NPM缓存机制与性能调优

NPM缓存是提升依赖安装速度的核心机制，理解其原理才能有效调优。

NPM缓存机制原理

缓存存储结构

NPM缓存目录默认位于 ~/.npm，内容按 make-fetch-happen 规范组织：

# 查看缓存路径
npm config get cache

# 缓存目录结构
~/.npm/_cacache/
  ├── content-v2/    # 包体内容（按hash存储）
  ├── index-v5/      # 索引元数据
  └── tmp/           # 临时文件

每个包体以 SHA512 hash 为文件名存入 content-v2，索引通过 integrity 字段关联内容，实现内容寻址去重。

缓存命中流程

npm install lodash
# 1. 查询 index-v5 是否有 lodash@4.17.21 的索引
# 2. 校验 integrity hash (sha512-...)
# 3. 命中则从 content-v2 解压，未命中则发起网络请求
# 4. 下载后写入缓存，再解压到 node_modules

缓存验证策略

# 查看缓存验证配置
npm config get prefer-online   # 默认 false，优先网络
npm config get prefer-offline  # 默认 false，优先缓存
npm config get maxsockets      # 默认 15，并发连接数

缓存验证使用 ETag / Last-Modified，若远程返回 304 则复用缓存体，避免重复下载。

缓存管理命令

# 验证缓存完整性
npm cache verify

# 强制清除缓存
npm cache clean --force

# 查看缓存统计
npm cache ls  # npm < 7
du -sh ~/.npm/_cacache

npm cache verify 会删除损坏条目并回收磁盘空间，建议定期执行。

依赖安装性能调优

安装参数优化

# 生产环境跳过可选依赖
npm install --omit=optional

# 禁用进度条（减少TTY开销）
npm install --no-progress

# 并行下载控制
npm install --maxsockets=20

# 优先使用缓存
npm install --prefer-offline

# 跳过审计和fund提示
npm install --no-audit --no-fund

CI 环境最佳配置

# CI 中推荐组合
npm ci --prefer-offline --no-audit --no-fund --omit=optional

npm ci 严格按 package-lock.json 安装，删除现有 node_modules 后全量安装，比 npm install 快 30%+。

锁文件优化

// package-lock.json 中关键性能字段
{
  "name": "my-app",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "node_modules/lodash": {
      "version": "4.17.21",
      "resolved": "https://registry.npmmirror.com/lodash/-/lodash-4.17.21.tgz",
      "integrity": "sha512-v3k...=="
    }
  }
}

• lockfileVersion: 3 使用扁平化 packages 结构，解析更快
• resolved 指向镜像源可加速下载
• integrity 确保缓存命中时无需二次验证

网络层调优

# 使用国内镜像
npm config set registry https://registry.npmmirror.com

# 设置代理
npm config set proxy http://127.0.0.1:7890
npm config set https-proxy http://127.0.0.1:7890

# DNS 缓存（Node 18+）
NODE_OPTIONS="--dns-result-order=ipv4first" npm install

全局缓存复用

# CI 缓存策略：缓存 .npm 目录
# GitHub Actions 示例
# - uses: actions/cache@v3
#   with:
#     path: ~/.npm
#     key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
#     restore-keys: ${{ runner.os }}-npm-

缓存 key 基于 lock 文件 hash，依赖不变时直接命中，跳过全部网络请求。

要点总结

• NPM 缓存基于内容寻址（SHA512 hash），索引与内容分离存储于 _cacache
• prefer-offline 优先缓存、prefer-online 优先网络，按场景选用
• CI 环境必用 npm ci，搭配 --prefer-offline --no-audit --no-fund
• 锁文件 lockfileVersion: 3 结构更扁平，解析更快
• 缓存 ~/.npm 目录是 CI 加速的关键，按 lock 文件 hash 做 cache key