GitHub Actions运行时npm install失败，如何排查和解决？

这个问题很典型，我之前也踩过类似的坑。ECONNRESET 说明 npm 在下载包的时候网络连接被重置了，虽然你在本地没问题，但 GitHub Actions 的运行环境是在云端的虚拟机上，网络策略和你本地完全不同。

我们一步步来排查和解决。

第一步，先确认是不是单纯的网络抖动。你可以加个重试机制，别直接跑一次 npm install 就完事。修改你的 workflow 步骤：

- name: Install dependencies

  run: |

    npm config set fetch-retries 3

    npm config set fetch-retry-mintimeout 10000

    npm config set fetch-retry-maxtimeout 60000

    npm install

这几行设置了 npm 下载失败后的重试次数和超时时间。有时候云环境临时丢包很正常，重试能解决一半的问题。

第二步，换 registry。你提到试过改镜像但没成功，可能是因为你没有正确设置。比如在中国大陆地区，官方 npm 源经常抽风。我们可以明确指定淘宝镜像：

- name: Set NPM registry

  run: npm config set registry https://registry.npmmirror.com



- name: Install dependencies

  run: |

    npm config set fetch-retries 3

    npm install

这里用的是 npmmirror，原淘宝 NPM 镜像的新域名，比原来的 registry.npm.taobao.org 更稳定。注意不要用带 /disturl= 的那种复杂配置，除非你要编译 node-gyp 模块。

第三步，考虑使用缓存。即使网络通了，每次重新下所有包也很慢，容易超时。加个缓存能减少请求次数，也能避免重复触发网络问题：

- name: Cache Node.js modules

  uses: actions/cache@v4

  with:

    path: ~/.npm

    key: ${{ runner.OS }}-node-${{ hashFiles('**/package-lock.json') }}

    restore-keys: |

      ${{ runner.OS }}-node-

这个缓存会把 ~/.npm 目录（也就是 npm 的全局缓存）存下来，下次命中的话，很多包就不用重新下载了。key 用 package-lock.json 的哈希值，确保依赖变了才会重新安装。

这里需要注意，如果你用了 pnpm 或 yarn，路径和 key 要对应调整。比如 yarn 是 ~/.cache/yarn，pnpm 是 ~/.pnpm-store。

第四步，如果上面都不行，可能是企业级网络限制或者某些特定包的问题。这时候要打开调试日志看细节：

- name: Install with verbose log

  env:

    NODE_DEBUG: npm

  run: npm install --verbose

加上 --verbose 和 NODE_DEBUG 环境变量后，你会在日志里看到具体是哪个请求发出去、收到什么响应。比如你会发现它卡在 GET https://registry.npmjs.org/axios 这一步，然后 timeout。这样就能判断是 DNS 解析问题还是 TCP 连接问题。

第五步，终极方案：换包管理器。npm 本身在网络处理上不如 pnpm 或 yarn modern 做得好。你可以试试用 pnpm：

先装 pnpm：

- name: Install pnpm

  uses: pnpm/action-setup@v3

  with:

    version: 8



- name: Setup Node

  uses: actions/setup-node@v4

  with:

    node-version: '18'

    cache: 'pnpm'



- name: Install dependencies

  run: pnpm install --frozen-lockfile

pnpm 的优势在于它用的内容寻址存储，对网络波动容忍度更高，而且安装速度更快。--frozen-lockfile 可以保证 CI 环境不自动生成新的 lock 文件，更安全。

最后补充一个冷知识：GitHub Actions 的 ubuntu-latest 有时候会从不同区域调度机器，有些地区的出口 IP 对外网访问有限制。如果你发现偶尔成功偶尔失败，可以尝试固定 Node.js 版本 + 开启自定义缓存 + 使用 pnpm，组合拳打下去基本都能稳住。

总结一下推荐的最终 workflow 片段：

jobs:

  build:

    runs-on: ubuntu-latest

    steps:

      - uses: actions/checkout@v4



      - name: Use Node.js 18

        uses: actions/setup-node@v4

        with:

          node-version: '18'

          cache: 'npm'



      - name: Cache Node.js modules

        uses: actions/cache@v4

        with:

          path: ~/.npm

          key: ${{ runner.OS }}-node-${{ hashFiles('**/package-lock.json') }}

          restore-keys: |

            ${{ runner.OS }}-node-



      - name: Set NPM registry to npmmirror

        run: npm config set registry https://registry.npmmirror.com



      - name: Install dependencies

        run: |

          npm config set fetch-retries 3

          npm config set fetch-retry-mintimeout 10000

          npm install

照这个配，99% 的 npm install 失败都能解决。要是还有问题，那得具体看日志里断在哪个包了，可能是那个包本身坏了或者被删了。

这问题我之前也踩过，ECONNRESET 大部分情况是网络不稳定或者 registry 被墙了。GitHub Actions 的 ubuntu-latest 机器在海外，按理说访问 npm 官方源不该有问题，但实际经常抽风，尤其是安装 axios 这种依赖多的包。

第一步先确认是不是 registry 的锅。你虽然试过换镜像，但记得转义，比如你用淘宝源得这么写：

- name: Install dependencies

  run: npm install --registry https://registry.npmmirror.com

npm.taobao.org 已经重定向到 npmmirror.com 了，旧地址可能失效。

如果还不行，加个 npm 的日志级别看看详细错误：

- name: Install with verbose log

  run: npm install --verbose

看日志里卡在哪一步。有时候是某个特定包的 tarball 下不动，可能是 CDN 问题。这时候可以考虑用 npm ci 替代 npm install，更快也更稳定，前提是你有 package-lock.json：

- name: Use npm ci

  run: npm ci --registry https://registry.npmmirror.com

另外别忘了给步骤加个缓存，不然每次重新下载，出错概率更高：

- name: Cache node modules

  uses: actions/cache@v3

  with:

    path: ~/.npm

    key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}

    restore-keys: |

      ${{ runner.os }}-node-

最后如果还是断，可能是 GitHub 自身网络临时问题，重跑 workflow 试试。但长期来看建议锁定 registry 到 npmmirror + 用 npm ci + 缓存三件套，基本能解决 95% 的 install 失败。