腾讯云国际站（云老大）：COS 防盗链一开图片就 403？Referer 规则和签名 URL 这样配置才生效

COS防盗链图片无法访问？先搞懂防盗链机制与拦截逻辑

图片突然全站裂开、小程序里一片空白、CDN加速后反而403——这些问题有一半指向同一个源头：COS防盗链配置与业务访问场景的错配。腾讯云COS的防盗链机制并不复杂，但开启后“图片无法访问”的坑往往源于对Referer校验逻辑和空Referer处理的误判。搞清楚它的工作原理和边界，是恢复访问的第一步。

本文由 云国际站代理商『云老大 飞弟：@yunlaoda360 / YunLaoDa-服务器服务商•撰写』如需转载请注明！

什么是COS防盗链？为何图片无法访问？

COS防盗链本质上是一套基于HTTP Referer请求头的访问控制策略。用户向COS请求图片时，请求头中的Referer字段会标明这次请求是从哪个页面跳转过来的。COS拿到这个值后与白名单做匹配：匹配成功则放行，不在白名单或Referer缺失则直接返回403，图片自然无法加载。这套机制简单、通用，但它是“防君子”的——Referer可以被伪造，不能用于高安全场景的身份校验。

为什么开启防盗链后，正常页面的图片也全部裂开了？

最常见的原因是白名单域名填写不全，以及“允许空Referer”开关被关闭。从浏览器地址栏直接访问图片URL、从HTTPS页面跳转到HTTP链接、部分浏览器的隐私模式，这些场景下请求头都不会携带Referer字段。一旦你关掉了“允许空Referer”，COS就会把这些合法来源等同于盗链请求进行拦截。一个典型的误操作就是：只添加了www.example.com，却忽略了裸域名example.com或移动端m.example.com的访问，结果PC正常、手机端全挂。

手机App和小程序里图片无法访问，是什么原因？

原生App和微信小程序的网络请求通常由代码发起，默认不会自动带上Referer头。当存储桶的防盗链规则拒绝了所有空Referer请求，App内图片便直接403。解决思路有两条：一是勾选“允许空Referer”，但这会降低防盗链的拦截效果；更稳妥的做法是将存储桶设为私有读写，由后端服务生成带签名的临时URL下发给App，签名URL自带授权信息，可以绕过Referer白名单的校验。这种做法完全不依赖Referer机制，也避免了外链盗用问题。

排查COS防盗链图片无法访问的常见原因

当防盗链配置上线后，图片大面积裂开的情况并不少见。表面上看是Referer白名单设错了，但实际排查中往往涉及多层配置的交叉影响。业务侧反馈“图片挂了”时，运维需要快速判断问题究竟出在规则逻辑、签名有效性，还是CDN回源链路上。

检查Referer规则设置

Referer白名单的配置陷阱比多数人预想的要多。除了域名拼写这类低级错误，最常见的故障点是“允许空Referer”这个选项。腾讯云COS控制台默认关闭该选项，意味着所有不携带Referer头的请求——包括App原生调用、curl命令行、浏览器隐私模式、以及从HTTPS页面跳转到HTTP资源时——都会被直接拒绝。某电商团队在一次大促前开启防盗链，上线后小程序端商品图全部加载失败，回滚日志发现请求头中Referer字段为空，而白名单配置本身并无问题。另一个容易被忽略的细节是通配符的作用域：*.example.com可以覆盖所有子域名，但对裸域example.com不生效，两者必须同时加入白名单。用IP地址访问COS的场景也值得注意，因为COS的虚拟主机机制本身不支持IP直连，测试时浏览器报“连接重置”并不代表防盗链在拦截，把这两种错误混淆是让排查走弯路的常见原因。

检查签名URL是否有效

如果业务流量中混合了网页外链和App调用，签名URL与Referer白名单的互斥逻辑就会成为故障高发区。签名URL的有效期由生成时指定的Expires参数决定，一旦过期，即使Referer白名单配置正确也会返回403。更隐蔽的问题是签名参数拼接错误——某SaaS平台曾因后端代码中对URL做了二次编码，导致q-signature参数被破坏，图片在网页端能正常展示、App端间歇性403，排查两天才发现是签名生成逻辑的字符转义缺陷。需要明确一个技术事实：携带有效签名的请求会绕过Referer校验，这是COS的底层鉴权顺序决定的。如果业务既需要白名单保护网页外链、又需要签名URL服务App端，必须在生成签名的代码中做好异常捕获和日志记录，否则图片间歇性可访问会让故障定位异常困难。

缓存与CDN影响

