腾讯云 COS 配置教程：Bucket 含 APPID 的格式坑与地域填写

学完这篇，你能把腾讯云 COS 在后台一次配对，不再被「Bucket 名要不要带 APPID」「地域填中文还是英文」这两个问题卡住。

第一步：先把三样东西从腾讯云控制台抄出来

登录腾讯云 → 对象存储 COS → 存储桶列表，找到你要用的桶，一次性记下：

• Bucket 全名：形如 `myforum-1258000000`
• 地域：形如 `ap-guangzhou`（控制台显示为「广州」）
• 密钥：访问管理 CAM → API 密钥管理，拿 SecretId 和 SecretKey

再去后台「系统设置 → 云存储」选择腾讯云 COS，把上面四项填进去，保存即生效，不用清缓存。

注意：SecretKey 只在创建时完整显示一次，当时没存就只能重新生成一对。别把 SecretId 和 SecretKey 填反——两者长度和开头字符不一样，填反了报错信息不会明说是填反了。

第二步：搞清楚 Bucket 名到底带不带 APPID

这是最容易翻车的地方。腾讯云 COS 的存储桶全名本身就是「自定义名-APPID」，中间一个短横线，比如你起的名字叫 `forum`、账号 APPID 是 `1258000000`，那完整名字就是：

forum-1258000000

所以关键看后台那个输入框要什么：

• 输入框提示「存储桶名称 / Bucket」→ 通常填全名（带 `-APPID`）
• 输入框提示「存储桶前缀 / 自定义名」，并且旁边另有单独的 APPID 输入框 → 这里只填 `forum`，APPID 填另一格

注意：三种写法都填不对会得到不同报错——只填 `forum` 报 `NoSuchBucket`；重复拼成 `forum-1258000000-1258000000` 也报 `NoSuchBucket`；名字对但大小写错、或用了下划线（COS 桶名只允许小写字母、数字、短横线）同样报错。填之前先回控制台把桶名整行复制一次，最稳。

第三步：地域填英文代号，不是城市名

COS 的地域必须填 API 用的英文代号：

注意：填「广州」「gz」「广州三区」都不行；`ap-guangzhou-2` 这种带数字的可用区写法也不是地域码。另外地域必须和桶的实际所在地域一致，桶在广州你填上海，签名会直接失败。

第四步：填访问域名（可选但建议）

默认域名格式是固定的：

https://存储桶全名.cos.地域.myqcloud.com

例如 `https://forum-1258000000.cos.ap-guangzhou.myqcloud.com`。如果你绑了 CDN 或自定义域名，就填自己的那一个，注意要带 `https://`。

注意：默认域名适合测试，正式站点建议开 CDN，否则图片全走 COS 源站会产生外网下行流量费用。

第五步：配权限和跨域

• 存储桶权限：想让图片直接显示，选「公有读私有写」；想全部走签名链接，选「私有读写」
• 跨域 CORS：在桶的「安全管理 → 跨域访问 CORS 设置」里加一条，来源填你的站点域名，允许方法勾 GET/PUT/POST，允许头部填 `*`

注意：CORS 没配的话，后台能上传成功但前端直传会报跨域错误，控制台通常不会有明显提示，只会看到请求被浏览器拦下。

第六步：发一帖带图验证

回前台发一个带图片的帖子，然后做两个检查：图片能正常显示；去 COS 控制台的文件列表里能看到刚上传的文件。两边都对，说明链路通了。

如果报错，按这个顺序看：

• `SignatureDoesNotMatch` → 密钥错了，或者 SecretKey 前后带了空格
• `NoSuchBucket` → Bucket 名格式问题（重点看第二步）
• `AccessDenied` → 密钥所属账号没有该桶的权限，去 CAM 授权
• `403` 且控制台有文件 → 桶权限设成了私有读写，但前台用的是默认域名访问

小结

• Bucket 全名 = 自定义名 + `-` + APPID，先看后台输入框要全名还是拆分填，再决定怎么写
• 地域填 `ap-` 开头的英文代号，必须与桶实际地域一致
• 密钥只在创建时完整可见，填完先本地存一份
• 权限和 CORS 是两个独立开关，上传成功不等于访问正常
• 配完发一帖实拍验证，比盯着控制台猜快得多