有朋友在群里问我我在 npm 上发了个新版本jsDelivr CDN 上为什么还是旧文件这个 CDN 的缓存到底多久自动更新一次我当时第一反应是——问这个话的人大概率没搞懂 jsDelivr 的缓存设计因为这玩意儿压根就不是按“时间”来更新的而是按“URL”来更新的。你只要摸清它的 URL 规则和发布流程很多缓存不更新的问题其实都是自己把自己绕进去了。这篇文章我打算把 jsDelivr CDN 的自动缓存更新机制从头到尾捋一遍内容包括永久缓存的设计原理、npm 包和 GitHub 仓库两种来源的更新方式、Purge API 手动刷新的正确姿势、以及我在实际排查缓存不更新问题时总结的一套完整链路。不管你是写博客引文件、维护开源库还是公司内部用 jsDelivr 做静态资源分发这篇文章都适用。1. 结论先行jsDelivr 不是“定期更新缓存”而是“按 URL 永不更新”1.1 永久缓存到底是什么意思jsDelivr 官网文档里写得很直白它的缓存策略是 immutable也就是说一旦一个 URL 的内容被缓存在 CDN 边缘节点上这个内容就永远不会被自动更新。我举个例子你就明白了https://cdn.jsdelivr.net/npm/your-package1.0.0/index.js假如你在 npm 上把 thisPackage 从 1.0.0 升到 1.0.1代码有了变动但页面上还是引用上面这个 URL那么 CDN 会一直给你返回 1.0.0 的 index.js等多久都是这样。不是“12 小时后更新”也不是“24 小时后更新”是永远不更新。这套设计和很多习惯了国内 CDN 控制台“刷新缓存”操作的朋友是反着来的。用传统 CDN 的时候我们通常会这么做资源文件名叫 app.js更新内容后去控制台提交刷新等 CDN 节点回源拉新文件。jsDelivr 的思路完全不同它认为一个 URL 就是一份不可变的内容快照想更新内容那就换个 URL而不是让旧 URL 变内容。这种设计带来的直接后果是URL 里的版本号就是缓存更新的一把钥匙。你不换版本号CDN 就没有任何动力去更新内容。1.2 分支 URL 的 12 小时例外当然上述“永久缓存”有一个重要例外那就是 GitHub 仓库的分支路径https://cdn.jsdelivr.net/gh/user/repomain/file.js这里的 main 是分支名分支是可变引用内容随时可能变。jsDelivr 对这种 URL 提供的是有限刷新机制默认缓存时间是 12 小时。也就是说你推到 main 分支上的文件最长要 12 小时才能在全网节点上看到更新。但注意这只是“分支名”这种可变引用的特例。如果你在 URL 里使用的是 tag 或 commit hash例如https://cdn.jsdelivr.net/gh/user/repov1.0.0/file.js https://cdn.jsdelivr.net/gh/user/repo7623a1bdc1c8/file.js那又回到永久缓存了。tag 和 commit hash 都指向某个确定的历史状态jsDelivr 认为它们不可变所以永久缓存。1.3 这套设计背后的成本逻辑很多人会觉得“永久缓存”很麻烦每次更新都要改版本号。但你站在 CDN 厂商的角度想一下就理解了永久缓存意味着极高的缓存命中率和极低的反向回源压力。jsDelivr 能提供免费服务核心靠的就是这套机制。如果它像国内 CDN 那样频繁回源校验每个边缘节点都要反复请求源站文件成本根本压不住。换版本号对发布方来说只是一个小动作但对 CDN 来说它可以用最便宜的方式服务海量流量。另外永久缓存也天然规避了“多人同时请求一个 URL结果 A 节点拿到新内容、B 节点还拿着旧内容”这种缓存不一致问题。所有节点只要缓存过一个 URL内容就锁定不会出现同一文件不同版本轮播的情况。这也是我比较欣赏这个设计的原因——它牺牲了“自动刷新”的便利性换来了全网的确定性和一致性。2. 版本号就是缓存钥匙URL 规则拆解2.1 npm 包 URLversion 里的学问npm 包的 jsDelivr URL 基本格式是https://cdn.jsdelivr.net/npm/包名版本号/文件路径这里版本号可以是精确版本、范围版本、或者 semver 的各种写法URL 写法含义缓存策略/npm/pkg1.2.3/file.js精确版本永久缓存/npm/pkg^1.2.3/file.js大于等于 1.2.3 的最新 1.x 版本302 跳转到精确版本 URL永久缓存/npm/pkglatest/file.js最新版本302 跳转到精确版本 URL永久缓存/npm/pkg/file.js不写版本默认 latest302 跳转到精确版本 URL永久缓存这里最巧妙的是 302 跳转机制。当你不写版本或者写成 latest 时jsDelivr 会先返回一个 302 重定向指向当前满足条件的具体版本 URL。浏览器和 CDN 节点跟着跳转以后实际缓存的内容仍然落在带版本号的那个 URL 上所以你还是享受永久缓存。我之前见过不少人直接把 latest 链接写在生产环境里这其实不是不行但有一个隐患jsDelivr 的后台服务更新 npm 包的引用是有延迟的而且 302 跳转之后你拿到的是哪个版本取决于 CDN 当时能看到的 npm registry 数据。如果发布和部署刚好卡在同一时间段有可能出现“代码已经发布但跳转还没跟上”的情况。所以我个人的习惯是能写精确版本号就写精确版本号别偷懒。2.2 GitHub 文件 URLbranch、tag 与 commit hash 的区别GitHub 文件的 jsDelivr URL 格式是https://cdn.jsdelivr.net/gh/用户名/仓库名分支或tag或hash/文件路径这个 后面跟什么直接决定缓存策略 后面的内容示例是否可变缓存策略分支名main可变12 小时过期Tagv1.0.0不可变永久缓存Commit Hash7623a1bdc1c8不可变永久缓存如果你在用 GitHub 仓库里的文件又想让 CDN 内容能自动跟着代码更新最直观的做法是用分支名。但代价就是最长可能有 12 小时的延迟而且你没法精确控制这个延迟——不是到点立刻更新而是在 12 小时内某个时间点更新。如果你想享受永久缓存的高命中率那就用 tag 或 commit hash。GitHub 每次 push 之后你在 URL 填入最新的 commit hash就能拿到一次全新的缓存条目。这在 CI/CD 场景下非常有用。2.3 CDN 缓存和浏览器缓存必须分开看讲到缓存不更新我一直强调要先把“CDN 缓存”和“浏览器缓存”这两个概念分开。jsDelivr 的永久缓存、12 小时缓存指的是 CDN 边缘节点上的文件。浏览器本地也有自己的 HTTP 缓存只要 CDN 返回的响应头里带着 cache-control 之类字段浏览器就会把文件存在本地下次直接读本地根本不会问 CDN。举个例子你用 curl 访问一个 jsDelivr URL发现 CDN 上的内容是最新的但打开浏览器测试页面却还是旧代码。这种情况下问题不一定在 jsDelivr可能是浏览器自己的 HTTP 缓存没失效。做缓存排查的时候第一步永远是用无痕窗口或 curl 去测先排除浏览器这层干扰。3. 发布新版本才是让 CDN 自动更新的正规操作3.1 npm 发布流程从改版本号到 publish既然 jsDelivr 按 URL 永久缓存那让它“自动更新”的正规操作就很明确了发一个新版本然后在所有引用处换上带新版本的 URL。发布 npm 包的核心步骤并不复杂# 在项目根目录执行patch 版本自动 1 npm version patch # 查看 package.json 确认版本号确实变了 cat package.json | grep version # 发布到 npm registry npm publishnpm version patch 会把版本号从 1.0.0 变成 1.0.1同时会自动打一个 git tag。你当然也可以手动改 package.json 里的 version 字段但我强烈建议用 npm version 系列命令因为它能保证 git tag 和 package.json 版本号永远同步少很多手滑写错版本号的机会。发布完成之后理论上 jsDelivr 就能拿到新文件了。这里要注意jsDelivr 不是实时从 npm registry 读文件的它有自己的后台同步服务需要轮询或者通过 webhook 感知新版本。实测下来npm 发布后到 jsDelivr 能看到新文件通常需要等几分钟到几十分钟不等。刚 publish 完立刻访问新版本 URL 可能 404过一会儿再试就有了这很正常不用慌。3.2 发布之后 jsDelivr 同步要等多久关于同步时间我没有看到官方给过精确承诺只说会在新版本发布后自动更新。我从自己维护的几个小库来看感知是Grunt 和 webpack 的库同步特别快奇怪但真实。如果你 publish 之后五分钟去访问/npm/xxx新版本号/xxx.js仍然 404可以先用npm view xxx versions确认 package 确实已经发布到 registry再去 jsDelivr 的官方数据面板或者 API 查索引状态。我自己常用的验证命令是这样# 查询 npm registry 上最新版本 npm view your-package version # 直接请求 jsDelivr 的特定版本文件看是否 404 curl -I https://cdn.jsdelivr.net/npm/your-package1.0.1/index.js如果 npm 上有 1.0.1但 CDN 那边 curl 还是 404那真的只能等这是 jsDelivr 后台索引同步的速度问题不是你能通过本地操作加速的。当然如果是公司项目着急上线可以走 Purge API 强制清理一遍后面第 4 节我会单独说。3.3 不要“顺手改内容”要“顺带换版本号”我见过很多刚接触 jsDelivr 的人首选的更新方式是在原文件上修修补补然后想着让 CDN 自动刷一刷。在他们的认知里CDN 就应该像 nginx 反代那样源文件变了代理跟着就变了。但在 jsDelivr 的模型里这个思路不通。你如果要更新通过 npm 发出去的某个文件常规流程是修改源码文件。执行npm version patch升级小版本。npm publish发布新版本。把页面、配置文件、代码里引用的 URL 版本号同步升级为 1.0.1。这四个步骤一个都不能少。其中最重要的往往是第 4 步——很多人发布了新版本但引用 URL 还是老版本号自然刷新一万遍都是旧内容。这里没有任何黑魔法就是 URL 没换。3.4 GitHub 侧发布打 tag 的正确方式如果你的文件不是通过 npm 发布而是直接放在 GitHub 仓库里通过gh域名引用那更新逻辑稍微有点不一样。如果你想走“永久缓存 可控更新”的路线我建议每次发版都打 taggit add . git commit -m fix: something git push origin main # 打 tag 并推送 git tag v1.1.0 git push origin v1.1.0然后你的引用 URL 就变成https://cdn.jsdelivr.net/gh/user/repov1.1.0/file.jstag 一旦打出来内容就固定了jsDelivr 会永久缓存这个 URL。下次再更新就打一个新 tag再换 URL。这样既能享受永久缓存的好处又能保证内容可追溯——想回滚也方便把 URL 的 tag 换回上一个就行。如果你就是不想每次打 tag想省事一点可以直接用分支名https://cdn.jsdelivr.net/gh/user/repomain/file.js那 jsDelivr 最长 12 小时会刷新一次。注意“最长”它不是一个定时器到点更新而是节点上的缓存 12 小时过期后如果正好有用户请求节点才会回源拉取新内容。如果这个文件一直没什么人访问那更新可能比你预期中还要慢甚至要等下一次有一个请求触发了回源才会更新。4. Purge API手动刷新的正确姿势和代价4.1 什么场景才值得手动 purge看到这里你可能想问那我把代码错了已经发布了 1.0.1但引用的 URL 是 1.0.0永久缓存的内容是坏的怎么办不手动刷新还能怎么办这种场景就可以用 jsDelivr 的 Purge API。比如你某个版本的文件内容有严重 bug已经嵌入进大量线上页面换版本号要一个个改引用太慢了或者你用的是分支 URL但 12 小时等不起这时候 purge 一下让它立即失效是合理的操作。Purge API 本身是免费开放的不需要注册 token直接提交 URL 列表就行。它的设计目的就是给你一个“紧急退出通道”而不是让你日常频繁使用的。滥用的话会给 CDN 增加不必要的回源压力同时也未必能达到你想要的“瞬间全网更新”效果。4.2 Web 页面和 API 两种清理方式最简单的方式是打开 purge 页面https://purge.jsdelivr.net/npm/your-package1.0.0/index.js直接在浏览器地址栏访问这个 URL如果显示{status:ok}之类的响应就说明 purge 请求已经被接收了。你可以把要清理的 URL 换成自己的多个 URL 可以逗号分隔也支持通配符。比如https://purge.jsdelivr.net/npm/your-package1.0.0/*可以一次清掉整个版本的缓存。如果你是在服务器脚本里做流程化清理可以用 curl 调 APIcurl -X POST https://purge.jsdelivr.net/npm/your-package1.0.0/index.js权威官方其实也提供了带通配符的 purge 能力支持类似curl https://purge.jsdelivr.net/gh/user/repo1.0.0/*我实测下来通配符在清理整个 tag 或版本时非常方便不用一个个列文件。4.3 purge 生效时间和全球节点差异purge 请求提交之后绝对不是瞬间就能全域生效的。jsDelivr 背后是一套分布在全球的 CDN 网络每个边缘节点收到 purge 指令、重新回源、拉取新内容这个过程有快有慢。从我的体感来看同一个请求在节点密集的欧美地区可能几十秒就更新了在南美、东南亚的一些节点可能要几分钟甚至更久。所以哪怕你 purge 完了也不要急着对着一张全球地图一点点验证每个地方的响应头这没有意义。只要确认 purge 请求成功返回接下来让时间给药就行。还有一个坑purge 之后如果原 URL 的内容没有真正改变纯属白忙。比如你改了源码但忘了跑构建发到 npm 上的还是旧文件那你 purge 十遍也没用回源拉回来的还是那个坏文件。排查的时候一定要先确认源文件内容正确再考虑 CDN 的问题。4.4 动永久缓存 URL 之前想清楚永久缓存 URL 是可以 purge 的但我不建议你把它当成日常运维工具。原因很简单一个永久缓存的 URL意味着它天生就适合承载大量流量。如果你动不动就 purge 它CDN 节点被迫频繁回源这个 URL 的缓存命中率会下降加载速度会受影响而且你也等于把“永久缓存”的好处白白扔掉了。如果你想长期、稳定地更新一个资源最佳姿势永远是换一个新版本号的 URL而不是去 purge 老 URL。purge 只适合做紧急止血不适合做常规发布流程。打个比方永久缓存 URL 就像一本已经印刷发行的书你想改内容正常的做法是出修订版而不是在旧书里用涂改液一页一页改。Purge API 的作用是回收渠道不是改版工具。5. 排查缓存不更新一条完整的链路5.1 头号翻车点改了文件没改 URL我先说一个我见过的最高频问题某团队发版后群里有人喊“jsDelivr 缓存没更新”然后把旧文件的 URL 发出来请求头看了一遍又一遍最后发现他们根本没有换版本号连 npm 包名后面的版本号都还是老的。这种情况你不管怎么排查 CDN、怎么清浏览器缓存都没用。因为 CDN 层面它服务的就是一个不可变文件旧 URL 的内容永远不会变。遇到“缓存不更新”我建议你先把引用 URL 和 npm/GitHub 上的最新版本比一比如果版本号就不对问题根本不值得继续往下查。所以排查第一步永远是确认源站npm registry 或 GitHub上的文件内容已经是新版本。确认你访问的 URL 里的版本号/commit hash 已经指向新版本。只有这两点都成立才进入 CDN 缓存的排查。5.2 用响应头判断到底卡在哪一层如果 URL 版本号没问题但访问到的内容确实还是旧的那就需要靠响应头来判断了。用 curl 查看响应头的命令很简单curl -I https://cdn.jsdelivr.net/npm/your-package1.0.1/index.js重点关注这几个字段字段含义age这个文件在 CDN 节点缓存中已经存在了多少秒cache-control客户端浏览器能缓存多久jsDelivr 一般会带public, max-age31536000, immutablevia经过的代理/Varnish 节点信息x-cache本次请求是 HIT命中缓存还是 MISS未命中回源如果x-cache是 HIT 且age数字很大说明这个文件在当前节点上缓存了很久。你这个时刻回源拿到的是边缘节点的旧缓存。这时候有两种做法等它到期或者去 purge 这个 URL。如果x-cache是 MISS说明节点本地没有缓存刚才回源拉过但源站返回的内容有问题那就继续去查源站文件。这里有一个容易混淆的点正常 CDN 的cache-control可能告诉浏览器“一年内别来烦我”但 CDN 节点本身是否过期是通过内部 TTL 控制的不一定完全等于cache-control。jsDelivr 的做法是两条线永久缓存内容响应头同样会带着immutable式的长缓存时间所以浏览器也不会频繁请求。5.3 浏览器缓存与 CDN 缓存的二次确认很多人分不清自己遇到的是浏览器缓存还是 CDN 缓存判断方法其实很简单用 curl 访问一次 URL如果 curl 拿到的是新内容但浏览器打开的页面是旧内容那大概率是浏览器缓存。打开浏览器开发者工具在 Network 面板勾选 “Disable cache”再刷新一次。如果这时候能拿到新内容同样说明是浏览器缓存。更省事的办法是开一个无痕窗口直接测无痕窗口默认不保留历史缓存测出来的结果最接近 CDN 真实状态。我自己工作里的习惯是先 curl再无痕窗口。curl 是命令行里的纯网络请求不受浏览器缓存影响适合确认 CDN 层无痕窗口适合确认整条链路在真实浏览器环境下的表现。两个都通过之后才能说 CDN 缓存真的没问题。5.4 npm 发布后同步慢的问题定位还有一种情况你遇到的是——不是旧内容而是 404。npm publish 成功了 10 分钟访问https://cdn.jsdelivr.net/npm/pkg1.0.1/index.js却一直 404。这大概率是 jsDelivr 的后台索引还没同步到新版本说明它的后台服务还没从 npm registry 抓到 1.0.1 这个版本或者抓到了但还没有构建出文件路径列表。可以用npm view pkg version确认 npm 侧确实已经有这个版本了然后去访问https://data.jsdelivr.com/v1/packages/npm/pkg1.0.1看看 jsDelivr 的索引 API 是否返回文件列表。如果 API 返回 404 或空数据那就是后台同步滞后只能等。如果 API 能返回文件列表但 CDN 访问还是 404那可能是边缘节点路由的问题可以 purge 一下试试。据我观察npm 包发布后 jsDelivr 的同步延迟一般在几分钟到几十分钟偶尔有超过一个小时的但不多。等的时候不要反复去 purge因为源文件还没被索引purge 一个不存在的 URL 没有意义。5.5 query string 能不能绕过 CDN 缓存有些前端同学遇到缓存不更新第一反应是给 URL 加?v1这种 query string比如https://cdn.jsdelivr.net/npm/pkg1.0.0/index.js?v20250101从浏览器角度看这确实是一个新 URL浏览器不会命中本地缓存CDN 节点也会把?v20250101当成一个新的缓存 key 处理所以你会拿到新内容。但这有一个问题如果你真的想拿“新内容”你其实是请求了一个带新参数的 URL绕过了旧缓存。旧缓存还在只是没人访问了而已。这其实算一个临时绕过方案也不算全错。但它有几个副作用URL 变得不好看、不好维护如果你构建工具不自动处理手动维护 query 版本号也很容易漏并且从 CDN 角度它没有清掉旧缓存只是多了一条新缓存资源浪费。我更推荐的做法是直接改版本号路径而不是加 query。因为版本号路径天然就是 jsDelivr 永久缓存设计想让你走的路query string 只是偏门解法救急可以别当常规。6. 进阶把“自动更新”做成可控流水线6.1 构建工具注入版本号既然 jsDelivr 的自动更新核心是“换 URL”那最好把它变成构建流水线里自动完成的一步而不是每次发布前手工去改 HTML 或配置文件里的引用。如果你是 Vite 项目可以考虑在构建时通过环境变量把 npm 版本号注入到路径里。比如// vite.config.js export default defineConfig({ define: { __APP_VERSION__: JSON.stringify(process.env.npm_package_version), }, });然后在代码里拼 CDN URLconst cdnBase https://cdn.jsdelivr.net/npm/your-package${__APP_VERSION__};这样每次npm version patch npm publish之后构建出的产物自然会带上新版本号。我用这种方式维护过几个小的前端加载器效果非常省心。6.2 publish 后自动 purge 的一键脚本有些场景是你的文件在 npm 包里的某个子路径而用户还是习惯直接访问不带版本号的入口 URL。这时候发布完想要“智能切换”可以写一个发布脚本在 npm publish 之后自动 purge 最新的入口 URL。下面是一个 Node 脚本的简单示意// scripts/purge.mjs const urls process.argv.slice(2); const resp await fetch( https://purge.jsdelivr.net/${urls.join(,)}, { method: POST } ); console.log(await resp.json());然后在 npm scripts 里串联起来{ scripts: { release: npm version patch npm publish node scripts/purge.mjs npm/pkglatest/index.js npm/pkg/index.js } }这里要注意/npm/pkg/index.js这类 URL 平时会 302 跳到具体版本purge 之后 CDN 重新回源时又会重新获取 registry 里的最新版本信息所以如果你用的是不带版本号的入口链接发布后 purge 一下确实能加速它切到新版。但要是你用了带版本号的永久缓存 URLpurge 只会让旧内容失效并重新回源拉同一份旧内容对“切换新版本”没有帮助。6.3 用 jsDelivr 的 API 验证文件最新状态自动发布之后怎么验证我推荐用 jsDelivr 的开放 API 做检查而不是傻等浏览器刷新# 获取 npm 包的版本信息 curl https://data.jsdelivr.com/v1/packages/npm/your-package # 获取某个版本的文件列表 curl https://data.jsdelivr.com/v1/packages/npm/your-package1.0.1如果 API 返回的版本列表里已经有 1.0.1说明 jsDelivr 索引已经同步完成。这时候再 curl 一下 CDN 上的具体文件看是否 200基本就能确认这次发布在 CDN 侧真的可用了。这套验证逻辑我在发布脚本里跑了很多次很稳定。6.4 我现在的做法最后说一下我自己目前在实际项目里的做法。凡是放到 jsDelivr 上的库我都坚持用精确版本号 URL并且把版本号作为构建参数注入到产物里。npm 发布和 CDN 验证交给一条 release 脚本串联起来发布完自动跑 API 确认索引同步。至于 Purge API我基本只在线上出问题的时候用平时哪怕发布错了版本我也更倾向于直接发一个 patch 版本再改 URL 引用而不是去折腾旧缓存。因为在新版本号方案下旧 URL 即使内容有问题它也是历史快照不会影响新版本 URL 的使用。这年头 CDN 缓存更新的问题十个里有八个是“版本号没换”导致的剩下两个里有一个是“浏览器缓存”。把这两件事在脑子里理清楚jsDelivr 的自动更新机制就没什么秘密了。