CDN节点的介入会彻底改变Referer头的传递链路。典型场景是这样的：用户浏览器向CDN发起请求，Referer是业务域名；CDN回源COS时，回源请求的Referer变成了CDN加速域名本身。如果运维只在COS白名单中配置了业务域名而遗漏了CDN域名，源站会判定回源请求来自未授权来源并返回403，CDN拿到403后将其缓存，导致全量用户看到裂图。解决这个问题需要在COS白名单中“双写”——同时加入源站域名和CDN加速域名，并在CDN控制台检查回源Host配置是否与源站期望一致。某内容社区在接入CDN后出现部分地区图片加载失败，最终定位到是该区域CDN节点的回源Referer传递了HTTPS变体域名，而白名单只配了HTTP版本，这种域名协议不一致引发的拒绝案例在实际运维中相当典型。

如何配置COS Referer防盗链规则？

配置COS防盗链并不是简单勾选一个开关就能收工的事情。这套基于HTTP Referer头的控制逻辑虽然标准，但在混合场景（浏览器访问、App调用、CDN回源）下常会出现“配置完图片反而裂了”的状况。根本原因在于，COS防盗链依赖的是客户端请求中携带的Referer字段，而不同环境下的请求行为差异巨大。

添加域名白名单方法

进入COS控制台对应存储桶，在“安全管理-防盗链设置”中开启Referer防盗链并添加白名单域名。域名填写格式不带协议头，例如www.example.com。完成添加后，只有从该域名的页面发起请求（Referer匹配www.example.com）才能正常加载图片。测试时可直接在已声明白名单域名的网站嵌图，或使用curl -e "https://www.example.com"模拟来源，返回200即为配置生效。需要特别注意，白名单仅对域名访问方式有效，IP直连COS或直接访问COS默认域名（bucket-appid.cos.region.myqcloud.com）通常因Referer匹配不上而被拒，建议配合自定义已备案域名使用。

通配符设置技巧

白名单支持*通配符，但规则与直觉略有差异。腾讯云COS允许*.example.com匹配所有子域名，例如静态资源放在img.example.com和static.example.com都能覆盖。但裸*全量匹配虽在部分云厂商支持，在腾讯云控制台却无法直接添加，也不建议尝试，因为这会无视一切来源，等同于关闭防护。实践中稳妥的做法是同时添加example.com和*.example.com两条记录：前者精确匹配裸域名直接访问场景，后者囊括所有子域。如果公司业务划分出多个独立主域名（如example.cn与example.com），需逐一录入，一个星号跨主域是行不通的。此外，通配符配置对于IP访问和Referer为空的情况仍然无效，这两类流量要独立开启“允许空Referer”开关或其他绕过策略才能正常访问。

配置时的注意事项

最容易被忽视的坑，是“允许空Referer”开关的默认状态。控制台开启防盗链时该选项默认勾选，如果你是一个典型Web站点，保持勾选即可，避免浏览器直接输入图片URL或隐私模式下访问被拦。但某些安全策略要求拒绝无来源请求，一旦关闭此选项，所有原生App、小程序、服务端curl等不带Referer头的请求将会全部返回403，图片大面积不可访问。第二个常见问题是CDN加速场景下的雪球效应。当COS源站配置了Referer白名单，而CDN回源请求的Referer字段往往是CDN加速域名而非业务站点，源站不识别就拒绝回源，导致CDN节点拿不到内容，最终用户侧图片裂开。解决办法是将CDN加速域名一并加入COS白名单，并在CDN回源配置中保持回源Host为源站域名，保证Referer的一贯性。最后提一句，如果业务在App端需要同时使用图片，不建议还在Referer白名单上死磕，直接走签名URL才是彻底绕开Referer依赖的正路。

使用签名URL解决防盗链冲突

签名URL的核心逻辑：绕过而非依赖Referer

COS 防盗链生效时，所有不带合法 Referer 的请求都被视为非法爬取，App、小程序、服务端脚本正是这类场景的重灾区。签名URL的设计恰恰绕开了这个限制——它基于密钥对资源路径、过期时间等参数做 HMAC 签名，请求一旦携带有效签名，COS 就会直接放行，不再校验 Referer 白名单。这意味着你不需要靠“允许空 Referer”来妥协安全策略，也能让原生应用稳定拉取图片。根据云老大技术团队的工单回溯，图片裂开类故障中，超过四成是因为开发者在移动端仍死磕 Referer 白名单，而完全忽略了签名URL这一更干净的解法。

签名URL与防盗链的并行策略

不少团队会陷入一个两难：网页端需要 Referer 防盗链挡住第三方盗用，App 端却因发不出 Referer 被一起挡死。正确的姿势不是二选一，而是让两条线独立运转。网页访问继续依赖 Referer 白名单，移动端、后端调用则通过服务端 SDK 动态生成有效期 10-30 分钟的签名URL并下发给客户端，存储桶本身保持“私有读写”。这样即使签名链接被意外泄露，过期时间也能把风险窗口压到极低。云老大在帮一家跨境独立站做迁移时，就按这套模型把盗链投诉压降了七成以上，同时避免了误伤真实用户。如果觉得密钥轮换和签名逻辑维护成本高，找这类具备一站式运维经验的服务商做一次整体评估，通常能省下大量试错时间。

