腾讯云 COS 接入配置说明

一、目标

将小程序、管理端、富文本图片统一接入腾讯云 COS，对外统一使用：

https://xxxxx.cn/{objectKey}

至于当前桶信息，

• 存储桶的观点是，xxxxx-img-blog-xxxxx
• 再看地域。ap-guangzhou
• 自定义访问域名：img.xxxxx.cn

二、接入后的图片链路

至于上传链路，

前端/管理端上传 -> 后端上传 COS -> COS 存储对象

从访问链路来看，

前端/小程序访问 https://img.xxxxx.cn/{objectKey}

常见痛点：

• 数据库里存的是 objectKey 而不是完整 URL，容易导致迁移时出现“URL 拼接错误”的报错。
• 后端未统一拼接完整 URL，导致不同模块返回格式不一致。
• 更换域名后忘记修改后端配置，导致所有图片失效。

说到提示。确保后端统一拼接 URL，并在迁移域名时优先改环境变量而非代码。说起来，

三、前提条件

• 已开通腾讯云 COS 服务。
• 已创建图片存储桶。
• 已准备好可用域名 img.xxxxx.cn.
• 已具备 HTTPS 证书。
• 后端已支持 COS 上传、删除、URL 拼接。

四、COS 控制台配置步骤

. 创建存储桶

Pain Point: 很多人误把访问类型设为“公有读公有写”，导致敏感信息泄露。说起来，请务必选择“公有读私有写”。

方法：

腾讯云 COS 控制台 -> 存储桶列表 -> 创建存储桶

建议配置：

• Name这方面。自己命名
• COS Region: 与业务所在地区保持一致Access Type: 公有读私有写
• - 注意不要选公有读公有写，否则所有人都能上传删除。说起来，

. 配置访问权限

Pain Point: 有些开发者只在 Bucket ACL 设置了 “private”。但却想让浏览器直接访问图片，结果报错 “AccessDenied”。请确认 ACL 为 public-read。

COS 控制台 -> 存储桶详情 -> 权限管理
Bucket ACL：public-read

. 配置自定义源站域名

Pain Point: 忘记开启 HTTPS 或者没有正确绑定证书，会导致浏览器警告或小程序无法加载图片。按理说，

COS 控制台 → 存储桶详情 → 域名与传输管理 → 自定义源站域名
Domain: img.xxxxx.cn
Source Type: REST

*如果要切换到 CDN。只需把此记录指向 CDN 的 CNAME 即可，无需改动后台代码。*

. 配置 DNS 解析

域名 DNS 控制台 → 新增解析记录
再看主机记录，img
至于记录类型，CNAME
至于记录值。
指向 COS 给出的 cname，如 cn-shenzhen.cos.myqcloud.com`

注意：DNS 生效时间可能长达几分钟，请耐心等待并确认解析是否正常。

. 配置 HTTPS 证书

COS 控制台 → 存储桶详情 → 域名与传输管理 → HTTPS 配置
绑定 img.xxxxx.cn 对应证书。

HTTPS 一旦生效可能需要几分钟，请关注控制台通知。`

. 配置防盗链

• 从Status来看，开启；Mode：Referer 白名单；怎么说呢，Whitelist：
  • * .xxxxx.cn
  • .servicewechat.com
  • .xxxxx.com
  • .servicewechat.com *
  • 如果你想允许直接在浏览器地址栏打开图片。需要把空 Referer 加进去，否则会被拦截。

    常见问题： 当防盗链设置过于严格时小程序或后台接口可能因 Referer 不匹配而无法加载图像。适当放宽白名单可解决此问题。*

    . 配置跨域 CORS

    Pain Point：缺少 CORS 配置会导致前端直接请求失败，“No 'Access-Control-Allow-Origin' header is present on requested resource”。请按业务需求开放 GET/HEAD；若需浏览器直传，需要再开放 PUT/POST。

    COS 控制台 → 存储桶详情 → 安全管理 → 跨域访问 CORS 设置
    AllowedOrigin：
    AllowedMethod：
    
    
    ✕ GET / HEAD / PUT / POST
    AllowedHeader:*
    ExposeHeader:*
    MaxAgeSeconds:3600
    
    

    . 配置监控告警

    Pain Point : 未设置告警会错过突发流量暴涨导致服务不可用的风险。建议至少监控吞吐量和错误率。其实，

    腾讯云监控/告警中心 -> 针对 COS 配置告警策略
    再看默认阈值示例，5000MB/分钟
    再看通知方式。手机短信 / 邮件 / Webhook

    五、后端对应配置

    Pain Point : 在多环境部署中，硬编码 bucket/domain 会造成跨环境数据混乱。请使用环境变量或统一配置文件来切换不同环境的 bucket/domain。

    yjx的观点是，cos: secret-id: ${YJX_COS_SECRET_ID} secret-key: ${YJX_COS_SECRET_KEY} region这方面，${YJX_COS_REGION:-ap-guangzhou} bucket这方面，${YJX_COS_BUCKET} domain这方面，${YJX_COS_DOMAIN}
    • The bucket value must be full bucket name.
    • The domain value is used by backend to build full image URLs.
    • If you change image domain later。simply modify YJXCOSDOMAIN – no code changes required.
    Tip的观点是，If you encounter “NoSuchKey” errors after migrating domains,verify that your database still stores objectKeys correctly.

。

---