技术 · 实用指南
npm ci 提示 package-lock 不同步？先核对清单、安装参数和 npm 版本，再决定是否重建
先保留失败时的输入。同一个 EUSAGE 提示可能来自依赖漂移、项目配置差异、旧锁文件或特定 npm 解析器行为。
当 npm ci 报告 package.json 与 package-lock.json 不同步时，它拒绝改写本应被冻结的依赖树。这个提示说明一致性检查失败，并不指向唯一根因。安全做法是先保留失败输入，证明哪一项发生变化，再判断应修正清单、项目配置、npm 版本还是生成的锁文件。
不要一开始就删除 package-lock.json、把 CI 改成 npm install，或加上 --force。这些动作会抹去解释失败所需的对照，并可能把一个很小的预期改动扩大成大量依赖树变化。合格的修复必须解释具体的 Missing 或 Invalid 项，在预期安装策略下复现，并留下可审查的锁文件差异。
1. 把 EUSAGE 提示当作一致性闸门
npm ci 面向自动化、可复现安装。它要求锁文件，安装前会移除已有 node_modules，并且不写入 package.json 或锁文件。当清单与锁文件不一致时，它退出而不是静默选择新依赖树，从而阻止 CI 接受未经审查的依赖变化。
尝试其他命令前先复制完整错误。保留每一条 Missing 或 Invalid、工作目录，以及命令是在仓库根目录还是 workspace 内运行。第一条带包名和版本范围的提示通常决定调查分支；最后那句通用的 npm install 建议并不能证明只有重建这一种修复。
2. 建立只读的清单、锁文件和环境台账
记录精确 commit，并确认 package.json 或 package-lock.json 是否有未提交修改。读取影响依赖树的根清单字段：dependencies、devDependencies、optionalDependencies、peerDependencies、bundledDependencies、overrides 和 workspaces。锁文件要记录 lockfileVersion，并核对 packages[""] 根节点与错误点名的包路径；不要手工修改生成的 integrity 或依赖字段。
记录 node --version、npm --version、项目 .npmrc、相关环境变量和完整 CI 命令。包含会塑造依赖树的参数，特别是 legacy-peer-deps、strict-peer-deps、install-links、omit/include 和 workspace 选择器。注册表令牌与凭据必须脱敏；目标是建立对照台账，不是公开秘密。
3. 区分预期的清单漂移与误改
如果 package.json 晚于锁文件发生变化，先确认依赖编辑是否有意且已审查。package.json 新增直接依赖而 packages[""].dependencies 中没有对应项，属于清单漂移；overrides、workspace 成员或包管理设置变化，即使常见 dependencies 区块未变，也可能改变解析树。
若改动是预期的，就在受控开发环境用项目指定的 npm 版本和配置重建锁文件；若是误改，则恢复已审查的清单。不要让 CI 每次自动修依赖树：提交生成的锁文件是源码变更，需要明确的差异与责任人审查。
4. 复现生成锁文件时的安装策略
npm ci 官方说明强调：若锁文件是用塑形参数生成的，安装时必须使用相同参数，legacy-peer-deps 是常见例子。若所有开发者和 CI 都必须使用某设置，应写入项目级 .npmrc；不要让个人用户级配置暗中决定仓库依赖树。
用相同 npm 主版本、项目 .npmrc 和 workspace 命令，在干净检出中比较失败 runner。若某环境只有加参数才通过，先说明这个参数为何属于仓库策略，再提交配置。没有被记录的“能跑”命令可能只是把不一致转移到另一台机器。
5. 区分 npm 版本行为与损坏的锁文件
如果清单、锁文件与项目配置完全相同，但失败随 npm 版本改变，改写文件前先复现一个小版本矩阵。保存项目支持版本与相邻版本的完整错误。近期上游案例显示，特定解析路径可能出现 npm install 完成而 npm ci 仍拒绝结果的情况；这应作为升级上报证据，不能据此绕过一致性闸门。
真正损坏或过时的锁文件需要具体证据：解析失败、根元数据缺失、不可能的包映射引用、冲突标记或已知格式迁移。保留原文件，用预期工具链重建一次并检查全部差异。大量无关变化说明环境或策略仍未受控。
6. 从干净检出验证最小修复
完成最小且有证据的修正后，从干净检出开始。使用预期 Node/npm 版本，只加载已提交的项目配置，运行与 CI 相同的 npm ci。确认锁文件不再变化、正确 workspace 已安装、生命周期脚本符合预期，并让项目原有测试或构建通过。
把锁文件差异当作依赖代码审查：根版本范围、解析版本、integrity、peer 关系和移除项都应对应预期修改。若 npm ci 再次失败，保存新错误并回到分支台账。不要反复重建直到偶然通过；可复现性要求输入可解释、结果可稳定。
