庖丁解牛：外部JS长缓存Cache-Control: max-age=31536000配置与版本更新实践

在页面上用 <script src="https://cdn.example.com/app.xxxx.js"></script> 引用一段外部 JS，再顺手给静态服务器加一行 Cache-Control: max-age=31536000，这几乎是所有前端和运维都做过的常规操作。可一旦你真去追这个响应头，会发现自己踩进了一个由 HTTP 缓存语义、资源版本管理、中间代理策略和浏览器行为共同织成的网。标题里“庖丁解牛”四个字用得很准，因为只背这一行配置没什么用，真正值钱的是把整个链路拆开看明白：为什么是 31536000，谁在消费这个字段，和页面更新冲突时该怎么办，以及最后怎么才能安全地享受长缓存带来的性能红利。

这篇文章适合正在被“用户浏览器打开还是旧脚本”折磨的前端，也适合刚接手静态资源服务、想搞清楚缓存头怎么配才不背锅的运维和全栈。读完后你至少能回答三个问题：外部 JS 的 Cache-Control 到底由谁设置、max-age=31536000 为什么是“一年”、在资源可能需要更新的前提下这个值怎么用得不出事。

1. 先从“一整年缓存”说起：外部JS缓存参数的经济账

1.1 外部 JS 的 Cache-Control 到底是谁设置的

很多初学同学有个误解：看到 <script src="xxx.js">，以为在页面里写 JS 代码就能控制它加载文件的缓存。这是把“页面”和“资源”两个角色弄混了。外部 JS 对页面来说是一个独立的 HTTP 请求，它的响应是否被缓存、缓存多久，只取决于那一次 HTTP 响应里返回的 Cache-Control 响应头。发出请求的是浏览器，返回资源的是服务器、CDN 或对象存储，和 JS 文件内部写了什么内容没有直接关系。

举个极端例子：假如我在自己的网站服务一个 tracker.js，并且服务器配置了：

code复制Cache-Control: public, max-age=31536000

那么即使 JS 文件里的代码每天自动变化，只要文件 URL 不变，浏览器在一年内都不会再向服务器发起这个文件的请求。外部 JS 本身没有任何能力去“修改”这次响应头——真正起作用的，是服务器在收到请求后返回的 HTTP 头部。你想让外部 JS 获得这个缓存策略，只能去改资源所在服务器的响应配置，而不是在 JS 代码里写 localStorage 之类的东西。

明白这一点后，后面所有操作都围绕同一件事：如何让提供 JS 资源的服务端在处理请求时，稳定地返回一行我们希望见到的 Cache-Control。

1.2 31536000 这个数字是怎么来的，为什么写错的人很多

Cache-Control 里的 max-age 单位是秒，不是毫秒，更不是天。31536000 是由 60 秒 × 60 分钟 × 24 小时 × 365 天计算得到，也就是一整年。很多团队第一次配长缓存时会顺手写 max-age=315360000，多打一个 0，瞬间变成十年。等到资源需要下线时，想强制让所有客户端丢弃这个缓存几乎只能靠改 URL，相当被动。

这里穿插一个常见误区：max-age 并不是一个绝对过期时间，而是一个相对时间。它表示“从浏览器收到这个响应开始，后续 N 秒内，可以直接使用本地缓存，不需要向服务器验证”。也就是说，如果用户 2025 年 1 月 1 日拿到响应，那么这个资源在本地有效到 2026 年 1 月 1 日；但如果是 2025 年 6 月才首次访问，它就从 6 月开始算一年。

有人会问：为什么不能像 Expires 那样直接写一个 GMT 时间？因为在现代 HTTP 语义里，Cache-Control 的优先级高于 Expires，而且 max-age 是相对时间，不用客户端和服务器各自时钟同步，省去很多时间不准导致的缓存失效问题。这也是为什么很多 CDN 和框架默认都生成 Cache-Control: max-age=... 而不是只发 Expires。

1.3 长缓存对“外部 JS”场景到底意味着什么

