Go配置客户端 - 对象存储 OSS

Client是OSS的Go客户端，用于管理存储空间和文件等OSS资源。使用Go SDK发起OSS请求时，您需要初始化一个Client实例，并根据需要修改默认配置项。

前提条件

初始化OSS SDK前，您需要配置访问凭证。详情请参见配置访问凭证。

新建Client

V4签名（推荐）

推荐使用更安全的V4签名算法。使用V4签名初始化时，除指定Endpoint以外，您还需要指定阿里云通用Region ID作为发起请求地域的标识，示例值为cn-hangzhou。同时声明oss.AuthV4。OSS Go SDK 3.0.2及以上版本支持V4签名。

以使用OSS域名初始化时使用V4签名为例，其他通过自定义域名等初始化的场景可参考以下示例执行相应修改。

package main

import (
	"log"

	"github.com/aliyun/aliyun-oss-go-sdk/oss"
)

// handleError 用于处理不可恢复的错误，并记录错误信息后终止程序。
func handleError(err error) {
	log.Fatalf("Error: %v", err)
}

// setupClient 用于设置并创建OSS客户端实例。
// 参数：
//
//	endpoint - Bucket对应的Endpoint。
//	region - Endpoint对应的Region信息。
//
// 返回创建的OSS客户端实例。
func setupClient(endpoint, region string) (*oss.Client, error) {
	// 从环境变量中获取访问凭证。
	provider, err := oss.NewEnvironmentVariableCredentialsProvider()
	if err != nil {
		return nil, err
	}

	// 创建OSSClient实例，并使用V4签名。
	client, err := oss.New(endpoint, "", "", oss.SetCredentialsProvider(&provider), oss.AuthVersion(oss.AuthV4), oss.Region(region))
	if err != nil {
		return nil, err
	}

	return client, nil
}

func main() {
	// yourEndpoint填写Bucket对应的Endpoint，以华东1（杭州）为例，填写为https://oss-cn-hangzhou.aliyuncs.com。其它Region请按实际情况填写。
	endpoint := "yourEndpoint"

	// yourRegion填写Endpoint对应的Region信息，例如cn-hangzhou。
	region := "yourRegion"

	// 检查环境变量是否已经设置。
	if endpoint == "" || region == "" {
		log.Fatal("Please set yourEndpoint and yourRegion.")
	}

	// 设置并创建OSS客户端实例。
	client, err := setupClient(endpoint, region)
	if err != nil {
		handleError(err)
	}

	// 输出客户端信息。
	log.Printf("Client: %#v\n", client)
}

V1签名（不推荐）

重要

阿里云对象存储OSS自2025年03月01日起不再对新用户（即新UID ）开放使用V1签名，并将于2025年09月01日起停止更新与维护且不再对新增Bucket开放使用V1签名。请尽快切换到V4签名，避免影响服务。更多信息，请参见公告链接。

使用OSS域名新建Client

以下代码用于使用OSS域名初始化。关于不同地域的OSS域名，请参见OSS地域和访问域名。

package main

import (
	"log"

	"github.com/aliyun/aliyun-oss-go-sdk/oss"
)

// handleError 用于处理不可恢复的错误，并记录错误信息后终止程序。
func handleError(err error) {
	log.Fatalf("Error: %v", err)
}

// setupClient 用于设置并创建OSS客户端实例。
// 参数：
//
//	endpoint - Bucket对应的Endpoint。
//
// 返回创建的OSS客户端实例。
func setupClient(endpoint string) (*oss.Client, error) {
	// 从环境变量中获取访问凭证。
	provider, err := oss.NewEnvironmentVariableCredentialsProvider()
	if err != nil {
		return nil, err
	}

	// 创建OSSClient实例。
	// yourRegion填写Bucket所在地域，以华东1（杭州）为例，填写为cn-hangzhou。其它Region请按实际情况填写。
	clientOptions := []oss.ClientOption{oss.SetCredentialsProvider(&provider)}
	clientOptions = append(clientOptions, oss.Region("yourRegion"))
	// 设置签名版本
	clientOptions = append(clientOptions, oss.AuthVersion(oss.AuthV4))
	client, err := oss.New(endpoint, "", "", clientOptions...)
	if err != nil {
		return nil, err
	}

	return client, nil
}

func main() {
	// yourEndpoint填写Bucket对应的Endpoint，以华东1（杭州）为例，填写为https://oss-cn-hangzhou.aliyuncs.com。其它Region请按实际情况填写。
	endpoint := "yourEndpoint"

	// 检查环境变量是否已经设置。
	if endpoint == "" {
		log.Fatal("Please set yourEndpoint.")
	}

	// 设置并创建OSS客户端实例。
	client, err := setupClient(endpoint)
	if err != nil {
		handleError(err)
	}

	// 输出客户端信息。
	log.Printf("Client: %#v\n", client)
}

使用自定义域名新建Client

以下代码用于使用自定义域名新建Client。关于使用自定义域名访问OSS的更多信息，请参见绑定自定义域名至Bucket默认域名。

重要

使用自定义域名时无法使用ossClient.listBuckets方法。

package main

