在 macOS 上，首先确认 npm 报告的是 Git 合并冲突、package.json 与 package-lock.json 之间的不匹配，还是 peer dependency 解析错误。在更改任何内容之前，先在终端中检查项目文件、Git 状态和 npm 版本。如果仅需协调 lockfile，npm 的 --package-lock-only 选项可以在不将包重新安装到 node_modules 的情况下对其进行更新。

从项目文件夹开始并保留当前状态

打开终端，切换到项目目录，并确认你位于预期的项目根目录中。在访达（Finder）中，你可以找到该文件夹，然后使用终端的 cd 命令；如果路径包含空格，请给路径加上引号，例如 cd "$HOME/Projects/My App"。运行：

pwd
git status --short
node --version
npm --version

git status --short 会显示任一清单文件是否存在未提交的编辑。如果有需要保留的更改，请在继续之前保存或提交它们；在仍在确定归属哪些依赖项更改时，不要覆盖文件。记录 Node.js 和 npm 的版本，以便将它们与项目中记录的配置或持续集成配置进行对比。npm lockfile 的格式在不同的 npm 主版本间发生过变化，因此格式差异可以解释意外的大幅变动，而不能证明依赖项本身已损坏。npm 的 package-lock 文档

确定你遇到的是哪种冲突

如果 package-lock.json 包含 Git 标记，如 <<<<<<<、======= 或 >>>>>>>，则这是版本控制合并冲突。检查所有受影响的部分并比较两个分支的更改。先解决 package.json 中的依赖项声明：npm 较旧的 lockfile 冲突指南明确指出，在重新生成 lockfile 之前，应手动解决清单冲突。不要出于习惯简单地保留 lockfile 的某一侧；每个分支都可能添加或更改了依赖项。npm 的 package-lock 冲突指南

如果没有 Git 标记，请将 package.json 中的依赖项名称和范围与 lockfile 进行比较。package.json 指定了可接受的范围，而 lockfile 记录了解析后的依赖树。当前的 npm 文档指出，正常的 npm install 会在锁定的版本满足清单范围时使用它们，并在不满足时更新锁定内容。npm install 如何使用 lockfile

如果命令因 peer dependency 消息而失败，请重点关注该错误中指出的包及其对 peer 的要求。这可能是声明的包范围之间存在的有效不兼容性，而非安装损坏。不要将 --force 或 --legacy-peer-deps 用作诊断捷径：改变依赖项解析行为可能会生成与项目预期设置不同的依赖树。

在要求 npm 协调之前检查更改

查看项目的历史记录和当前的 diff：

git diff -- package.json package-lock.json
git log -5 --oneline -- package.json package-lock.json

查找更改了依赖项声明、lockfile 版本或 npm 配置的提交或分支。还要检查项目是否包含 .npmrc；npm 文档说明诸如 legacy-peer-deps 或 install-links 等塑形树结构的选项会影响 lockfile 与后续的全新安装（clean install）是否一致。请使用仓库中已采用的相同项目特定设置，而不是随意添加新标志。npm ci 文档

lockfileVersion 值有助于识别文件格式，但避免将其本身作为诊断依据。npm 文档中记载了格式版本 1、2 和 3，并指出较新的 npm 版本可以更新较旧的 lockfile。版本的更改可能反映了 npm 的兼容性行为；在接受大规模重写之前，请检查实际的依赖项差异。Lockfile 格式和较旧的文件

在不重新安装依赖项的情况下协调 lockfile

在解决所有冲突标记并确保 package.json 正确后，让 npm 仅更新 lockfile：

npm install --package-lock-only

npm 文档说明该选项用于更新 package-lock.json，而无需检查 node_modules 或下载依赖项。这是一个针对性的协调步骤；它不保证生成的依赖集就是你预期的，因此之后需要检查 diff。npm install 选项

git diff --check
git diff -- package.json package-lock.json
git status --short

git diff --check 有助于捕获空格错误，而 diff 本身会显示 npm 更改了什么。确认清单没有混入意外的编辑，检查意外的版本更改或广泛的 lockfile 重写，并确认冲突标记已消失。如果建议的更改不合理，请从已保存的状态或版本控制中还原文件并重新排查原因，而不是删除 node_modules 或重新生成所有内容。

了解何时适合进行全新安装

仅在清单和 lockfile 已按预期对齐且你想复现锁定的依赖树之后，才使用 npm ci。它需要 lockfile，在出现不匹配时会直接报错而不是更新，并且在安装前会删除现有的 node_modules 目录。这使得它在确认已解决的状态时很有用，但它并不是一个用于无害检查的命令。npm ci 行为

如果 npm install --package-lock-only 无法解决冲突，请记录其准确的错误信息，查看提及的包范围和项目 npm 设置，并与生成该 lockfile 的分支或 CI 环境进行对比。决定性的问题是项目应该保留哪些依赖项声明；清理安装并不能替你回答这个问题。一旦该决定反映在 package.json 中，请仅重新生成 lockfile，检查建议的更改，然后再选择是否有必要进行全新安装。

来源