外部 JS 是前端性能优化里优先级极高的静态资源。一个中大型站点的主脚本往往有几十到几百 KB，如果是首屏依赖的逻辑，每次刷新都回源会浪费大量带宽，也会让首屏变慢。设置一年长缓存，理论上可以让绝大多数重复访问用户直接命中本地缓存，彻底消灭这部分请求的往返时间。

但“最大缓存一年”不能和“缓存一定会持续一年”划等号。真实场景里还要看用户使用的浏览器磁盘缓存是否足够、是否主动强制刷新、CDN 节点有没有覆盖源站响应头、以及资源 URL 是否发生变化。可以说，max-age=31536000 是在给你提供一张“上限额度”，而不是承诺它能满额使用。想真正拿到长缓存的红利，光配一行响应头远远不够，还需要配合版本号策略和 HTML 的缓存控制，后面我会单独拆一节。

2. 判断现状：动手前必须学会查看当前响应头

“庖丁解牛”里最精彩的一句话是“目无全牛”。意思是解牛时看到的已经不是一整头牛，而是骨骼、经络之间的缝隙。排查缓存问题也一样，如果你只看页面能不能打开，永远抓不住问题；你需要像看结构一样看清一次资源请求从发出到返回过程中，到底带了哪些响应头。

2.1 在命令行里对任意外部 JS 发一次请求

无论目标资源在不在你的服务器上，都可以先用 curl 看它的响应头。比如：

bash复制curl -sI https://example.com/target.js

如果你想同时看到请求状态码和完整响应头，也可以用：

bash复制curl -s -o /dev/null -D - https://example.com/target.js

-o /dev/null 是丢到响应体，-D - 是把响应头打印到终端。执行后，重点找几行：

code复制HTTP/2 200
cache-control: public, max-age=31536000, immutable
content-type: application/javascript; charset=utf-8
etag: "63e2a4f5-1a3b"
last-modified: Mon, 12 Jun 2023 10:20:30 GMT

看到 cache-control 里有 max-age=31536000，就说明资源自己在服务器层已经配置了整整一年的强缓存。如果响应里没有 cache-control，甚至你看到的只有 ETag 和 Last-Modified，那就要小心了：浏览器可能基于启发式缓存做一些你完全没预期的缓存行为。

2.2 从浏览器开发者工具里看“真实用户视角”

curl 看到的是源站或当前网络路径返回的头，但用户浏览器里的真实情况，还会受到用户本地缓存状态的影响。打开 Chrome DevTools 的 Network 面板，勾选“Disable cache”并不等于模拟普通用户，它只是方便调试。正确做法是刷新页面，点击目标 JS，在 Headers 面板里看两个区：

• General 里的 Status Code：如果是 200 OK (from disk cache) 或 200 OK (from memory cache)，说明资源是本地直接用缓存，根本没发请求。
• Response Headers 里的 Cache-Control：这里展示的是资源首次被缓存时保存下来的响应头，能用来判断当初服务器给的是什么策略。

一个容易踩的坑：如果资源已经命中本地缓存，你在 Network 面板里是看不到“这一次”的服务器响应头的，看到的只是上一次保存的缓存头。所以判断服务器配置有没有改对，最可靠的办法是用无痕窗口，或者先清缓存再刷新，或者直接用 curl 访问源站地址。

2.3 不带任何缓存头时会发生什么

有些同学说：“我们的服务器没配过 Cache-Control，为什么用户还是拿到了旧文件？”这里藏着 HTTP 缓存里一个容易被忽略的机制：启发式缓存。

假设响应里只有 Last-Modified: 2025-01-01 10:00:00，没有 Cache-Control，没有 Expires。浏览器会按 RFC 7234 的启发式算法，用当前时间和 Last-Modified 之间的差值乘以一定比例，默认按 10% 左右估算一个新鲜度。如果一个 JS 文件在服务器上已经一年没改，Last-Modified 是一年前，浏览器可能私自缓存几十天。这段“隐形缓存期”里用户同样拿不到新版。所以“不设缓存”绝不等于“不缓存”，这行没写的响应头反而会让你在排查时更困惑。给静态资源明确写入 Cache-Control，本质上是在告诉所有中间环节：按我的规则来，不要自己猜。

