package-lock.json深入与冲突处理

package-lock.json记录依赖树完整快照，确保跨环境安装一致性。

package-lock.json结构

顶层结构

JSON

{
  "name": "my-app",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {},
  "dependencies": {}
}

packages字段（v3核心）

JSON

{
  "packages": {
    "": {
      "name": "my-app",
      "dependencies": {
        "lodash": "^4.17.21"
      }
    },
    "node_modules/lodash": {
      "version": "4.17.21",
      "resolved": "https://registry.npmjs.org/lodash/-/lodash-4.17.21.tgz",
      "integrity": "sha512-...",
      "license": "MIT"
    },
    "node_modules/lodash/node_modules/some-dep": {
      "version": "1.0.0",
      "resolved": "https://registry.npmjs.org/some-dep/-/some-dep-1.0.0.tgz",
      "integrity": "sha512-..."
    }
  }
}

lockfileVersion版本

版本	npm版本	特点
1	v5-v6	仅dependencies字段
2	v7+	新增packages字段
3	v8+	仅packages字段，dependencies为兼容保留

lockfileVersion=3时，packages是权威数据源，dependencies仅为向后兼容保留。

resolved与integrity

resolved

包的下载地址，指向具体tgz文件：

JSON

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

使用镜像源时resolved仍指向原始registry
离线或内网环境需确保resolved可达

integrity

子资源完整性校验值（Subresource Integrity），格式为算法-哈希：

JSON

{
  "integrity": "sha512-v2kDEe57lecTulaDIuNTPy3Ry4gLGJ6Z1O3vE1krgXZNrsQ+LftGHVBJvC3s0Z1L0k3W8+0/T06FgO9nPcilQ=="
}

常用算法：

sha512：默认算法
sha384：部分旧包使用

校验机制

npm安装时比对下载内容的integrity与lock中记录的值：

匹配：安装成功
不匹配：拒绝安装，报integrity验证失败

integrity校验防止包被篡改或CDN缓存污染。如果integrity验证失败，不要删除integrity字段绕过，应排查网络或registry问题。

lock文件冲突处理

常见冲突场景

两人同时添加不同依赖
一人升级依赖版本，另一人添加新依赖
合并分支时lock文件与package.json不同步

处理策略

策略一：重新生成（推荐）

Bash

# 删除lock文件和node_modules
rm -rf node_modules package-lock.json

# 重新安装
npm install

此方法简单粗暴，但可能引入间接依赖版本变化。

策略二：接受一方后更新

Bash

# git合并时选择一方的lock
git checkout --theirs package-lock.json

# 基于当前package.json更新lock
npm install

策略三：npm ci验证（CI中）

Bash

# lock与package.json不同步时报错
npm ci

预防措施

及时提交lock文件到Git
升级依赖时单独提PR，不与其他改动混合
CI中使用npm ci确保一致性
使用renovate/dependabot自动化依赖更新

package-lock.json必须提交到Git。.gitignore中不应包含package-lock.json（库项目除外，库项目可选择不提交）。

要点总结

lockfileVersion=3以packages字段为权威数据源
resolved记录下载地址，integrity用sha512校验包完整性
integrity验证失败说明包可能被篡改，不应绕过
冲突时推荐删除lock重新生成，或接受一方后npm install更新
package-lock.json必须提交到Git（应用项目）