import (
	"log"

	"github.com/aliyun/aliyun-oss-go-sdk/oss"
)

// handleError 用于处理不可恢复的错误，并记录错误信息后终止程序。
func handleError(err error) {
	log.Fatalf("Error: %v", err)
}

// setupClient 用于设置并创建OSS客户端实例，支持CNAME。
// 参数：
//
//	endpoint - 自定义域名，即绑定到存储空间的自定义域名。
//
// 返回创建的OSS客户端实例。
func setupClient(endpoint string) (*oss.Client, error) {
	// 从环境变量中获取访问凭证。
	provider, err := oss.NewEnvironmentVariableCredentialsProvider()
	if err != nil {
		return nil, err
	}

	// 创建OSSClient实例，并启用CNAME支持。
	// yourRegion填写Bucket所在地域，以华东1（杭州）为例，填写为cn-hangzhou。其它Region请按实际情况填写。
	clientOptions := []oss.ClientOption{oss.SetCredentialsProvider(&provider)}
	clientOptions = append(clientOptions, oss.Region("yourRegion"))
	clientOptions = append(clientOptions, oss.UseCname(true))
	// 设置签名版本
	clientOptions = append(clientOptions, oss.AuthVersion(oss.AuthV4))
	client, err := oss.New(endpoint, "", "", clientOptions...)
	if err != nil {
		return nil, err
	}

	return client, nil
}

func main() {
	// yourEndpoint填写Bucket对应的自定义域名。
	// 示例：填写为 "custom-domain-for-your-bucket.com"。
	endpoint := "yourEndpoint"

	// 检查环境变量是否已经设置。
	if endpoint == "" {
		log.Fatal("Please set yourEndpoint.")
	}

	// 设置并创建OSS客户端实例，支持CNAME。
	client, err := setupClient(endpoint)
	if err != nil {
		handleError(err)
	}

	// 输出客户端信息。
	log.Printf("Client: %#v\n", client)
}

配置Client

您可以通过Client配置代理、连接超时、最大连接数等参数。

参数	描述	方法
MaxIdleConns	最大闲置连接数。默认值为100。	oss.MaxConns
MaxIdleConnsPerHost	每个主机的最大闲置连接数。默认值为100。	oss.MaxConns
MaxConnsPerHost	每个主机的最大连接数。默认为空。	oss.MaxConns
ConnectTimeout	HTTP超时时间，单位为秒。默认值为10秒，0表示不超时。	oss.Timeout
ReadWriteTimeout	HTTP读取或写入超时时间，单位为秒。默认值为20秒，0表示不超时。	oss.Timeout
IsCname	是否支持将自定义域名作为Endpoint，默认不支持。	oss.UseCname
UserAgent	设置HTTP的User-Agent头，默认值为aliyun-sdk-go。	oss.UserAgent
ProxyHost	是否开启代理服务器主机地址和端口。取值如下： true：开启代理服务器主机地址和端口。 false（默认值）：关闭代理服务器主机地址和端口。	oss.AuthProxy
ProxyUser	代理服务器验证的用户名。	oss.AuthProxy
ProxyPassword	代理服务器验证的密码。	oss.AuthProxy
RedirectEnabled	设置是否开启HTTP重定向。取值如下： true（默认值）：开启HTTP重定向。 false：关闭HTTP重定向。	oss.RedirectEnabled
InsecureSkipVerify	设置是否开启SSL证书校验。取值如下： true（默认值）：忽略SSL证书校验。 false：开启SSL证书校验。	oss.InsecureSkipVerify
IsEnableCRC	是否开启CRC数据校验。取值如下： true（默认值）：开启CRC数据校验。 false：关闭CRC数据校验。重要强烈建议不要关闭CRC数据校验功能。如果您关闭此功能，则阿里云不保证上传、下载过程数据的完整性。	oss.EnableCRC
LogLevel	设置日志模式。取值如下： oss.LogOff oss.Debug oss.Error oss.Warn oss.Info	oss.SetLogLevel

配置示例如下：

package main

import (
	"log"

	"github.com/aliyun/aliyun-oss-go-sdk/oss"
)

// handleError 用于处理不可恢复的错误，并记录错误信息后终止程序。
func handleError(err error) {
	log.Fatalf("Error: %v", err)
}