3. 四种配置 Cache-Control 的可落地方案

看完现状之后，进入实操环节。外部 JS 的 Cache-Control: max-age=31536000 可以在多个层级设置：源站程序、Nginx/Apache、对象存储、CDN 控制台。下面每种方案都给出完整做法。

3.1 Nginx：最常见的静态资源服务器配置

现在很多前端项目部署在后端 Nginx 上，通过 location 匹配 JS 后缀来加响应头。一个我自己反复验证过的配置：

nginx复制server {
    listen 80;
    server_name example.com;

    root /var/www/dist;

    location ~* \.(?:js|mjs)$ {
        expires 1y;
        add_header Cache-Control "public, max-age=31536000, immutable" always;
        try_files $uri =404;
    }

    location / {
        # 页面本身不适合长缓存，通常用 no-cache
        add_header Cache-Control "no-cache" always;
        try_files $uri $uri/ /index.html;
    }
}

需要注意几个细节：expires 1y 这个指令本身就会生成 Cache-Control: max-age=31536000 和 Expires 头，所以如果你又手动写了 add_header Cache-Control "public, max-age=31536000, immutable"，在 Nginx 里需要小心会不会覆盖或重复。我习惯用显式的 add_header，并且加上 always 关键字，确保即使是 404、500 这类错误响应也会附带，避免调试时响应头时有时无。immutable 是给支持它的浏览器“吃定心丸”的，告诉浏览器这个文件在过期前绝不会变，可以放心大胆地用缓存。Nginx 版本和模块不同，expires 生成的默认值也可能有差异，写成显式更可控。

3.2 Apache：通过 .htaccess 或虚拟主机配置

Apache 环境里，如果开启了 mod_headers，可以直接在目录配置或 .htaccess 里写：

apache复制<FilesMatch "\.(js|mjs)$">
    Header set Cache-Control "public, max-age=31536000, immutable"
</FilesMatch>

这里还有个优先级问题：Header set 会覆盖同名的旧头，如果用 Header add 则可能出现两个 Cache-Control，某些代理会合并它们，导致结果不可预期。所以改成 set 更安全。Apache 2.4 版本下，FilesMatch 匹配的是文件名，不影响目录路径。如果项目里的 JS 都放在 /assets/ 下，也可以结合 <Directory> 配置得更精细。

3.3 对象存储/CDN：托管静态资源时的标准操作

现在很多项目把静态资源放在对象存储和 CDN 上。无论是阿里云 OSS、腾讯云 COS 还是 AWS S3，上传对象时都能指定对象的 HTTP 头。控制台操作通常是在“对象属性 -> HTTP Header”里新增；如果用 SDK，则可以在上传时设置 CacheControl 字段。S3 的 Java SDK 示例大概是：

java复制ObjectMetadata metadata = new ObjectMetadata();
metadata.setContentType("application/javascript");
metadata.setCacheControl("public, max-age=31536000, immutable");
s3Client.putObject(bucketName, key, inputStream, metadata);

CDN 层还要额外注意“源站缓存头”和“CDN 缓存配置”两层概念。有的团队只在 CDN 控制台配置了“缓存过期时间”，但 CDN 回源时没有透传源站的 Cache-Control，结果源站改版后 CDN 还拼命返回旧缓存。比较推荐的做法是：CDN 上对带版本 hash 的静态文件设置“遵循源站缓存头”，把缓存决策权交回给源站，减少配置漂移。

3.4 服务端动态输出 JS 时的 Header 设置

如果 JS 并不是纯静态文件，而是由后端接口临时生成或需要鉴权，此时就要在应用代码里设置。拿几个常见后端举例：

Python Flask 示例：

python复制from flask import Flask, Response

app = Flask(__name__)

@app.route("/script.js")
def script():
    js_content = "console.log('hello from python')"
    resp = Response(js_content, mimetype="application/javascript")
    resp.headers["Cache-Control"] = "public, max-age=31536000, immutable"
    return resp

Node.js Express 示例：

