症状
本篇调试指南针对“npm ci 失败 — package.json 与 package-lock.json 不同步”。内容涵盖可观察的症状、可复现的诊断路径、根本原因、具体修复方式，以及如何验证修复并防止回归。
可观察到的症状包括：
- npm ci 失败并提示 package.json 与 package-lock.json 不同步
- 本地 install 可用，CI install 失败
- 错误列出缺失或无效的包
诊断
先在隔离环境中复现故障，再按顺序执行以下检查，逐步缩小范围。
步骤 1
npm install && git add package-lock.json常规 install 会重写 lock 以匹配 package.json，从而解决不匹配。
步骤 2
rm -rf node_modules && npm ci干净环境下的 ci 安装通过，即确认 lock 与清单已一致。
常见诱因（按出现频率排序）：
- 新增或升级依赖时未更新 lockfile
- lockfile 缺失或未提交
- 合并处理了 package.json 却留下陈旧的 lockfile
根因
npm ci 严格依据 package-lock.json 安装，并在 lock 与 package.json 不匹配时拒绝运行。任何清单变更若无对应的 lock 更新都会触发该错误，这是为保证可复现性的设计。
修复
运行 npm install 重新生成 lock，提交 package-lock.json，并在 CI 中按预期使用 npm ci；切勿删除 lock 或在 CI 回退到 install。
注意：为绕过错误而把 CI 改为 npm install 会重新引入不可复现构建，并可能造成依赖版本漂移。
# local: regenerate and commit the lock
npm install
npm test
git add package.json package-lock.json
git commit -m "sync lockfile"
# CI: strict, reproducible install
npm ci --no-audit --prefer-offline验证
在干净检出下运行 npm ci 并确认完成；验证 install 后 git status 无 lock 变化。
修复后补充一条回归测试，复现原始症状，防止问题再次出现。
这类故障通常是环境问题而非纯逻辑错误，因此在缺陷记录中应写明完整命令、环境变量与工作目录。请用最小的脚本复现，待最小用例清楚后再扩大范围。为这类故障准备一份简短的排查清单，能显著减少下次排障时间。