首页 > 科技周边 > 业界新闻

npm 依赖供应链审计中的锁文件保留策略

来源：17golang原创

时间：2026-10-28 10:35:26 235浏览收藏

npm 依赖供应链审计中，锁文件最应该保留的是“这次构建到底解析出了哪棵依赖树”。因此，主项目应把 package.json 和 package-lock.json 一起提交，保留依赖变更的 Git 历史；CI 和部署用 npm ci 按锁定结果安装。漏洞报告、修复决定和发布产物仍要单独记录，不能把“有锁文件”写成“已经安全”。

官方地址：https://docs.npmjs.com/

要点速览

保留 package-lock.json，审计它的差异，不把 node_modules 当成审计材料。
用 npm ci 消费锁定树；生成锁文件时影响树形状的配置也要随项目保存。
锁文件解决可复现和可追溯，npm audit 与人工处置负责漏洞判断。

先划定锁文件的审计职责

package.json 更像“允许使用什么版本范围”的声明，package-lock.json 则记录一次解析后得到的具体版本、依赖位置和解析来源。审计时真正有价值的是两者的变更关系：谁新增了直接依赖，哪些间接依赖随之变化，版本范围是否被扩大，解析来源是否从注册表变成了 Git 或远程压缩包。

这三类材料不要混为一谈：

材料	保留目的	不能替代的结论
package.json	记录直接依赖与版本范围	不能说明最终间接依赖版本
package-lock.json	固定并展示解析后的依赖树	不能单独判断是否存在漏洞
npm audit 结果	记录当前已知风险及修复建议	不能代替变更审查与发布责任

package.json、package-lock.json 与 npm audit 在供应链审计中的职责边界原创说明图 — 图1：锁文件审计职责边界说明图，区分版本范围、解析依赖树与漏洞判断；这是原创结构说明图，不是运行截图。

npm 官方文档说明，package-lock.json 用来描述一次生成的精确依赖树，并且适合提交到源码仓库。这个定位决定了保留策略：它要跟着源代码提交，而不是只在发布服务器上临时生成。

把 package-lock.json 纳入版本库

主项目的最小规则是：修改直接依赖时同时提交 package.json 与 package-lock.json；代码评审中查看锁文件的增删改；不提交 node_modules，也不把开发机的 node_modules/.package-lock.json 当作团队共享锁文件。后者服务于本地安装性能，生命周期和项目根目录的锁文件不同。

# 只忽略本机安装结果，不忽略项目根目录的锁文件
node_modules/

# npm 的隐藏锁文件属于本地安装树，不作为团队审计材料
node_modules/.package-lock.json

评审锁文件时，可以按“直接依赖—间接变化—解析来源”三列阅读，而不是只看文件行数。若一次只想升级依赖元数据或处理审计修复，应在提交说明中写清是版本升级、锁树重算还是来源调整，避免把大范围重排伪装成普通补丁。

让 CI 使用锁定安装

npm ci 的职责是消费已有锁文件：项目必须存在 package-lock.json 或 shrinkwrap，锁文件与 package.json 不一致时命令会失败，并且安装过程不会回写它们。这种失败是有价值的，因为它会尽早暴露“提交了半套依赖变更”的问题。

# 示例：CI 中按仓库锁文件安装，再运行项目自己的检查脚本
steps:
  - run: npm ci # 锁文件与 package.json 不一致时直接失败
  - run: npm test # 测试只消费刚刚按锁定树安装的依赖

如果生成锁文件时使用了会改变依赖树形状的参数，例如 --legacy-peer-deps 或 --install-links，npm 文档要求安装时保持相同设置。实践中应把项目级 .npmrc 纳入版本库，或者在 CI 配置中明确相同参数，避免本地能装、流水线却无法复现。

npm 锁文件从依赖变更到 CI 安装和发布归档的原创生命周期结构图 — 图2：锁文件保留生命周期结构图，展示依赖变更、评审、npm ci 安装和发布归档之间的责任关系；这是原创结构说明图，不代表真实执行结果。

按变更审计与归档

每个依赖变更至少保留四个关联点：变更请求、审阅过的 package-lock.json diff、CI 使用的提交、最终发布版本。发布归档不必复制一份巨大的 node_modules；保留源码提交、锁文件、构建配置和产物标识，已经能让后来的人重新理解依赖树来自哪里。

漏洞处理则走另一条记录链。npm audit 需要锁文件来描述依赖，返回的是已知漏洞与修复建议；如果运行 npm audit fix --package-lock-only，它可以只更新锁文件，但这仍然是一次需要评审的依赖变更，不应直接覆盖原始审计证据。高风险或破坏性升级还要由维护者确认兼容性、测试结果和回滚方案。

因此，团队可以采用“锁文件长期保留、审计结果按运行归档、修复通过变更请求落地”的组合：锁文件跟随每个提交，审计结果带时间和提交号，修复记录说明是否只改 lockfile、是否改变直接依赖，以及哪次发布开始生效。