React18 控制台报错 ReactDOM.render is no longer supported：用 createRoot 迁移的完整配置与验证

1. React18 升级后控制台报错 ReactDOM.render is no longer supported 到底在说什么你从 React17 升到 React18npm install react18 react-dom18装完npm start一跑页面看着没啥问题但浏览器控制台里躺着一行黄字Warning: ReactDOM.render is no longer supported in React 18. Use createRoot instead. Until you switch to the new API, your app will behave as if its running React 17.这句话拆开看有三层意思。第一层是事实陈述ReactDOM.render这个 API 在 React18 里被标记为不再支持。第二层是行动建议改用createRoot。第三层最关键——「your app will behave as if its running React 17」意思是你的应用现在跑在 React17 的兼容模式下React18 的并发特性Concurrent Features一个都没生效。很多人看到「Warning」就觉得无所谓反正页面能渲染。但这里有个坑React18 的核心卖点——自动批处理Automatic Batching、useTransition、useDeferredValue、Suspense 的并发能力——全部依赖新的 root API。你继续用ReactDOM.render等于花 18 的钱用 17 的服务。而且这个警告会在每次热更新时重复打印控制台越滚越长真正需要排查的错误反而被淹没。这个报错适合谁看三类人最需要一是刚从 React17 升到 18、还没动入口文件的开发者二是用 Create React App 或 Vite 建了新项目、但入口代码是从旧模板复制过来的三是接手了老项目、看到控制台黄字想彻底清掉的人。我试过在一个中型后台项目里拖了两个月没改后来想用useTransition优化搜索框发现完全不生效回头才发现根因就是入口没迁移。迁移本身不复杂核心就是把ReactDOM.render(App /, container)换成createRoot(container).render(App /)。但「不复杂」不等于「没细节」——react-dom/client的导入路径、StrictMode 的包裹方式、TypeScript 的类型报错、SSR 场景的hydrateRoot这些地方各有各的坑。下面按可跟做的顺序拆开讲。2. 迁移前先确认版本与入口文件TaoToken 辅助排查依赖冲突动手改代码之前先确认两件事React 版本真的是 18以及入口文件到底在哪。很多「改了没效果」的情况是因为改错了文件或者项目里装了两个版本的 react-dom。先看版本。在项目根目录执行npm ls react react-dom正常输出应该是这样my-app0.1.0 /path/to/my-app ├── react18.2.0 └── react-dom18.2.0如果看到react-dom17.x和react-dom18.x同时出现说明有依赖锁死了旧版本这时候改入口也没用得先解决依赖树。常见的是某个 UI 库的 peerDependencies 还写着^17可以用npm ls react-dom定位是哪个包带进来的。入口文件的命名因脚手架而异。Create React App 是src/index.jsVite 的 React 模板是src/main.jsxNext.js 的 Pages Router 是pages/_app.jsApp Router 则不需要手动调createRoot。先打开文件找到ReactDOM.render那一行确认它就是你控制台警告的来源。这一步如果遇到依赖解析报错、或者不确定某个包是否兼容 React18可以借助模型对话快速判断。把npm ls的输出和报错信息贴进去让它帮你分析依赖链https://taotoken.net/api对应的模型对话入口在https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentreact18_migration我一般会把package.json里的 dependencies 整段贴过去问「哪些包可能锁死 react-dom 17」比一个个翻 node_modules 快得多。确认版本干净之后再进入下一步改代码。3. 可复制的 createRoot 配置入口文件改造与 settings 片段这是整篇最核心的部分。React18 的迁移分两种场景纯客户端渲染CSR和 服务端渲染SSR。绝大多数从 CRA/Vite 升级过来的项目属于前者先讲这个。3.1 客户端渲染index.js / main.jsx 改造改造前的典型代码React17 写法import React from react; import ReactDOM from react-dom; import App from ./App; ReactDOM.render( React.StrictMode App / /React.StrictMode, document.getElementById(root) );改造后React18 写法import React from react; import { createRoot } from react-dom/client; import App from ./App; const container document.getElementById(root); const root createRoot(container); root.render( React.StrictMode App / /React.StrictMode );三个关键变化要盯住。第一导入路径从react-dom变成react-dom/client这是最容易写错的地方写成import { createRoot } from react-dom会直接报createRoot is not a function。第二createRoot接收的是 DOM 容器返回一个 root 对象render挂在 root 上不再是ReactDOM.render(元素, 容器)的两参数形式。第三React.StrictMode依然可以包但注意 React18 的 StrictMode 在开发模式下会故意双调用 effect这是预期行为不是 bug。如果你用 TypeScriptdocument.getElementById(root)的返回类型是HTMLElement | nullcreateRoot不接受 null。稳妥写法是加个断言或判空import React from react; import { createRoot } from react-dom/client; import App from ./App; const container document.getElementById(root) as HTMLElement; const root createRoot(container); root.render( React.StrictMode App / /React.StrictMode );3.2 SSR 场景hydrateRoot 替换 hydrate如果你的项目用了 Next.js 自定义 server、或者 Remix、或者手写 SSR客户端注水要用hydrateRootimport { hydrateRoot } from react-dom/client; import App from ./App; hydrateRoot( document.getElementById(root), App / );注意hydrateRoot的第二个参数直接是元素不像createRoot那样先建 root 再 render。这是两个 API 签名上的差异别混用。3.3 配置文件片段确保构建工具识别新入口Vite 项目一般不用改配置但如果你在vite.config.js里手动指定过optimizeDeps确认react-dom/client在预构建范围内// vite.config.js import { defineConfig } from vite; import react from vitejs/plugin-react; export default defineConfig({ plugins: [react()], optimizeDeps: { include: [react, react-dom, react-dom/client] } });CRA 项目不需要动webpack.config.js本身也被 eject 才可见改完入口直接重启即可。如果你用的是 Next.js 的 Pages Routerpages/_app.js不需要createRootNext.js 内部已经处理只有自定义_document.js或手写客户端入口时才需要。改完保存先别急着看控制台往下走验证流程。4. 验证迁移是否成功控制台无报错与页面渲染结果双确认改完代码npm start重启开发服务器。验证分两个层面缺一不可。第一层控制台。打开浏览器 DevTools 的 Console 面板刷新页面。如果迁移成功那行ReactDOM.render is no longer supported的黄字应该彻底消失。注意要硬刷新CtrlShiftR因为热更新有时会保留旧的模块缓存。如果黄字还在先确认你改的文件是不是真正被加载的入口——可以在createRoot那行打个console.log(createRoot called)看它有没有打印。第二层页面渲染。光看控制台干净不够得确认 DOM 真的挂载了。在 Console 里执行document.getElementById(root).children.length正常应该返回大于 0 的数字说明 React 把组件树渲染进去了。如果返回 0页面白屏那多半是createRoot的容器选错了或者render没被调用。再进一步验证 React18 的并发特性是否真的生效。写一个最小测试组件import { useState, useTransition } from react; function SearchBox() { const [input, setInput] useState(); const [list, setList] useState([]); const [isPending, startTransition] useTransition(); const handleChange (e) { setInput(e.target.value); startTransition(() { const items []; for (let i 0; i 20000; i) { items.push(e.target.value i); } setList(items); }); }; return ( div input value{input} onChange{handleChange} / {isPending span加载中.../span} ul{list.slice(0, 10).map((item, i) li key{i}{item}/li)}/ul /div ); }把SearchBox挂到App里在输入框快速打字。如果输入框不卡顿、且「加载中...」会短暂出现说明useTransition生效了也就证明你的应用真的跑在 React18 模式下。如果输入框明显卡顿、isPending永远是 false那说明还在 React17 兼容模式回去检查入口。实测下来这个验证方法比单纯看控制台可靠得多因为它直接测的是运行时行为而不是警告文本。5. 迁移常见报错排查401、local proxy failed、reading choices、OAuth 对照迁移过程中会撞上几类典型报错这里按真实错误信息对照排查。报错一createRoot is not a function或createRoot is not exported from react-dom原因几乎都是导入路径写错。正确是import { createRoot } from react-dom/client不是react-dom。检查你的编辑器自动补全有没有帮你补成旧路径。报错二Target container is not a DOM elementcreateRoot拿到的容器是 null。常见于脚本在 DOM 加载前执行或者index.html里根本没有idroot的元素。确认public/index.htmlCRA或根目录index.htmlVite里有div idroot/div。报错三401 Unauthorized或local proxy failed这类报错通常出现在你调用后端接口或 AI 服务时和 React 迁移本身无关但容易在迁移期间被误判。如果你在项目里集成了模型调用检查 API Key 是否配置正确。TaoToken 的 API Key 在控制台生成https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentreact18_migration生成后写入.env文件注意 Vite 需要VITE_前缀CRA 需要REACT_APP_前缀否则前端读不到。local proxy failed一般是本地开发代理配置问题检查vite.config.js的server.proxy或 CRA 的setupProxy.js。报错四Cannot read properties of undefined (reading choices)这是调用模型接口时响应结构解析错误通常是返回体不是预期的 OpenAI 兼容格式。确认请求的 Base URL 是https://taotoken.net/api且 model 参数用的是平台支持的模型 ID。如果你在 React 组件里直接 fetch记得处理流式响应的分块解析。报错五OAuth 相关报错如果你用 Claude Code 或 Codex 这类工具做辅助开发遇到 OAuth 认证失败检查三件套是否齐全Base URL、API Key、Model ID。以 Claude Code 为例配置文件里需要同时写对这三项缺一个都会认证失败。接入文档在https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentreact18_migration排查顺序建议先看报错文本属于哪一类再对照上面的原因。不要一上来就重装 node_modules90% 的迁移报错都是路径或容器选择问题。6. 长期编码与 Agent 场景把迁移后的项目接上 Coding Plan迁移完成、控制台干净之后如果你打算在这个项目上长期做开发或者想用 Agent 辅助写代码可以考虑把模型调用接进工作流。TaoToken 的 Coding Plan 适合这种场景https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentreact18_migration接入时记住三件套的写法。以 Cline 或 CC Switch 这类工具为例配置片段大致是{ baseUrl: https://taotoken.net/api, apiKey: sk-你的密钥, model: claude-sonnet-4-20250514 }Base URL 固定用https://taotoken.net/api不要加 UTM 参数到 API 地址上。API Key 从控制台的 API Keys 页面生成https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentreact18_migrationModel ID 要和你实际使用的模型对上写错了会报model not found。如果你用 Codex配置写在~/.codex/auth.json里字段名和上面略有差异以接入文档为准。回到 React18 迁移本身最后提醒一个容易忽略的点迁移完成后检查一下项目里有没有其他地方还在用ReactDOM.render比如测试文件、Storybook 的 preview、或者某些动态挂载的弹窗组件。全局搜一下grep -rn ReactDOM.render src/搜出来一处改一处直到结果为空。这样控制台才算真正干净React18 的并发能力也才能完整生效。