一个突然超时的 CI 作业

2026年5月22日23点，我写完了新版本的最后一个 PR，像往常一样 create tag，push tags，然后进入 GitHub 仓库的 Actions 界面等待构建完成自动发布 release。

过了一会我发现事情有点不对了，npm安装依赖竟然卡了10分钟了都没装好！

我翻看了之前的workflow运行记录，在没有新增依赖的情况下，只需要1分半左右就能跑完

在排除了 GitHub Actions 和 npm registry的网络问题后，我选择取消workflow并重新运行。可能只是偶发性问题。

然而，不出意外的话就出意外了：

还是卡在依赖安装，而且目前没有任何有效的日志信息。

经过了漫长的等待，终于——报错了

一行诡异的 504 错误

其中有一行报错非常的诡异：

npm error 504 Gateway Time-out - GET https://registry.npmmirror.com/webpack-virtual-modules/-/webpack-virtual-modules-0.6.2.tgz

这其中的 registry.npmmirror.com 是淘宝镜像源！

那么现在问题就明确了：GitHub Actions 的美国机器在安装依赖时使用了淘宝源，直接超时了。可是问题是，GitHub Actions怎么会使用淘宝源作为镜像地址呢？翻看了 build_frontend.yml 这个工作流文件，相关部分也没有淘宝源的痕迹。

- name: Install dependencies
  working-directory: webui/frontend
  run: npm ci

最后，通过全局搜索，我在 package-lock.json 中找到了淘宝源的地址！

"node_modules/webpack-virtual-modules": {
  "version": "0.6.2",
  "resolved": "https://registry.npmmirror.com/webpack-virtual-modules/-/webpack-virtual-modules-0.6.2.tgz",
  "integrity": "sha512-..."
}

package-lock.json 是什么？

简单说，它是 npm 自带的“依赖快照”。当你执行 npm install 时，npm 会根据 package.json 里写的版本范围（比如 ^5.0.0）算出一棵具体的依赖树，然后把每个包的精确版本、下载地址、完整性哈希全部固化到 package-lock.json 里。

它的初衷很好——保证项目在不同机器、不同时间安装出来的依赖完全一致，避免“It works on my machine”的经典悲剧。但是 npm install 和 npm ci 命令在此处有一个关键差异：

npm install：会参考 package-lock.json 中的版本和完整性信息，但不会强制使用 resolved 里的下载地址。它优先遵循当前环境的 registry 配置（比如 npm config get registry 或 .npmrc）。也就是说，即便 lock 文件里写的是淘宝源，只要你的 CI 环境配的是官方源，npm install 还是会去官方源拉取。

npm ci：它的设计目标是严格、快速、可重现。它会强制使用 package-lock.json 中的每一个字段，包括 resolved 里那个具体的 URL。它忽略当前环境的 registry 配置，直接去锁文件里写死的地址下载。

这个机制在单一 registry 环境下非常完美。但一旦本地用了淘宝源，而 CI 跑在 GitHub Actions 的美国机器上，resolved 就成了定时炸弹——它会强行拉着 CI 去访问一个可能已经对海外关门的镜像站，结果就是 504 超时，而且你翻遍工作流文件都找不到任何淘宝源的配置，因为它藏在锁文件里，像一个隐形的契约。

重新推送

所有的问题都搞明白，接下来只要在本地使用官方源重新执行一遍 npm install，并将更新后的 lockfile 重新推送到 GitHub 就能修复了。

重新推送 tag 后，依赖只花了7秒中就装好了…… 看来之前的1分半钟也是被淘宝源拖累了，而现在国外的机器可能完全访问不了淘宝源了。

晚上23：54分，ci成功发布了新版的release：

危机解除。这次事故前前后后忙活了1个小时，实际修改只花了 10 秒——在本地跑一遍 npm install --registry=https://registry.npmjs.org，然后 git add package-lock.json 再 push。。

最后顺便推广一下本篇所说的开源项目： xxynet/KiraAI

这是一个 AI数字生命项目，它可以让你轻松的搭建出属于自己的数字生命，并且在多平台活跃（QQ，telegram，discord，bilibili等），借助插件可以极大的拓展数字生命的能力边界。欢迎加入我们的社区！