Next.js 15 + React 19

简要说明

如果你正在使用 npm，可以通过标志位安装 shadcn/ui 依赖项。shadcn CLI 在运行会提示你选择一个标志位。使用 pnpm、bun 或 yarn 则无需标志位。

请参阅 升级状态 以了解各包对 React 19 的支持情况。

发生了什么？

React 19 现已进入 候选发布版本 (rc)，并且在最新的 Next.js 15 版本中 已得到测试和支持。

为了支持 React 19，包维护者需要测试并更新他们的包，以将 React 19 包含在对等依赖（peer dependency）中。这一工作 已经 在 进行中。

Copy"peerDependencies": {
-  "react": "^16.8 || ^17.0 || ^18.0",
+  "react": "^16.8 || ^17.0 || ^18.0 || ^19.0",
-  "react-dom": "^16.8 || ^17.0 || ^18.0"
+  "react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0"
},

在此期间，如果你安装的包 没有 将 React 19 列为对等依赖，你将看到类似以下的错误信息

Copynpm error code ERESOLVE
npm error ERESOLVE unable to resolve dependency tree
npm error
npm error While resolving: my-app@0.1.0
npm error Found: react@19.0.0-rc-69d4b800-20241021
npm error node_modules/react
npm error   react@"19.0.0-rc-69d4b800-20241021" from the root project

如何解决

方案 1: 使用 --force 或 --legacy-peer-deps

你可以使用 --force 或 --legacy-peer-deps 标志位强制安装包。

Copynpm i <package> --force
 
npm i <package> --legacy-peer-deps

这将安装该包并忽略对等依赖警告。

方案 2: 使用 React 18

你可以将 react 和 react-dom 降级到 18 版本，该版本与你正在安装的包兼容，并在依赖项更新后再升级。

Copynpm i react@18 react-dom@18

无论你选择哪种方案，请务必彻底测试你的应用，确保没有回归问题。

在 Next.js 15 上使用 shadcn/ui

使用 pnpm、bun 或 yarn

按照 安装指南 中的说明安装 shadcn/ui。无需使用任何标志位。

使用 npm

当你运行 npx shadcn@latest init -d 时，系统会提示你选择一个选项来解决对等依赖问题。

CopyIt looks like you are using React 19.
Some packages may fail to install due to peer dependency issues (see https://ui.shadcn.org.cn/react-19).
 
? How would you like to proceed? › - Use arrow-keys. Return to submit.
❯   Use --force
    Use --legacy-peer-deps

然后，你可以使用你选择的标志位运行该命令。

添加组件

添加组件的过程与上述相同。请选择一个标志位来解决对等依赖问题。

安装新依赖后，请务必始终测试你的应用。

升级状态

为了让你方便跟踪升级进度，我在下方创建了一个表格，列出了 shadcn/ui 依赖项对 React 19 的支持状态。

• ✅ - 在 npm、pnpm 和 bun 下可与 React 19 一起使用。
• 🚧 - 在 pnpm 和 bun 下可与 React 19 一起使用。npm 需要标志位。PR 正在进行中。

如果你有任何疑问，请在 GitHub 上 开启一个 issue。

Recharts

要在 React 19 中使用 recharts，你需要覆盖 react-is 依赖项。

Copy"overrides": {
  "react-is": "^19.0.0-rc-69d4b800-20241021"
}