如何读取 NPM 依赖冲突错误？

Question

我试图npm install在一个相当过时的项目上运行并不断遇到 NPM 依赖错误。我之前在各种项目中遇到过数百个这样的错误，但我还没有找到关于如何阅读它们的良好指南。该线程最接近，但并没有真正描述一般情况，这些文档帮助我理解依赖项的底层结构，但并不能真正帮助我调试。

下面是我现在遇到的错误，从底部开始，我的解释是@aws-amplify/ui-react@1.2.26require react-dom@">=16.7.0"，但除此之外我不遵循。它看起来像react-dom@18.2.0require react@"^18.2.0"，但我不明白这是如何相关的，因为它react-dom甚至不是我的项目中的依赖项（至少没有明确声明）。

我认为缩进块意味着错误来自嵌套依赖项，但我真的不知道该怎么做。同样，上面的错误也与 相关@aws-amplify/ui-react@1.2.26，但我无法判断它是否导致下面的错误，反之亦然（或者也许它们完全无关？）。

我希望获得 1) 有关如何将 NPM 依赖项错误解读为可操作步骤的一般建议，以及 2) 有关如何修复此特定错误的建议。

另请注意，我已经尝试过npm update @aws-amplify/ui-react@1.2.26，但遇到了类似的错误。

npm ERR! code ERESOLVE
npm ERR! ERESOLVE unable to resolve dependency tree
npm ERR!
npm ERR! While resolving: myapp@0.0.1
npm ERR! Found: react@17.0.1
npm ERR! node_modules/react
npm ERR!   react@"17.0.1" from the root project
npm ERR!   peer react@">= 16.7.0" from @aws-amplify/ui-react@1.2.26
npm ERR!   node_modules/@aws-amplify/ui-react
npm ERR!     @aws-amplify/ui-react@"^1.2.26" from the root project
npm ERR!
npm ERR! Could not resolve dependency:
npm ERR! peer react@"^18.2.0" from react-dom@18.2.0
npm ERR! node_modules/react-dom
npm ERR!   peer react-dom@">= 16.7.0" from @aws-amplify/ui-react@1.2.26
npm ERR!   node_modules/@aws-amplify/ui-react
npm ERR!     @aws-amplify/ui-react@"^1.2.26" from the root project
npm ERR!
npm ERR! Fix the upstream dependency conflict, or retry
npm ERR! this command with --force, or --legacy-peer-deps
npm ERR! to accept an incorrect (and potentially broken) dependency resolution.

另外，如果有帮助的话，我的 NPM 依赖项的完整列表在这里：

  "dependencies": {
    "@aws-amplify/core": "^4.3.12",
    "@aws-amplify/ui-react": "^1.2.26",
    "@babel/plugin-proposal-decorators": "^7.16.7",
    "@flyskywhy/react-native-gcanvas": "^2.3.22",
    "@nozbe/watermelondb": "^0.24.0",
    "@react-native-async-storage/async-storage": "^1.17.6",
    "@react-native-community/checkbox": "^0.5.9",
    "@react-native-community/datetimepicker": "^4.0.1",
    "@react-native-community/masked-view": "^0.1.11",
    "@react-native-community/netinfo": "^6.2.1",
    "@react-navigation/bottom-tabs": "^5.11.15",
    "@react-navigation/native": "^5.9.8",
    "@react-navigation/stack": "^5.14.9",
    "@testing-library/react-hooks": "^5.1.3",
    "amazon-cognito-identity-js": "^5.2.4",
    "aws-amplify": "^4.3.12",
    "aws-amplify-react-native": "^5.0.5",
    "babel-preset-react-native": "^4.0.1",
    "crypto": "^1.0.1",
    "eslint-plugin-react": "^7.31.0",
    "eslint-plugin-react-native": "^4.0.0",
    "formik": "^2.2.9",
    "generate-username-from-email": "^1.0.2",
    "graphql": "^16.2.0",
    "lodash": "^4.17.21",
    "moment": "^2.29.1",
    "prop-types": "^15.8.1",
    "react": "17.0.1",
    "react-native": "0.64.1",
    "react-native-bootsplash": "^3.2.7",
    "react-native-canvas": "^0.1.38",
    "react-native-chart-kit": "^6.11.0",
    "react-native-confirmation-code-input": "^1.0.4",
    "react-native-device-info": "^10.5.1",
    "react-native-dotenv": "^3.3.1",
    "react-native-elements": "^3.4.2",
    "react-native-gesture-handler": "^1.10.3",
    "react-native-i18n": "^2.0.15",
    "react-native-idle-timer": "^2.1.7",
    "react-native-keychain": "^7.0.0",
    "react-native-reanimated": "2.2.4",
    "react-native-safe-area-context": "^3.3.2",
    "react-native-screens": "^3.4.0",
    "react-native-svg": "^12.1.1",
    "react-native-toast-notifications": "^3.2.3",
    "react-native-vector-icons": "^8.1.0",
    "react-native-video": "^5.2.0",
    "react-native-video-controls": "^2.8.1",
    "react-native-vimeo-iframe": "^1.0.4",
    "react-native-webview": "^11.21.1",
    "react-navigation": "^4.4.4",
    "unique-username-generator": "^1.0.1",
    "yup": "^0.32.11"
  },
  "devDependencies": {
    "@babel/core": "^7.16.7",
    "@babel/runtime": "^7.16.7",
    "@react-native-community/eslint-config": "^2.0.0",
    "@testing-library/react-native": "^7.2.0",
    "@types/react-native-vector-icons": "^6.4.10",
    "babel-jest": "^26.6.3",
    "eslint": "^8.22.0",
    "eslint-config-prettier": "^8.5.0",
    "eslint-config-standard": "^17.0.0",
    "eslint-plugin-import": "^2.26.0",
    "eslint-plugin-n": "^15.2.5",
    "eslint-plugin-prettier": "^4.2.1",
    "eslint-plugin-promise": "^6.0.1",
    "husky": "^6.0.0",
    "jest": "^26.6.3",
    "jetifier": "^1.6.8",
    "metro-react-native-babel-preset": "^0.64.0",
    "prettier": "^2.7.1",
    "react-test-renderer": "17.0.1"
  }