javascript复制app.get('/script.js', (req, res) => {
  res.set('Content-Type', 'application/javascript');
  res.set('Cache-Control', 'public, max-age=31536000, immutable');
  res.send(`console.log('hello from node')`);
});

Go 标准库示例：

go复制func ScriptHandler(w http.ResponseWriter, r *http.Request) {
    w.Header().Set("Content-Type", "application/javascript")
    w.Header().Set("Cache-Control", "public, max-age=31536000, immutable")
    fmt.Fprintln(w, "console.log('hello from go')")
}

动态输出的资源通常不像构建产物那样带文件名 hash，如果内容会变，我建议你在业务层评估一下到底要不要开一年长缓存。真要动态内容，又想让外部引用方拿到新版本，就得靠 URL 参数或路径版本号来“换一个缓存键”，这个点放到后面重点讲。

4. 庖丁解牛的核心：长缓存和版本更新如何共存

一个完整的技术方案如果只聊“怎么配置”，那就和看菜谱不炒菜一样。真正考验水平的是，配置完了，你团队下周要上线新版本，文件名还叫 app.js，此时在浏览器里看到旧代码怎么办？这一章，“庖丁”才开始动刀。

4.1 为什么固定 URL + 极长 max-age 会让你上线翻车

假设用户第一次访问，请求 https://example.com/app.js，响应头是 Cache-Control: public, max-age=31536000。用户在本地存了一年。第二天你们发布新版本，覆盖了服务器上的 app.js 文件，URL 还是同一条。结果是什么？除非用户强刷或缓存被清，他这一年里永远用旧逻辑。这跟服务端文件是否覆盖没有关系，因为浏览器认为自己的缓存还没过期，根本不会发起新请求。

这也是很多团队在初次接触长缓存时崩溃的原因。他们给所有 JS 统一加了 max-age=31536000，然后上线时发现测试环境怎么刷新都是旧东西。本质就是把“缓存所有 JS”和“安全缓存所有 JS”两件事画了等号。想安全，就必须让静态资源 URL 和内容形成绑定关系。

4.2 用“文件名内容哈希”打破旧缓存

现代前端构建工具给出的标准解是：把内容 hash 写进文件名。Webpack、Vite、Rollup 默认都会生成 app.7d12f31a.js 这样的产物，内容是同一份，hash 就一定是同一个；内容一变，hash 也会变。页面引用的是：

html复制<script src="/assets/app.7d12f31a.js"></script>

下次构建后变成：

html复制<script src="/assets/app.9f2ba14c.js"></script>

从浏览器视角看，这是一条全新的 URL。之前那条一年缓存是旧文件的，跟新 URL 没有任何关系，所以不会阻塞更新。真正需要修改的是 HTML 页面，它要第一时间把新的 <script src> 引用输出给用户。因此配套原则就是：带 hash 的静态资源可以开一年甚至更长缓存，但 HTML 必须用 no-cache。

4.3 要不要配合协商缓存：理解 no-cache 与 max-age 的分工

max-age=31536000 和 no-cache 并不互斥，它们可以同时存在，比如：

code复制Cache-Control: no-cache

这里的“no-cache”不是禁止缓存，而是“使用缓存前必须先向服务器验证资源是否过期”。换句话说，它允许缓存，但每次都要走一次协商。

如果你看响应头有：

code复制Cache-Control: max-age=0, must-revalidate

这也是要求每次请求都做验证，原理类似。而对应地，静态资源用了一年 max-age 后，如果服务器还有 ETag，那么缓存未过期时不会发请求；一旦本地缓存被别人恶意清掉一部分，或者 CDN 节点需要回源，源站可以通过 ETag 判断内容是否变化，返回 304，让体积小的响应头代替重复下载整个 JS 文件。

在我自己维护的几个项目里，页面 HTML 用 Cache-Control: no-cache，静态带 hash 资源用 Cache-Control: public, max-age=31536000, immutable，这组组合能显著平衡性能和可更新性。

4.4 immutable 到底是干嘛的，别在没做 hash 时乱用

