动态与公告

产品动态

产品公告

产品简介

产品概述

功能概览

应用场景

产品优势

基本概念

地域和访问域名

规格与限制

产品计费

计费概述

计费方式

计费项

免费额度

计费示例

查看和下载账单

欠费说明

常见问题

快速入门

控制台快速入门

COSBrowser 快速入门

用户指南

创建请求

存储桶

对象

数据管理

批量处理

全球加速

监控与告警

运维中心

数据处理

内容审核

智能工具箱

数据工作流

应用集成

工具指南

工具概览

环境安装与配置

COSBrowser 工具

COSCLI 工具

COSCMD 工具

COS Migration 工具

FTP Server 工具

Hadoop 工具

COSDistCp 工具

HDFS TO COS 工具

GooseFS-Lite 工具

在线辅助工具

自助诊断工具

实践教程

概览

访问控制与权限管理

性能优化

使用 AWS S3 SDK 访问 COS

数据容灾备份

域名管理实践

图片处理实践

COS 音视频播放器实践

工作流实践

数据直传

内容审核实践

数据安全

数据校验

大数据实践

COS 成本优化解决方案

在第三方应用中使用 COS

迁移指南

本地数据迁移至 COS

第三方云存储数据迁移至 COS

以 URL 作为源地址的数据迁移至 COS

COS 之间数据迁移

Hadoop 文件系统与 COS 之间的数据迁移

数据湖存储

云原生数据湖

元数据加速

数据加速器 GooseFS

数据处理

数据处理概述

图片处理

媒体处理

内容审核

文件处理

文档处理

故障处理

获取 RequestId 操作指引

通过外网上传文件至 COS 缓慢

访问 COS 时返回403错误码

资源访问异常

POST Object 常见异常

API 文档

简介

公共请求头部

公共响应头部

错误码

请求签名

操作列表

Service 接口

Bucket 接口

Object 接口

批量处理接口

数据处理接口

任务与工作流

内容审核接口

云查毒接口

SDK 文档

SDK 概览

准备工作

Android SDK

C SDK

C++ SDK

