NET::ERR_CACHE_ENTRY_NOT_SUITABLE 是 Chromium 内核浏览器中一个相对冷门的网络错误，它并不像断网或 DNS 解析失败那样直观。出现该错误时，资源通常已经从网络加载完成并写入了磁盘缓存，但下一次请求同一个 URL 时，浏览器却认为这个缓存条目与当前请求不匹配，于是直接中断加载。这种现象在 CDN 加速场景中尤其常见，因为 CDN 边缘节点会根据自身的缓存策略保存响应，而源站和 CDN 对响应头的处理差异会放大缓存条目不合适的问题。
错误现象与触发条件
先明确一个关键点：NET::ERR_CACHE_ENTRY_NOT_SUITABLE 并不是缓存文件损坏，也不是磁盘空间不足。Chromium 的源码中，当缓存条目存在但无法满足当前请求时，会返回这个错误码。常见的触发场景包括：请求资源的 URL 完全相同，但请求头中的 Accept-Encoding、Accept-Language 或 Origin 发生了变化；或者缓存条目中的响应头与当前响应头不一致，例如 Content-Encoding 声明为 gzip 但实际存储的内容是未压缩的。
在 CDN 环境下，这个问题更容易被放大。CDN 服务商通常会在边缘节点缓存静态资源，并根据缓存键（Cache Key）决定是否复用缓存。如果缓存键没有把一些关键请求头纳入计算，边缘节点就可能把同一个缓存对象返回给不同类型的请求。例如，源站支持 Brotli 和 gzip 两种压缩方式，CDN 缓存了 Brotli 版本，但当浏览器只声明支持 gzip 时，CDN 仍然返回 Brotli 内容，并且响应头里写着 Content-Encoding: br，这时本地缓存校验就会失败，浏览器可能报出 NET::ERR_CACHE_ENTRY_NOT_SUITABLE。
另一个常见触发条件是 CDN 缓存了带有错误状态码的响应。比如源站因为限流返回了 429 状态码，但 CDN 配置不当将其缓存，并附带 200 状态码返回给用户，导致缓存条目中的状态码与实际响应体不匹配。这种状态码和响应体错位的情况会让浏览器在缓存校验阶段直接判定条目不合适。
从 HTTP 缓存校验逻辑理解根因
HTTP 缓存的合法性由 RFC 9111 定义，核心原则是一个缓存条目必须与当前请求在方法、URI 以及 Vary 头指定的维度上完全匹配。浏览器在检查本地缓存时，会先核对请求方法和 URL，再查看缓存条目的响应头中是否包含 Vary 字段。如果 Vary 字段存在，浏览器会进一步比较请求中对应头字段的值与缓存条目存储时的值是否一致。如果不一致，这个缓存条目就是不可用的，此时浏览器通常会发起新的网络请求，但在某些边界情况下，Chromium 会直接给出 NET::ERR_CACHE_ENTRY_NOT_SUITABLE。
Vary 头是最容易被忽视的元凶。假设源站返回了 Vary: Accept-Encoding，但 CDN 在缓存时忽略了 Accept-Encoding 的差异，只缓存了第一个请求的压缩版本。之后其他 Accept-Encoding 状态的请求命中同一个缓存对象，就会造成内容编码与请求声明不匹配。此时浏览器收到的响应体可能是 gzip 数据，但响应头写的是 br，缓存校验自然失败。更隐蔽的情况是源站没有返回 Vary 头，但 CDN 自行添加了某些头字段，导致缓存条目之间的差异没有被正确区分。
除了 Vary，Content-Length 和 Transfer-Encoding 的不一致也会触发该错误。当缓存条目记录的内容长度与实际写入磁盘的大小不一致时，Chromium 会认为缓存条目损坏或不完整。CDN 回源时如果源站使用了分块传输编码（Transfer-Encoding: chunked），而 CDN 最终响应给用户时没有正确处理 Content-Length，就可能导致缓存元数据与实际内容不匹配。
下面用一个简单的响应头示例展示这种不一致。假设 CDN 返回给浏览器的响应头如下，但实际缓存内容是未压缩的文本：
HTTP/1.1 200 OK Content-Type: text/html; charset=utf-8 Content-Encoding: gzip Content-Length: 512 Vary: Accept-Encoding Cache-Control: public, max-age=86400
如果实际存储的内容没有经过 gzip 压缩，或者 Content-Length 的值与实际字节数不符，浏览器在缓存校验时就会抛出 NET::ERR_CACHE_ENTRY_NOT_SUITABLE。排查时可以先用 curl 查看源站和 CDN 分别返回的响应头，对比两者在 Content-Encoding、Content-Length、Vary 上的差异。
排查 CDN 缓存配置与常见修复方案
定位问题首先要确认错误是否只在特定浏览器或特定网络环境下出现。Chromium 系浏览器（Chrome、Edge）对缓存校验更严格，Firefox 或 Safari 可能只是重新请求而不报错。如果只在 Chromium 下出现，基本可以锁定为缓存元数据不一致。接下来可以查看 CDN 的缓存命中日志，观察出现错误时的缓存状态是 HIT 还是 MISS。如果错误发生在 HIT 状态，说明 CDN 返回了错误的缓存对象；如果发生在 MISS 状态，则可能是源站响应头本身有问题。
修复方案需要根据根因分别处理。如果是 Vary 头没有被纳入缓存键，就要在 CDN 配置中把对应的请求头加入缓存键。以 Cloudflare 为例，可以在缓存规则中启用“区分 Accept-Encoding”或自定义缓存键包含特定请求头。对于 Nginx 作为自建 CDN 节点的情况，需要检查 proxy_cache_key 配置，确保包含必要的变量。下面是一个 Nginx 缓存键配置示例：
proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=my_cache:10m max_size=10g inactive=60m use_temp_path=off;
server {
listen 80;
server_name cdn.ippipp.com;
location /static/ {
proxy_cache my_cache;
proxy_cache_key "$host$request_uri$http_accept_encoding";
proxy_cache_valid 200 302 1h;
proxy_cache_valid 404 1m;
proxy_pass http://origin_server;
add_header X-Cache-Status $upstream_cache_status;
}
}
上面的配置把 $http_accept_encoding 加入了缓存键，这样不同压缩编码的请求会分别缓存。但要注意，如果 Accept-Encoding 的值有很多变体（如 gzip, deflate, br 或 gzip, deflate），缓存碎片会增多，需要权衡缓存命中率和正确性。另一种做法是规范源站统一使用同一种压缩算法，并明确返回 Vary: Accept-Encoding，让 CDN 按照标准处理。
如果问题是 CDN 缓存了错误状态码或错误响应体，最直接的修复是清理 CDN 缓存并重新预热。对于误缓存 4xx 或 5xx 响应的场景，需要在 CDN 控制台设置“不缓存错误响应”或限制缓存状态码。例如 Cloudflare 默认不缓存 4xx 和 5xx，但如果自定义了 Cache Everything 规则，就可能把错误响应也缓存下来。此时应调整缓存规则，只对 200 和 3xx 响应进行缓存。
源站响应头不规范时，还需要从源站侧修复。确保源站对可缓存资源返回明确的 Cache-Control 和 Vary 头。对于动态内容或个性化内容，不要使用强缓存，可以设置 Cache-Control: no-cache, private。对于静态资源，建议使用内容指纹（如文件名带 hash）配合长缓存，从根源上避免同一个 URL 返回不同内容的情况。
预防措施与最佳实践
要避免 NET::ERR_CACHE_ENTRY_NOT_SUITABLE 反复出现，需要建立一套严格的缓存规范。第一，源站和 CDN 的响应头必须保持一致，特别是 Content-Encoding 和 Vary。建议在源站就返回完整的 Vary 头，不要依赖 CDN 自动补充。第二，对静态资源采用内容指纹命名，例如 main.3f2a1b.js，这样内容变化时 URL 也会变化，不会命中旧缓存。第三，对错误响应配置零缓存或极短缓存，防止 CDN 将错误状态码返回给用户。
监控方面，可以定期检查 CDN 缓存命中率以及浏览器端错误上报。如果错误集中在某个资源或某个地区，应该优先排查对应 CDN 节点的缓存内容。还可以在 CI/CD 流程中加入缓存一致性测试，模拟不同 Accept-Encoding 请求，验证 CDN 返回的内容编码是否与请求匹配。这些措施虽然不能完全杜绝问题，但能显著降低出现概率。
最终，缓存问题本质上是多个系统之间的协作问题。浏览器、CDN、源站对 HTTP 缓存标准的理解必须一致，任何一方的特殊处理都可能打破缓存条目的适用性。理解 NET::ERR_CACHE_ENTRY_NOT_SUITABLE 背后的缓存校验逻辑，能帮助开发者更快定位是本地缓存、CDN 配置还是源站响应头出了问题，从而针对性地修复而不是盲目清理浏览器缓存。
NET::ERR_CACHE_ENTRY_NOT_SUITABLECDN缓存配置HTTP缓存校验修改时间：2026-08-21 04:49:56