6月5日 21:38

npm 缓存机制详解：4 个方法加速依赖安装

每次 npm install 都从网络下载包？不是的——npm 会把下载过的包缓存在本地，下次安装同一个版本时直接从缓存读取，跳过网络请求。理解缓存机制，能让 CI 构建更快、排查依赖问题更精准。

缓存存在哪里

bash
npm config get cache
# macOS/Linux: ~/.npm
# Windows: %AppData%/npm-cache

缓存目录结构：

shell
~/.npm/_cacache/
├── content-v2/    # 包的原始内容（按 hash 存储）
├── index-v5/      # 包的元数据索引
└── tmp/           # 临时文件

_cacache 是 npm 缓存的核心——它基于 content-addressable storage（内容寻址存储），每个文件按内容的 hash 命名，相同内容只存一份。

缓存怎么工作的

安装一个包时，npm 的流程是：

查询 registry 获取包的元数据（版本号、tarball 地址）
检查本地缓存中是否已有该 tarball（通过 hash 比对）
缓存命中 → 直接从本地解压，跳过下载
缓存未命中 → 下载 tarball，存入缓存，再解压

bash
# 强制忽略缓存，全部重新下载
npm install --no-cache

# 验证缓存完整性
npm cache verify

npm cache verify 会检查缓存文件的完整性，删除损坏的条目并输出统计信息。如果遇到安装报错怀疑是缓存损坏，先跑一次这个命令。

加速依赖安装的 4 个方法

1. 锁文件是第一优先级

bash
# 有 package-lock.json 时，npm 按锁文件精确安装，不需要重新解析依赖
npm ci

npm ci 比 npm install 快 2-3 倍——它直接按 package-lock.json 安装，跳过依赖解析，而且会先删掉 node_modules 保证干净环境。CI 环境永远用 npm ci，不用 npm install。

2. 配置 registry 镜像

国内访问 npm 官方源经常超时，换成镜像源能大幅加速：

bash
# 淘宝镜像（最常用）
npm config set registry https://registry.npmmirror.com

# 验证
npm config get registry

# 临时使用
npm install --registry=https://registry.npmmirror.com

3. 利用 CI 缓存目录

GitHub Actions / GitLab CI 都支持缓存目录。把 npm 缓存目录缓存下来，下次构建就能直接复用：

yaml
# GitHub Actions 示例
- name: Cache npm
  uses: actions/cache@v3
  with:
    path: ~/.npm
    key: ${{ runner.os }}-npm-${{ hashFiles('**/package-lock.json') }}
    restore-keys: |
      ${{ runner.os }}-npm-

- run: npm ci

锁文件没变时 key 完全匹配，缓存命中率 100%。锁文件变了也会用 restore-keys 匹配部分缓存——大部分包的版本没变，仍然能命中。

4. 优先使用本地缓存

在 monorepo 或频繁切换分支的场景，不同项目的依赖大量重叠：

bash
# 查看缓存大小
npm cache ls  # 旧版
du -sh ~/.npm  # 直接看目录大小

# 不要随便清缓存！
npm cache clean --force  # 除非确认缓存损坏，否则别跑这个

很多开发者习惯性地 npm cache clean --force，然后重新安装——这等于把缓存全部清空，下次所有包都要重新下载。除非缓存验证报错，不要清缓存。

package-lock.json 和缓存的关系

package-lock.json 记录了每个依赖的精确版本和 integrity hash。npm 安装时会用这个 hash 校验缓存中的文件是否完整：

json
// package-lock.json 片段
"node_modules/lodash": {
  "version": "4.17.21",
  "resolved": "https://registry.npmjs.org/lodash/-/lodash-4.17.21.tgz",
  "integrity": "sha512-v3kCN8h1WT3dbmE...=="
}

integrity 字段就是内容的 SHA-512 hash。如果缓存中的文件 hash 不匹配，npm 会重新下载——这保证了缓存不会返回被篡改的包。

所以：package-lock.json 一定要提交到 git。没有锁文件，npm 每次都要重新解析依赖、查询 registry，安装慢且结果不确定。

常见问题

安装一直失败，报 EINTEGRITY

缓存文件损坏了，integrity 校验不通过：

bash
npm cache verify  # 先验证
# 如果还不行
npm cache clean --force  # 清缓存重试

CI 里 npm ci 比 npm install 还慢

大概率是缓存没配。检查 CI 配置是否缓存了 ~/.npm 目录。另外确认没有用 --no-cache 参数。

磁盘空间被缓存占了太多

bash
# 查看缓存大小
du -sh ~/.npm
# 清理
npm cache verify  # 先验证（会自动清理损坏条目）
npm cache clean --force  # 强制清空

长期不清理的缓存可能占几个 GB。npm cache verify 比 clean 更温和——只清理损坏和过期的条目，保留有用的缓存。

缓存策略速查

场景	建议
日常开发	不用管，缓存自动工作
CI 构建	`npm ci` + 缓存 `~/.npm` 目录
国内网络慢	换淘宝镜像源
安装报 EINTEGRITY	`npm cache verify` → 不行再 `clean --force`
切换分支后安装慢	正常，不同分支依赖可能不同，缓存命中率低
monorepo 多项目	依赖重叠多，缓存命中率高，不要频繁清缓存

标签：NPM