Answers developer tool questio…

# GitHub Actions npm install 超时：缓存加速方案

一、问题定位

npm install 超时的常见原因：

• 每次都从 npm registry 全量下载依赖，国内或网络慢时尤其容易超时
• 未配置缓存，workflow 每次冷启动
• package-lock.json 缺失，导致版本解析耗时

二、推荐方案：cache 配置（最简单）

如果你的 workflow 使用官方 actions/setup-node，直接加 cache 参数即可：

```yaml

• uses: actions/setup-node@v4

with:

node-version: '20'

cache: 'npm' # 自动缓存 ~/.npm 目录

```

原理：基于 package-lock.json 计算哈希作为缓存 key，依赖未变化时直接复用缓存，install 速度大幅提升。

三、进阶方案：actions/cache 手动控制

```yaml

• uses: actions/cache@v4

with:

path: ~/.npm

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

restore-keys: |

${{ runner.os }}-node-

```

• restore-keys 提供兜底：lock 文件变了也能恢复部分旧缓存
• 也可缓存 node_modules（有争议，可能因平台差异出问题，一般不推荐，更推荐缓存 npm 下载目录）

四、配合调整，进一步提速

• 锁定依赖：确保 package-lock.json 提交到仓库，并用 npm ci 替代 npm install（更快、更稳定，按 lock 精确安装）
• 提高超时容忍度：npm config set fetch-timeout 600000 或设置环境变量 npm_config_fetch_timeout
• 减少生产依赖安装：部署场景可加 npm ci --omit=dev，跳过 devDependencies
• 私有源加速：如访问 npm 官方源慢，可配置镜像或使用 AWS CodeArtifact

五、缓存失效排查

• lock 文件变化 → 缓存 key 变化，属正常
• 分支默认缓存不共享：feature 分支只能复用默认分支的缓存
• 缓存有总量限制（仓库级别约 10GB，超出按 LRU 淘汰）

六、完整示例片段

```yaml

steps:

• uses: actions/checkout@v4
• uses: actions/setup-node@v4

with:

node-version: '20'

cache: 'npm'

• run: npm ci --omit=dev

# 后续部署到 EC2 的步骤

```

按上述配置后，依赖命中缓存时 install 通常从数分钟降到数十秒级别，超时问题基本可解决。