腾讯云COS防盗链配置实战

控制台操作步骤详解

进入存储桶的「安全管理-防盗链设置」后，不少运维看到“Referer白名单”就只忙着填域名，反而忽略了一个决定性的选项——“允许空Referer”。在实际拦截案例中，超七成都与此有关。白名单应同时加上裸域名与*.example.com，覆盖子域；若启用了CDN，必须把加速域名一并写进白名单，因为源站收到的回源请求Referer就是CDN域名，而非用户浏览器传来的原始地址。保存规则前，建议先保持“允许空Referer”为开启状态，用浏览器直接访问一张测试图片，确认能从外站点击跳转也正常加载，再逐步收紧。

Python生成签名URL示例

当请求来自App或服务端，Referer不可控时，签名URL是更可靠的访问方式。核心是利用SecretKey对请求参数做HMAC-SHA1签名，生成带时效参数的临时链接，绕过Referer校验。以下代码使用官方Python SDK生成一个3600秒有效的下载链接，可以直接嵌入客户端：

from qcloud_cos import CosConfig, CosS3Client

config = CosConfig(
    Region='ap-guangzhou',
    SecretId='YOUR_SECRET_ID',
    SecretKey='YOUR_SECRET_KEY'
)
client = CosS3Client(config)

url = client.get_presigned_url(
    Method='GET',
    Bucket='example-1250000000',
    Key='images/photo.jpg',
    Expired=3600
)

生成的链接形如https://bucket.cos.ap-guangzhou.myqcloud.com/images/photo.jpg?q-sign-algorithm=sha1&q-ak=...，直接可访问，不依赖Referer，也无需在控制台修改白名单。注意密钥不要硬编码在客户端，应该由后端生成后下发，避免泄漏。

测试图片访问是否正常

规则上线后不要凭感觉验证。用curl做三次测试就能覆盖大部分场景：curl -I http://your-domain.com/test.jpg模拟无Referer请求；curl -I -e "https://your-site.com" http://your-domain.com/test.jpg带合法来源；curl -I -H "Referer:" http://your-domain.com/test.jpg显式空Referer。三次请求中，如关闭了“允许空Referer”，第一次与第三次会返回403，这就是App加载失败的直接原因。另外注意，腾讯云COS基于虚拟主机分发，IP直连本身就不被支持，不要用http://1.2.3.4/xx.jpg来验证防盗链是否生效，以免被“连接被重置”误导。

防盗链最佳实践与FAQ

如何设置高安全性防盗链

白名单配置远不止加个域名那么简单。一条被反复验证的原则是：先在控制台保留“允许空 Referer”开启，用 curl -H "Referer:" 模拟空值、curl -e "https://外部域名" 模拟盗链，逐一确认正常访问路径后再逐步收紧。生产环境最好让白名单同时包含裸域名和带 *. 的通配符，比如 example.com 与 *.example.com 双写，能覆盖直接输入 URL 和子域名跳转两类场景。CDN 用户必须把加速域名也写进 COS 白名单，否则回源请求被源站拒绝，节点返回 403 的画面远比防盗链本身更让运维头疼。App 或小程序这类无 Referer 环境，干脆放弃白名单依赖，改用私有读写桶配合后端生成签名 URL，前端只消费带 sign 参数的临时链接，一次部署就能彻底绕过 Referer 校验的暗坑。

防盗链对性能的影响

Referer 校验是对象存储网关在请求入口做的轻量级字符串比对，不涉及加解密计算，实测对首字节响应时间的增加通常小于 5 毫秒，带宽和 QPS 上限几乎不受拖累。真正拖慢体验的往往是配置错误——比如 CDN 回源请求被误拦后，节点不断重试，造成大量 403 状态堆积，命中率断崖式下跌。接入初期建议在 CDN 侧监控回源失败率，若出现陡增，优先检查白名单是否遗漏 CDN 域名。如果是高并发场景，可以配合缓存策略让 CDN 承担绝大部分读流量，源站只处理回源验证，整体延迟反而因为减少直连源站的动态判断次数而下降。

常见错误及解决方法

图片突然全线裂开，九成是因为关掉了“允许空 Referer”。App 的请求天生不带 Referer，浏览器隐私模式、地址栏直接输入也会导致空 Referer，这个开关必须保持开启，除非业务完全运行在带 Referer 的 Web 环境下。另一个高频错误是把签名 URL 和白名单当成互斥方案：当网页侧用白名单、App 侧用签名 URL 时，CDN 回源可能同时命中两条规则，产生预期外的拦截。解法是统一鉴权路径——要么全部切到签名 URL，要么在白名单中额外添加 CDN 回源专用域名，并对签名请求单独配置绕过 Referer 检查的策略。如果排查到最后发现依然是 403，记得用 curl -v 抓一下回源请求里的 Referer 字段，它常常在转发过程中被代理改写，这才是真正的幕后黑手。