immutable 是后来新增的语义，含义是“这个资源在过期之前一定不会变”。主流浏览器在处理普通刷新时会忽略部分协商逻辑，而 immutable 更像是给浏览器一个强烈暗示：就算用户手动刷新页面，这个文件只要还没超过 max-age，就不需要重新验证。Chrome 对带 immutable 的静态文件，在普通刷新和前进后退时都会更“懒”地使用缓存。

但它不是没有代价的。如果项目还没做内容 hash，文件就甭想更新了，只能靠强制刷新/CDN 刷新解决。我见过某个项目给所有 JS 加了 31536000，还顺手加了 immutable，结果上线后一大半用户十天都拿不到新版本，最后运维只能紧急把所有静态资源 URL 前面加了一个版本号前缀，才把事故压下去。建议把 immutable 当作“最后一公里”优化，前提一定是有可靠的文件名 hash。

4.5 处理版本更新的完整链路

把最优实践串起来，完整链路是：

1. 构建阶段输出带 hash 的 JS/CSS 文件。
2. HTML 模板引用新 hash 的 URL。
3. 源站对静态 JS 返回 Cache-Control: public, max-age=31536000。
4. CDN 缓存规则遵循源站头。
5. 用户在浏览器请求新 HTML，HTML 里拿着新 URL，触发新的缓存条目。
6. 旧 URL 的本地缓存自然过期，不主动清理也不影响新版本。

这套链路如果走通，你就不再需要用户强制刷新，也不怕一年长缓存。

5. 常见问题与排查实操

配置类的文章如果没有“踩坑记录”，就像给了一把螺丝刀却没告诉用户怎么拧花螺丝。下面这些情况是我在真实现场反复撞过的，整理成可以照抄的排查顺序。

5.1 排查“改了服务器配置但浏览器还是旧 JS”的路线

按从客户端到源站的顺序走：

第一步，清掉浏览器本地缓存，或用无痕窗口打开页面，观察 Network 面板。如果无痕窗口里能拿到新文件，说明源站和网络路径是通的，问题出在用户本地或 HTML 被缓存。

第二步，查看页面 HTML 的响应头。如果 HTML 被某个代理或你自己错误地设置了长缓存，那么即使服务器中新 JS 上线，用户拿到的 HTML 还引用着旧文件名，看起来就是“JS 没更新”。

第三步，用 curl 直接访问源站，观察它返回的 Cache-Control。如果源站是新配置，但用户在浏览器里访问的 CDN 域名还是旧响应头，那么还要检查 CDN 节点缓存。

第四步，检查你是否改了“正在被缓存的文件同名覆盖”。如果 JS 文件名没变，且浏览器本地缓存还有效，那新版本本来就是“看不见的”。这不算配置错，而是策略不对。

5.2 一张速查表应对 90% 的缓存异常

5.3 配置模板：直接能抄的一键想法

假设你使用 Nginx 托管 dist 目录，构建产物里带 hash，最省心的一套配置：

nginx复制location /assets/ {
    expires 1y;
    add_header Cache-Control "public, max-age=31536000, immutable" always;
}

location / {
    add_header Cache-Control "no-cache" always;
    try_files $uri /index.html;
}

这个片段的使用前提是：/assets/ 下文件名全部来自构建系统且包含 hash，而 / 下的 HTML 每次都被刷新验证。如果项目没有区分目录，就要靠构建后脚本把带 hash 的文件单独挪进 assets 目录，或者用正则匹配文件后缀。

对后端 API 响应，我不建议随便配 max-age=31536000，除非你能保证接口结果长期不变。一般情况下 API 用 Cache-Control: no-store 或短 max-age 更稳妥。因为 HTTP 缓存是给不常变的静态资源准备的，不是给业务逻辑穿的保护衣。

5.4 别只背配置，练成“接口即结构”的思维

再次回到“庖丁解牛”的隐喻。解牛高手区别于普通厨子，在于他对牛的结构了然于胸。处理一个缓存问题时，可以把链路拆成“浏览器缓存池、中间代理/服务端缓存、源站逻辑/存储”三层。你看到任何一处异常，都需要标记出问题发生在哪一层，而不是盲目地改服务器配置。

