npm 装包时 EINTEGRITY 完整性校验失败

FreeGuideOnline 最新 2026-07-04

npm ERR! code EINTEGRITY npm ERR! sha512-... integrity checksum failed when using sha512: wanted sha512-... but got sha512-...


**EINTEGRITY** 表示包的完整性校验失败。npm 在下载包时会对比包的 `integrity` 字段（通常是 `sha512` 哈希值）与实际下载内容的哈希值。如果两者不匹配，就会抛出此错误。这意味着你收到的文件与 `package-lock.json` 或注册表中记录的应该下载的文件不一致。

> 完整性校验是 npm 的一项重要安全机制，用来防止中间人攻击或下载到被篡改的包。

## 为什么会发生完整性校验失败

在动手修复之前，先理解常见的原因，这能帮你避免反复踩坑：

1. **本地缓存损坏**  
   npm 会把下载的包缓存到 `~/.npm` 目录。如果缓存中的包数据不完整或被意外修改，再次使用缓存时就会报错。

2. **`package-lock.json` 与实际不一致**  
   这种情况常在协作开发中出现：有人手动修改了 `package-lock.json`，或者通过不同的 npm 版本生成/合并了该文件，导致其中的 `integrity` 哈希与远程注册表不匹配。

3. **网络传输问题**  
   下载过程中网络中断、代理或镜像源返回了不完整的内容，最终写入缓存或 `node_modules` 的文件不完整。

4. **npm 自身 bug 或版本过低**  
   极少数情况下，某些 npm 版本在处理哈希计算时存在缺陷，尤其是从 npm 5/6 升级到 npm 7+ 时。

5. **锁定文件使用了过时的注册表信息**  
   如果你切换过镜像源（例如从官方切换到淘宝镜像），且 `package-lock.json` 里的 `resolved` 和 `integrity` 仍指向旧源，就会发生不匹配。

## 逐步排查与解决

下面按从易到难的顺序，给出最有效的修复步骤。每步执行后都可以重新尝试 `npm install` 来验证。

### 1. 清除 npm 缓存

这是解决 EINTEGRITY 最快的办法，尤其适用于缓存损坏的情况。

```bash
npm cache clean --force

--force 强制清空缓存目录。
执行后再运行 npm install，npm 会重新下载所有依赖。

如果清完缓存仍报错，可以试着手动删除缓存目录：
rm -rf ~/.npm/_cacache   # macOS / Linux
rmdir /s /q %userprofile%\.npm\_cacache   # Windows

2. 删除 `node_modules` 和 `package-lock.json` 后重装

如果缓存清理后问题依旧，很可能是 package-lock.json 本身已损坏或包含错误的完整性哈希。

rm -rf node_modules package-lock.json   # macOS / Linux
# 或者在 Windows CMD 中执行：
# rmdir /s /q node_modules
# del package-lock.json

npm install

这会让 npm 基于 package.json 重新生成全新的 package-lock.json，并重新下载所有依赖，大部分情况下能直接修复。

3. 检查并统一 npm 版本

团队协作时，不同成员使用的 npm 版本不同，可能导致 package-lock.json 的 lockfileVersion 不一致，从而出现完整性错误。

npm -v          # 查看当前版本
npm install -g npm@latest   # 更新到最新稳定版

然后删除 node_modules 和 package-lock.json，重新执行 npm install。

建议在项目根目录添加 .npmrc 文件，指定 lockfile-version=3（或团队统一版本），以保持一致性。

4. 核对镜像源的一致性

如果你使用了非官方的镜像（如淘宝镜像），请确保 package-lock.json 中的 resolved 字段也指向相同的镜像，而不是混用旧源。

临时使用官方源重试：

npm install --registry=https://registry.npmjs.org/

永久修改镜像源：

npm config set registry https://registry.npmjs.org/

随后删除 node_modules 和 package-lock.json，再执行安装。如果确认需要使用镜像，确保团队所有人都配置了相同的镜像，并且 package-lock.json 是统一生成的。

5. 使用 `npm ci` 验证

如果你有 package-lock.json，并希望严格按照它安装（比如在 CI 环境），可以尝试跑一次 npm ci，它会直接根据锁定文件的 integrity 校验每个包。如果 npm ci 报 EINTEGRITY，问题一定出在缓存或 package-lock.json 上。此时按上述步骤清除缓存和重装即可。

6. 手动修正特定包的完整性值（高级）

当只有个别包反复报错，且上述方法无效时，可以考虑手动更新该包在 package-lock.json 中的 integrity 值。

步骤：

打开 package-lock.json，找到报错包对应的条目。

查看该包在 "dependencies" 下的 "resolved" 字段，比如：

"resolved": "https://registry.npmjs.org/lodash/-/lodash-4.17.21.tgz"

删除该包的 "integrity" 字段，然后执行：
```
npm install --save lodash@4.17.21   # 替换为实际包名和版本
```
或直接运行 npm install，npm 会重新下载该包并重新计算完整性。

注意：手动编辑 package-lock.json 容易引入错误，建议只在其他方法都失败时使用。

7. 禁用完整性检查（不推荐，仅用于临时绕过）

如果你急于运行项目，可以临时跳过校验，但这极其不安全，永远不要在生产环境中使用。

npm install --no-audit --no-fund --no-optional --ignore-scripts --strict-ssl=false --legacy-peer-deps
# 或者更直接地：
npm install --no-optional --ignore-scripts

2. 删除 node_modules 和 package-lock.json 后重装