Answer 1

好吧，这个问题已经困扰我很长时间了，但我终于有了一个 TLDR 的方式来解释它：

总而言之：

1. 阅读错误消息中缩进最少的“While/Found/Could not”部分，以了解以下格式的冲突：“在尝试安装 Z 时，我发现我已经安装了模块 X 版本 1.0，但结果是，我无法满足我们使用模块 X 版本 2.0 的其他要求”。
2. 所有其他行都只是回答这个问题：“上面一行中的东西是从哪里来的？”

深入解释

让我们以您的错误消息为例：

npm ERR! code ERESOLVE
npm ERR! ERESOLVE unable to resolve dependency tree
npm ERR!
npm ERR! While resolving: myapp@0.0.1
npm ERR! Found: react@17.0.1
npm ERR! node_modules/react
npm ERR!   react@"17.0.1" from the root project
npm ERR!   peer react@">= 16.7.0" from @aws-amplify/ui-react@1.2.26
npm ERR!   node_modules/@aws-amplify/ui-react
npm ERR!     @aws-amplify/ui-react@"^1.2.26" from the root project
npm ERR!
npm ERR! Could not resolve dependency:
npm ERR! peer react@"^18.2.0" from react-dom@18.2.0
npm ERR! node_modules/react-dom
npm ERR!   peer react-dom@">= 16.7.0" from @aws-amplify/ui-react@1.2.26
npm ERR!   node_modules/@aws-amplify/ui-react
npm ERR!     @aws-amplify/ui-react@"^1.2.26" from the root project
npm ERR!
npm ERR! Fix the upstream dependency conflict, or retry
npm ERR! this command with --force, or --legacy-peer-deps
npm ERR! to accept an incorrect (and potentially broken) dependency resolution.

1. 首先阅读错误消息的“顶层”（最少缩进）部分，以获得对问题的高级理解。

   • 该消息遵循以下“While/Found/Could not”格式：在尝试安装 Z 时，我发现我已经安装了模块 X 版本 1.0，但结果是，我无法满足我们使用 X 版本 2.0 的其他要求”。

     • 在您的示例中，它是：“在尝试安装myapp@0.0.1时，我发现我已经安装了react@17.0.1，但结果是，我无法满足react@的要求”^18.2.0”。

        npm ERR! While resolving: myapp@0.0.1
        npm ERR! Found: react@17.0.1
        (...)
        npm ERR! Could not resolve dependency:
        npm ERR! peer react@"^18.2.0" from react-dom@18.2.0 resolution.
       