比如我发现用户反馈旧资源，第一反应不是去清 CDN，而是确定用户访问的 DOM 里引用的是什么 URL。如果 URL 本身带着旧 hash，说明 HTML 层缓存过期了；如果 URL 已经是新 hash，但内容还是旧的，说明 CDN 节点或源站输出有问题。这个简单的分流能少走很多弯路。

6. 从我自己的长期实践中再补几个冷门细节

最后分享几个我在项目里积累出来的小经验，不一定写在官方文档里，但很实用。

不要给同一个域名下的所有资源都配一样的缓存策略。哪怕同样叫 JS，app.js、analytics.js、api.js 的更新频率完全不同。把一年长缓存用在“内容会变”的文件上，等于给自己和用户埋了一颗延迟发布的定时炸弹。我比较喜欢按目录、按 filename 模式分开配置，让有 hash 的资源走长缓存，其他资源走短缓存或验证。

注意 Cache-Control 里 public 和 private 的语义。对外部公开 CDN 上的 JS，用 public 是合理的；如果脚本涉及用户个人信息，最好不要通过 CDN 或代理缓存，直接 private 或干脆不缓存。滥用 public 在小团队内网可能没事，一旦资源被外部代理、聚合站点缓存，就可能泄露不该泄露的内容。

服务端如果同时配置了 Expires 和 Cache-Control，别担心，HTTP 标准规定：当 Cache-Control 里的 max-age 存在且与 Expires 冲突时，max-age 优先。所以如果你只是图方便在 Nginx 里写 expires 1y，它会同时生成这两个头，行为依然一致。关键问题是别在源站、CDN、多层代理之间各写一套互相矛盾的规则，那才是真正噩梦的开始。

还有一个小坑：max-age 是资源被缓存的时间窗口，但它不代表 CDN 一定会在这段时间内把资源保持在边缘节点上。CDN 节点有自己的淘汰策略。如果某个 JS 体积巨大但很少被访问，源站的 TTL 设了一年，CDN 节点也可能在几小时后因节点压力淘汰它，下次请求重新回源。此时如果源站的磁盘上文件还在，那没问题；如果源站已经清除旧版本，只保留了新的，那就会出现部分边缘节点还可能短暂提供旧内容、部分节点已经回源拿到新内容的不一致。处理和长期一致性的最佳办法还是使用带内容 hash 的 URL，让新旧两版资源在源站保留一段时间，不要急着删除，给 CDN 和用户一个自然过渡期。

另外关于“强制刷新能解决吗”这个问题，我的回答是：它能验证问题，不是长久解法。用户按 Ctrl+F5 / Cmd+Shift+R 后，请求头通常会带上 Cache-Control: no-cache，浏览器会绕过强缓存去服务器验证，所以能看到新版。但这不可能让每个用户都在每个设备上做这个操作。真正解法永远是把资源版本化，让新用户可以重新走一遍缓存填充，而不是在旧 URL 上做文章。

我最近一次处理这个问题是在给一个数据大屏项目做上线流程优化。团队以前所有 JS 都叫 main.js，上线后总有人反馈页面白屏或图表不出现，排查了大半天最后发现是浏览器缓存了旧版 main.js，新代码里调用的接口和旧版事件绑定方式不兼容。后来我们把构建产物全部改成带内容 hash 的命名，页面 HTML 改为 no-cache，静态资源 CDN 统一设 Cache-Control: public, max-age=31536000, immutable，上线时只需要确认 HTML 更新。包括双十一当天临时调样式，也只发一次新构建就完成全量更新，不需要任何人按键强刷。

所以，看到 Cache-Control: max-age=31536000 的时候，别再单纯觉得“缓存时间越长越好”。这串数字能给你带来理想的性能，也可能带给你最头疼的发布故障。区别就在你有没有把资源版本化、HTML 缓存原则、CDN 透传策略和请求链路排查能力组合成一套完整的“解牛刀法”。把这套刀法学到手，以后无论是外部 JS 还是 CSS、图片、字体，处理思路都能一通百通。