.NET(C#) SDK

Flutter SDK

Go SDK

iOS SDK

Java SDK

JavaScript SDK

Node.js SDK

PHP SDK

Python SDK

React Native SDK

小程序 SDK

错误码

鸿蒙(Harmony) SDK

终端 SDK 质量优化

安全与合规

数据容灾

数据安全

访问管理

常见问题

热门问题

一般性问题

计费计量问题

域名合规问题

存储桶配置问题

域名和 CDN 问题

文件操作问题

日志监控问题

权限管理问题

数据处理问题

数据安全问题

预签名 URL 问题

SDK 类问题

工具类问题

API 类问题

服务协议

Service Level Agreement

隐私政策

数据处理和安全协议

联系我们

词汇表

快速入门

PDF

聚焦模式

字号

最后更新时间： 2025-12-29 16:25:44

相关资源
对象存储 COS 的 XML Go SDK 源码下载地址：XML Go SDK。
示例 Demo 下载地址：COS XML Go SDK 示例。
更多信息请参见 COS Go SDK API 文档。
SDK 文档中的所有示例代码请参见 SDK 代码示例。
SDK 更新日志请参见 ChangeLog。
SDK 常见问题请参见：Go SDK 常见问题。
说明：
如果您在使用 SDK 时遇到函数或方法不存在等错误，请先将 SDK 升级到最新版再重试。
环境配置与准备
Golang：用于下载和安装 Go 编译运行环境，请前往 Golang 官网进行下载。
最低支持的 Go 版本为1.16，推荐使用最新稳定版1.24.10。
您需要获取一个腾讯云 API 密钥，该密钥是您使用 COS SDK 各项功能的前提。
安装 SDK
执行以下命令安装 COS Go SDK。
go get -u github.com/tencentyun/cos-go-sdk-v5
初始化 COS 服务
下面为您介绍如何使用 COS Go SDK 完成一个基础操作，如初始化客户端、创建存储桶、查询存储桶列表、上传对象、查询对象列表、下载对象和删除对象。
初始化 COS
使用 COS 域名生成 COS Go 客户端 Client 结构。
方法原型
func NewClient(uri *BaseURL, httpClient *http.Client) *Client
参数说明
// BaseURL 访问各 API 所需的基础 URL
type BaseURL struct {
    // 访问 bucket, object 相关 API 的基础 URL（不包含 path 部分）: https://examplebucket-1250000000.cos.<Region>.myqcloud.com
    BucketURL *url.URL
    // 访问 service API 的基础 URL（不包含 path 部分）: https://cos.<Region>.myqcloud.com
    ServiceURL *url.URL
    // 访问 Batch API 的基础 URL （不包含 path 部分）: https://<UIN>.cos-control.<Region>.myqcloud.com
    BatchURL *url.URL
    // 访问 CI 的基础 URL （不包含 path 部分）: https://examplebucket-1250000000.ci.<Region>.myqcloud.com
    CIURL *url.URL
}
参数名称
参数描述
类型
是否必填
BucketURL
访问 bucket, object 相关 API 的基础 URL（不包含 path 部分）
string
是
ServiceURL
访问 service API 的基础 URL（不包含 path 部分）
string
否
BatchURL
访问 Batch API 的基础 URL （不包含 path 部分）
string
否
CIURL
访问 CI 的基础 URL （不包含 path 部分）
string
否
设置 API 访问密钥
访问密钥是 COS SDK 访问所有服务的前提，密钥分为：临时密钥和永久密钥。
注意：
建议用户使用子账号密钥 + 环境变量的方式调用 SDK，提高 SDK 使用的安全性。为子账号授权时，请遵循 最小权限指引原则，防止泄露目标存储桶或对象之外的资源。
如果您一定要使用永久密钥，建议遵循 最小权限指引原则 对永久密钥的权限范围进行限制。
临时密钥（推荐）
永久密钥
临时密钥生成和使用可参见 临时密钥生成及使用指引。
// 将 examplebucket-1250000000 和 COS_REGION 修改为真实的信息
// 存储桶名称，由 bucketname-appid 组成，appid 必须填入，可以在 COS 控制台查看存储桶名称。https://console.tencentcloud.com/cos5/bucket
// COS_REGION 可以在控制台查看，https://console.tencentcloud.com/cos5/bucket, 关于地域的详情见 https://www.tencentcloud.com/document/product/436/6224?from_cn_redirect=1
u, _ := url.Parse("https://examplebucket-1250000000.cos.COS_REGION.myqcloud.com")
b := &cos.BaseURL{BucketURL: u}
// 2.临时密钥
client := cos.NewClient(b, &http.Client{
    Transport: &cos.AuthorizationTransport{
        // 如果使用临时密钥需要填入，临时密钥生成和使用指引参见 https://www.tencentcloud.com/document/product/436/14048
        SecretID:     "SECRETID",
        SecretKey:    "SECRETKEY",
        SessionToken: "SECRETTOKEN",
    },
})
if client != nil {
    // 调用 COS 请求
}
﻿
// 将 examplebucket-1250000000 和 COS_REGION 修改为用户真实的信息
// 存储桶名称，由 bucketname-appid 组成，appid 必须填入，可以在 COS 控制台查看存储桶名称。https://console.tencentcloud.com/cos5/bucket
// COS_REGION 可以在控制台查看，https://console.tencentcloud.com/cos5/bucket, 关于地域的详情见 https://www.tencentcloud.com/document/product/436/6224?from_cn_redirect=1
u, _ := url.Parse("https://examplebucket-1250000000.cos.COS_REGION.myqcloud.com")
// 用于 Get Service 查询，默认全地域 service.cos.myqcloud.com
su, _ := url.Parse("https://cos.COS_REGION.myqcloud.com")
b := &cos.BaseURL{BucketURL: u, ServiceURL: su}
// 1.永久密钥
client := cos.NewClient(b, &http.Client{
    Transport: &cos.AuthorizationTransport{
        SecretID:  os.Getenv("SECRETID"),  // 用户的 SecretId，建议使用子账号密钥，授权遵循最小权限指引，降低使用风险。子账号密钥获取可参考 https://www.tencentcloud.com/document/product/598/37140?from_cn_redirect=1
        SecretKey: os.Getenv("SECRETKEY"), // 用户的 SecretKey，建议使用子账号密钥，授权遵循最小权限指引，降低使用风险。子账号密钥获取可参考 https://www.tencentcloud.com/document/product/598/37140?from_cn_redirect=1
    },
})
配置域名
通过修改 BaseURL，可以直接使用自定义域名或者全球加速域名访问 COS。
// 使用全球加速域名访问COS
u, _ := url.Parse("http://<BucketName-APPID>.cos.accelerate.myqcloud.com")
b := &cos.BaseURL{BucketURL: u}
// 2.临时密钥
client := cos.NewClient(b, &http.Client{
    Transport: &cos.AuthorizationTransport{
        // 如果使用临时密钥需要填入，临时密钥生成和使用指引参见 https://www.tencentcloud.com/document/product/436/14048
        SecretID:     "SECRETID",
        SecretKey:    "SECRETKEY",
        SessionToken: "SECRETTOKEN",
    },
})
CRC64校验（可选）
COS Go SDK 默认开启了文件上传 CRC64检验。
注意：
COS Go SDK 需要使用 v0.7.23及以上版本。
强烈建议用户不关闭 CRC64校验。
// 将 examplebucket-1250000000 和 COS_REGION 修改为真实的信息
// 存储桶名称，由 bucketname-appid 组成，appid 必须填入，可以在COS控制台查看存储桶名称。https://console.tencentcloud.com/cos5/bucket
// COS_REGION 可以在控制台查看，https://console.tencentcloud.com/cos5/bucket, 关于地域的详情见 https://www.tencentcloud.com/document/product/436/6224?from_cn_redirect=1
u, _ := url.Parse("https://examplebucket-1250000000.cos.COS_REGION.myqcloud.com")
b := &cos.BaseURL{BucketURL: u}
// 2.临时密钥
client := cos.NewClient(b, &http.Client{
    Transport: &cos.AuthorizationTransport{
        // 如果使用临时密钥需要填入，临时密钥生成和使用指引参见 https://www.tencentcloud.com/document/product/436/14048
        SecretID:     "SECRETID",
        SecretKey:    "SECRETKEY",
        SessionToken: "SECRETTOKEN",
    },
})
// 关闭 CRC64 校验
client.Conf.EnableCRC = false
﻿
访问 COS 服务
创建存储桶
查询存储桶列表
上传对象
查询对象列表
下载对象
删除对象
入门示例如下，更多示例 Demo 请参见 GitHub 地址。
package main
﻿
﻿
import (
    "context"
    "net/http"
    "net/url"
    "os"
﻿
    "github.com/tencentyun/cos-go-sdk-v5"
)
﻿
﻿
func main() {
    // 将 examplebucket-1250000000 和 COS_REGION 修改为真实的信息
    // 存储桶名称，由 bucketname-appid 组成，appid 必须填入，可以在 COS 控制台查看存储桶名称。https://console.tencentcloud.com/cos5/bucket
    // COS_REGION 可以在控制台查看，https://console.tencentcloud.com/cos5/bucket, 关于地域的详情见 https://www.tencentcloud.com/document/product/436/6224?from_cn_redirect=1
    u, _ := url.Parse("https://examplebucket-1250000000.cos.COS_REGION.myqcloud.com")
    b := &cos.BaseURL{BucketURL: u}
    c := cos.NewClient(b, &http.Client{
        Transport: &cos.AuthorizationTransport{
            SecretID:  os.Getenv("SECRETID"),  // 用户的 SecretId，建议使用子账号密钥，授权遵循最小权限指引，降低使用风险。子账号密钥获取可参考 https://www.tencentcloud.com/document/product/598/37140?from_cn_redirect=1
            SecretKey: os.Getenv("SECRETKEY"), // 用户的 SecretKey，建议使用子账号密钥，授权遵循最小权限指引，降低使用风险。子账号密钥获取可参考 https://www.tencentcloud.com/document/product/598/37140?from_cn_redirect=1
        },
    })
﻿
﻿
    _, err := c.Bucket.Put(context.Background(), nil)
    if err != nil {
        panic(err)
    }
}
入门示例如下，更多示例 Demo 请参见 GitHub 地址。
package main
﻿
﻿
import (
    "context"
    "fmt"
    "net/http"
    "os"
﻿
﻿
    "github.com/tencentyun/cos-go-sdk-v5"
)
﻿
﻿
func main() {
    c := cos.NewClient(nil, &http.Client{
        Transport: &cos.AuthorizationTransport{
            SecretID:  os.Getenv("SECRETID"),  // 用户的 SecretId，建议使用子账号密钥，授权遵循最小权限指引，降低使用风险。子账号密钥获取可参考 https://www.tencentcloud.com/document/product/598/37140?from_cn_redirect=1
            SecretKey: os.Getenv("SECRETKEY"), // 用户的 SecretKey，建议使用子账号密钥，授权遵循最小权限指引，降低使用风险。子账号密钥获取可参考 https://www.tencentcloud.com/document/product/598/37140?from_cn_redirect=1
        },
    })
﻿
﻿
    s, _, err := c.Service.Get(context.Background())
    if err != nil {
        panic(err)
    }
﻿
﻿
    for _, b := range s.Buckets {
        fmt.Printf("%#v\\n", b)
    }
}
入门示例如下，更多示例 Demo 请参见 GitHub 地址。
package main
﻿
﻿
import (
    "context"
    "net/http"
    "net/url"
    "os"
    "strings"
﻿
    "github.com/tencentyun/cos-go-sdk-v5"
)
﻿
﻿
func main() {
    // 将 examplebucket-1250000000 和 COS_REGION 修改为真实的信息
    // 存储桶名称，由 bucketname-appid 组成，appid 必须填入，可以在 COS 控制台查看存储桶名称。https://console.tencentcloud.com/cos5/bucket
    // COS_REGION 可以在控制台查看，https://console.tencentcloud.com/cos5/bucket, 关于地域的详情见 https://www.tencentcloud.com/document/product/436/6224?from_cn_redirect=1
    u, _ := url.Parse("https://examplebucket-1250000000.cos.COS_REGION.myqcloud.com")
    b := &cos.BaseURL{BucketURL: u}
    c := cos.NewClient(b, &http.Client{
        Transport: &cos.AuthorizationTransport{
            SecretID:  os.Getenv("SECRETID"),  // 用户的 SecretId，建议使用子账号密钥，授权遵循最小权限指引，降低使用风险。子账号密钥获取可参考 https://www.tencentcloud.com/document/product/598/37140?from_cn_redirect=1
            SecretKey: os.Getenv("SECRETKEY"), // 用户的 SecretKey，建议使用子账号密钥，授权遵循最小权限指引，降低使用风险。子账号密钥获取可参考 https://www.tencentcloud.com/document/product/598/37140?from_cn_redirect=1
        },
    })
    // 对象键（Key）是对象在存储桶中的唯一标识。
    // 例如，在对象的访问域名 `examplebucket-1250000000.cos.COS_REGION.myqcloud.com/test/objectPut.go` 中，对象键为 test/objectPut.go
    name := "test/objectPut.go"
    // 1.通过字符串上传对象
    f := strings.NewReader("test")
﻿
﻿
    _, err := c.Object.Put(context.Background(), name, f, nil)
    if err != nil {
        panic(err)
    }
    // 2.通过本地文件上传对象
    _, err = c.Object.PutFromFile(context.Background(), name, "../test", nil)
    if err != nil {
        panic(err)
    }
    // 3.通过文件流上传对象
    fd, err := os.Open("./test")
    if err != nil {
        panic(err)
    }
    defer fd.Close()
    _, err = c.Object.Put(context.Background(), name, fd, nil)
    if err != nil {
        panic(err)
    }
}
入门示例如下，更多示例 Demo 请参见 GitHub 地址。
package main
﻿
﻿
import (
    "context"
    "fmt"
    "net/http"
    "net/url"
    "os"
﻿
    "github.com/tencentyun/cos-go-sdk-v5"
)
﻿
﻿
func main() {
    // 将 examplebucket-1250000000 和 COS_REGION 修改为真实的信息
    // 存储桶名称，由 bucketname-appid 组成，appid 必须填入，可以在 COS 控制台查看存储桶名称。https://console.tencentcloud.com/cos5/bucket
    // COS_REGION 可以在控制台查看，https://console.tencentcloud.com/cos5/bucket, 关于地域的详情见 https://www.tencentcloud.com/document/product/436/6224?from_cn_redirect=1
    u, _ := url.Parse("https://examplebucket-1250000000.cos.COS_REGION.myqcloud.com")
    b := &cos.BaseURL{BucketURL: u}
    c := cos.NewClient(b, &http.Client{
        Transport: &cos.AuthorizationTransport{
            SecretID:  os.Getenv("SECRETID"),  // 用户的 SecretId，建议使用子账号密钥，授权遵循最小权限指引，降低使用风险。子账号密钥获取可参考 https://www.tencentcloud.com/document/product/598/37140?from_cn_redirect=1
            SecretKey: os.Getenv("SECRETKEY"), // 用户的 SecretKey，建议使用子账号密钥，授权遵循最小权限指引，降低使用风险。子账号密钥获取可参考 https://www.tencentcloud.com/document/product/598/37140?from_cn_redirect=1
        },
    })
﻿
﻿
    opt := &cos.BucketGetOptions{
        Prefix:  "test",
        MaxKeys: 3,
    }
    v, _, err := c.Bucket.Get(context.Background(), opt)
    if err != nil {
        panic(err)
    }
﻿
﻿
    for _, c := range v.Contents {
        fmt.Printf("%s, %d\\n", c.Key, c.Size)
    }
}
入门示例如下，更多示例 Demo 请参见 GitHub 地址。
package main
﻿
﻿
import (
    "context"
    "fmt"
    "io"
    "net/http"
    "net/url"
    "os"
﻿
    "github.com/tencentyun/cos-go-sdk-v5"
)
﻿
﻿
func main() {
    // 将 examplebucket-1250000000 和 COS_REGION 修改为真实的信息
    // 存储桶名称，由 bucketname-appid 组成，appid 必须填入，可以在 COS 控制台查看存储桶名称。https://console.tencentcloud.com/cos5/bucket
    // COS_REGION 可以在控制台查看，https://console.tencentcloud.com/cos5/bucket, 关于地域的详情见 https://www.tencentcloud.com/document/product/436/6224?from_cn_redirect=1
    u, _ := url.Parse("https://examplebucket-1250000000.cos.COS_REGION.myqcloud.com")
    b := &cos.BaseURL{BucketURL: u}
    c := cos.NewClient(b, &http.Client{
        Transport: &cos.AuthorizationTransport{
            SecretID:  os.Getenv("SECRETID"),  // 用户的 SecretId，建议使用子账号密钥，授权遵循最小权限指引，降低使用风险。子账号密钥获取可参考 https://www.tencentcloud.com/document/product/598/37140?from_cn_redirect=1
            SecretKey: os.Getenv("SECRETKEY"), // 用户的 SecretKey，建议使用子账号密钥，授权遵循最小权限指引，降低使用风险。子账号密钥获取可参考 https://www.tencentcloud.com/document/product/598/37140?from_cn_redirect=1
        },
    })
    // 1.通过响应体获取对象
    name := "test/objectPut.go"
    resp, err := c.Object.Get(context.Background(), name, nil)
    if err != nil {
        panic(err)
    }
    bs, _ := io.ReadAll(resp.Body)
    resp.Body.Close()
    fmt.Printf("%s\\n", string(bs))
    // 2.获取对象到本地文件
    _, err = c.Object.GetToFile(context.Background(), name, "exampleobject", nil)
    if err != nil {
        panic(err)
    }
}
入门示例如下，更多示例 Demo 请参见 GitHub 地址。
注意：
对象被删除后，其对应的数据将无法再被访问。
package main
﻿
﻿
import (
    "context"
    "net/http"
    "net/url"
    "os"
﻿
    "github.com/tencentyun/cos-go-sdk-v5"
)
﻿
﻿
func main() {
    // 将 examplebucket-1250000000 和 COS_REGION 修改为真实的信息
    // 存储桶名称，由 bucketname-appid 组成，appid 必须填入，可以在 COS 控制台查看存储桶名称。https://console.tencentcloud.com/cos5/bucket
    // COS_REGION 可以在控制台查看，https://console.tencentcloud.com/cos5/bucket, 关于地域的详情见 https://www.tencentcloud.com/document/product/436/6224?from_cn_redirect=1
    u, _ := url.Parse("https://examplebucket-1250000000.cos.COS_REGION.myqcloud.com")
    b := &cos.BaseURL{BucketURL: u}
    c := cos.NewClient(b, &http.Client{
        Transport: &cos.AuthorizationTransport{
            SecretID:  os.Getenv("SECRETID"),  // 用户的 SecretId，建议使用子账号密钥，授权遵循最小权限指引，降低使用风险。子账号密钥获取可参考 https://www.tencentcloud.com/document/product/598/37140?from_cn_redirect=1
            SecretKey: os.Getenv("SECRETKEY"), // 用户的 SecretKey，建议使用子账号密钥，授权遵循最小权限指引，降低使用风险。子账号密钥获取可参考 https://www.tencentcloud.com/document/product/598/37140?from_cn_redirect=1
        },
    })
    name := "test/objectPut.go"
    _, err := c.Object.Delete(context.Background(), name)
    if err != nil {
        panic(err)
    }
}
常见问题
您在使用过程中可能会碰到的一些常见问题，相关的解决办法可参见 Go SDK 常见问题。

帮助和支持

本页内容是否解决了您的问题？

您也可以联系销售或提交工单以寻求帮助。

填写满意度调查问卷，共创更好文档体验。

文档反馈

参数名称	参数描述	类型	是否必填
BucketURL	访问 bucket, object 相关 API 的基础 URL（不包含 path 部分）	string	是
ServiceURL	访问 service API 的基础 URL（不包含 path 部分）	string	否
BatchURL	访问 Batch API 的基础 URL （不包含 path 部分）	string	否
CIURL	访问 CI 的基础 URL （不包含 path 部分）	string	否

tencent cloud

对象存储

快速入门

相关资源

环境配置与准备

安装 SDK

初始化 COS 服务

初始化 COS

方法原型

参数说明

设置 API 访问密钥

配置域名

CRC64校验（可选）

访问 COS 服务

常见问题

帮助和支持