// setupClient 用于设置并创建OSS客户端实例。
// 参数：
//
//	endpoint - Bucket对应的Endpoint。
//
// 返回创建的OSS客户端实例。
func setupClient(endpoint string) (*oss.Client, error) {
	// 从环境变量中获取访问凭证。
	provider, err := oss.NewEnvironmentVariableCredentialsProvider()
	if err != nil {
		return nil, err
	}

	// 设置连接数为10，每个主机的最大闲置连接数为20，每个主机的最大连接数为20。
	conn := oss.MaxConns(10, 20, 20)

	// 设置HTTP连接超时时间为20秒，HTTP读取或写入超时时间为60秒。
	time := oss.Timeout(20, 60)

	// 设置是否支持将自定义域名作为Endpoint，默认不支持。
	cname := oss.UseCname(true)

	// 设置HTTP的User-Agent头，默认为aliyun-sdk-go。
	userAgent := oss.UserAgent("aliyun-sdk-go")

	// 设置是否开启HTTP重定向，默认开启。
	redirect := oss.RedirectEnabled(true)

	// 设置是否开启SSL证书校验，默认忽略。
	verifySsl := oss.InsecureSkipVerify(false)

	// 设置代理服务器地址和端口。
	// proxy := oss.Proxy("yourProxyHost")

	// 设置代理服务器的主机地址和端口，代理服务器验证的用户名和密码。
	authProxy := oss.AuthProxy("yourProxyHost", "yourProxyUserName", "yourProxyPassword")

	// 开启CRC加密。
	crc := oss.EnableCRC(true)

	// 设置日志模式。
	logLevel := oss.SetLogLevel(oss.LogOff)

	// 创建OSSClient实例。
	// yourRegion填写Bucket所在地域，以华东1（杭州）为例，填写为cn-hangzhou。其它Region请按实际情况填写。
	client, err := oss.New(endpoint, "", "", oss.SetCredentialsProvider(&provider), oss.Region("yourRegion"), oss.AuthVersion(oss.AuthV4),
		conn, time, cname, userAgent, authProxy, verifySsl, redirect, crc, logLevel)
	if err != nil {
		return nil, err
	}

	return client, nil
}

func main() {
	// yourEndpoint填写Bucket对应的Endpoint，以华东1（杭州）为例，填写为https://oss-cn-hangzhou.aliyuncs.com。其它Region请按实际情况填写。
	endpoint := "yourEndpoint"

	// 检查环境变量是否已经设置。
	if endpoint == "" {
		log.Fatal("Please set yourEndpoint.")
	}

	// 设置并创建OSS客户端实例。
	client, err := setupClient(endpoint)
	if err != nil {
		handleError(err)
	}

	// 输出客户端信息。
	log.Printf("Client: %#v\n", client)
}

设置请求上下文

您可以通过请求上下文控制和管理请求的生命周期，以及传递请求相关的上下文信息。

以下代码用于设置请求上下文。仅OSS Go SDK 2.2.9及以上版本支持设置请求上下文。

package main

import (
	"context"
	"fmt"
	"log"
	"time"

	"github.com/aliyun/aliyun-oss-go-sdk/oss"
)

// handleError 用于处理不可恢复的错误，并记录错误信息后终止程序。
func handleError(err error) {
	log.Fatalf("Error: %v", err)
}

// uploadFile 用于将本地文件上传到OSS存储桶。
// 参数：
//
//	bucketName - 存储空间名称。
//	objectName - Object完整路径，完整路径中不包含Bucket名称。
//	localFileName - 本地文件的完整路径。
//	endpoint - Bucket对应的Endpoint。
//
// 如果成功，记录成功日志；否则，返回错误。
func uploadFile(bucketName, objectName, localFileName, endpoint string) error {
	// 从环境变量中获取访问凭证。
	provider, err := oss.NewEnvironmentVariableCredentialsProvider()
	if err != nil {
		return err
	}

	// 创建OSSClient实例。
	// yourRegion填写Bucket所在地域，以华东1（杭州）为例，填写为cn-hangzhou。其它Region请按实际情况填写。
	client, err := oss.New(endpoint, "", "", oss.SetCredentialsProvider(&provider), oss.Region("yourRegion"), oss.AuthVersion(oss.AuthV4))
	if err != nil {
		return err
	}

	// 获取存储空间。
	bucket, err := client.Bucket(bucketName)
	if err != nil {
		return err
	}

	// 设置请求上下文。
	ctx := context.Background()

	// 指定请求上下文过期时间。
	ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
	defer cancel()

	// 将本地文件上传至OSS。
	err = bucket.PutObjectFromFile(objectName, localFileName, oss.WithContext(ctx))
	if err != nil {
		select {
		case <-ctx.Done():
			return fmt.Errorf("Request cancelled or timed out")
		default:
			return err
		}
	}

	// 文件上传成功后，记录日志。
	log.Printf("File uploaded successfully: %s/%s", bucketName, objectName)
	return nil
}

func main() {
	// yourEndpoint填写Bucket对应的Endpoint，以华东1（杭州）为例，填写为https://oss-cn-hangzhou.aliyuncs.com。其它Region请按实际情况填写。
	endpoint := "yourEndpoint"

	// 填写存储空间名称，例如examplebucket。
	bucketName := "examplebucket"

	// yourObjectName填写Object完整路径，完整路径中不包含Bucket名称。
	objectName := "yourObjectName"

	// yourLocalFile填写本地文件的完整路径。
	localFileName := "yourLocalFile"

	// 检查环境变量是否已经设置。
	if endpoint == "" || bucketName == "" || objectName == "" || localFileName == "" {
		log.Fatal("Please set yourEndpoint, bucketName, objectName, and localFileName.")
	}

	// 尝试上传文件，如果失败则处理错误。
	if err := uploadFile(bucketName, objectName, localFileName, endpoint); err != nil {
		handleError(err)
	}

	// 输出上传成功的消息。
	log.Println("Upload Success!")
}