2. 所有其他行都只是回答这个问题：“上面一行中的东西是从哪里来的？”

   1. 在您的示例中，当您阅读冲突的前半部分时：

      npm ERR! Found: react@17.0.1
      

      1. 然后你问：“从哪里来react@17.0.1？” 然后看下一行：

         npm ERR! node_modules/react
         

      2. 答： 是在 中发现的node_modules/react。

      3. 问：好的，为什么会在那里？（看下一行）

         npm ERR!   react@"17.0.1" from the root project
         

      4. 答：因为根项目package.json说要安装该特定版本。（看下一行）

         npm ERR!   peer react@">= 16.7.0" from @aws-amplify/ui-react@1.2.26
         

      5. 答：此外，即使 root 不需要它package.json，我们也需要它react@">= 16.7.0"，因为我们安装的另一个包需要它：@aws-amplify/ui-react@1.2.26。

      6. 问：好的，从哪里来@aws-amplify/ui-react@1.2.26？（看下一行）

         npm ERR!   node_modules/@aws-amplify/ui-react
         

      7. 答： 是在 中发现的node_modules/@aws-amplify/ui-react。

      8. 问：好的，为什么会在那里？（看下一行）

         npm ERR!     @aws-amplify/ui-react@"^1.2.26" from the root project
         

      9. A：因为根项目package.json说要安装它。

      10. 冲突前半部分的总结：我们已经react@17.0.1安装了，因为 rootpackage.json说要安装它，而且我们至少需要安装>= 16.7.0它@aws-amplify/ui-react@"^1.2.26"，因为我们的 rootpackage.json说要安装它。

   2. 然后你看看冲突的后半部分：

      npm ERR! Could not resolve dependency:
      npm ERR! peer react@"^18.2.0" from react-dom@18.2.0
      

      1. 问：您为什么要尝试安装react@"^18.2.0"？

      2. 答：因为它是react-dom@18.2.0（正如您在第二行末尾看到的）所要求的。

      3. 问：好的，从哪里来react-dom@18.2.0？

         npm ERR! node_modules/react-dom
         

      4. 答：它已经安装在node_modules.

      5. 问：好的，为什么？

         npm ERR!   peer react-dom@">= 16.7.0" from @aws-amplify/ui-react@1.2.26
         

      6. 答：这是 要求的@aws-amplify/ui-react@1.2.26。它说我们需要一个版本react-dom >= 16.7.0，所以我猜它安装了最新版本。

      7. 问：从哪里来ui-react的？

         npm ERR!   node_modules/@aws-amplify/ui-react
         

      8. 答：它已经安装在node_modules.

      9. 问：为什么？

         npm ERR!     @aws-amplify/ui-react@"^1.2.26" from the root project
         

      10. A：根项目（package.json）说要安装它。

      11. 冲突后半部分的摘要：我们尝试安装react@"^18.2.0"，因为它是 所需的react-dom@18.2.0，而这又是 所需的软件包的最新版本@aws-amplify/ui-react@1.2.26，而这又是我们指定在根目录中安装的软件包package.json。

   3. 然后您可以总结冲突：我们的 rootpackage.json说要安装react@17.0.1，但随后又说要安装@aws-amplify/ui-react@1.2.26，这导致我们尝试安装react@"^18.2.0"。

   4. 然后您可以总结如何解决冲突：我们可以：

      1. 更新我们package.json以指定安装react@"^18.2.0"，或者
      2. 更新我们package.json以指定适用@aws-amplify/ui-react于react@17.0.1, 或
      3. 我们可以更新我们的版本以将 的版本和 的版本package.json更改为可以协同工作的版本，或者react@aws-amplify/ui-react
      4. package.json（最复杂的）我们可以尝试在我们的版本中找到并手动指定（react-dom从而>= 16.7.0满足冲突的后半部分）但仍然与react@17.0.1（冲突的前半部分）兼容。

Answer 2

Your specific error is caused by a version number mismatch. You are specifying a version of React for your project (17.0.1) in your package.json, and also (via @aws-amplify/ui-react@^1.2.26 which requires react-dom@>=16.7.0 but is currently using react-dom@18.2.0, which in turn requires react@18.2.0) loading an incompatible version as a peer dependency. The reason for this is that at some point a version of react-dom was required that is now too high of a version number, and you should be able to fix this by downgrading the version of react-dom to match your version of react (17.0.1), which will still satisfy the requirement react-dom@>=16.7.0.

In this case, where the already-resolved dependencies have formed a bit of a knot, you might also solve the problem by deleting your package-lock.json and rerunning npm install.

How to read NPM dependency errors?

The good news is, you're on the right lines with your own investigation. You should try getting the dependency graph for your project (npm list) and tracing through which modules require which submodules - this can have several layers of nesting. It's also useful to run npm list [module] to see what dependencies a given module has. This lets you see at a glance what existing dependencies might be affected when you add a new module. If you run into the same problem again, this might be enough to get you unstuck.

We can also take a closer look at some of the error messages you were getting.

npm ERR! Could not resolve dependency:
npm ERR! peer react@"^18.2.0" from react-dom@18.2.0
npm ERR! node_modules/react-dom
npm ERR!   peer react-dom@">= 16.7.0" from @aws-amplify/ui-react@1.2.26
npm ERR!   node_modules/@aws-amplify/ui-react
npm ERR!     @aws-amplify/ui-react@"^1.2.26" from the root project

The key things to note here are that the version of react-dom with the dependency is not using the same version number as where it's being required. This usually means that there are multiple places where it's a dependency, and NPM has tried to solve all conflicts already, but because NPM lists all places where a conflicting dependency is required, we know that's not the case here. I recommend reading up about the purpose of package-lock.json if you want to understand this in more depth.

@aws-amplify/ui-react is specified as coming 'from the root project', so we know it's a top-level dependency. Usually with a version mismatch, if you can trace all the dependencies through to the root dependency, you can look at potentially bumping one or more root dependencies to solve the problem that way.

Lastly, you can pin a specific version of a dependency and overwrite NPM's own version resolution mechanism. This is most useful when you want to use a patched version of a nested dependency without updating everything that depends on that package, e.g. to remove a vulnerability in the project. It's risky if you're not sure what you're doing, though. You can do this with the overrides section of the package.json.