React 18升级报Can't resolve react-helmet-async的迁移方案

你遇到的模块找不到报错，本质是旧版react-helmet-async不再作为React 18相关包的子依赖被间接安装，且旧版本身不兼容React 18并发特性、流式SSR能力，不符合长期技术选型要求。

针对你无嵌套Head用法、后续计划接入SSR的场景，推荐使用@unhead/react作为替代方案：它原生兼容React 18所有新特性，支持客户端渲染、传统SSR、流式SSR，API和你之前用的react-helmet-async高度一致，迁移成本极低。

迁移步骤 #

• 安装依赖
  先执行命令移除旧的未声明依赖，安装新的head管理包：

  npm uninstall react-helmet-async
  npm install @unhead/react
  

• 替换全局Provider
  把根组件里的HelmetProvider替换为UnheadProvider，位置和之前一致，放在路由组件外层即可。

  注意：你贴的示例代码有两个笔误：函数组件没有返回JSX、React Router v6要求所有Route必须被Routes包裹，且页面元素要传给Route的element属性，修正后的完整代码如下：

  import { Routes, Route, BrowserRouter as Router } from 'react-router-dom'
  // 替换原有helmet的导入
  import { UnheadProvider, Head } from '@unhead/react'
  
  const pages = [/* 原有页面配置数组，无需修改 */]
  
  const App = () => {
    return (
      <Router basename={process.env.PUBLIC_URL}>
        <UnheadProvider>
          <Routes>
            {pages.map(
              ({ pageId, title, description, jsx, path }) => {
                return(
                  <Route 
                    path={path} 
                    key={pageId}
                    element={
                      <>
                        {/* 替换Helmet为Head组件，内部标签写法完全不变 */}
                        <Head>
                          <html lang='en' />
                          <title>{title}</title>
                          <meta name='description' content={description} />
                        </Head>
                        <AppProvider>{jsx}</AppProvider>
                      </>
                    }
                  />
                )
              }
            )}
          </Routes>
        </UnheadProvider>
      </Router>
    )
  }
  

  所有分散在业务组件里的Helmet用法，都可以按同样规则替换为Head组件，内部的title、meta、link等标签写法完全不需要修改。

后续SSR接入适配 #

等你后续接入SSR时，不需要修改任何业务组件里的Head写法，只需要在服务端渲染逻辑中做两处调整即可，天然支持多请求隔离、流式渲染：

// 服务端渲染入口文件
import { createHead } from '@unhead/react/server'
import { renderToString } from 'react-dom/server'

app.get('*', (req, res) => {
  // 每个请求单独创建head实例，避免不同用户的head内容串扰
  const head = createHead()
  // 渲染组件时把head实例传入Provider
  const appHtml = renderToString(
    <UnheadProvider head={head}>
      {/* 你的服务端App根组件，和客户端共用业务逻辑 */}
    </UnheadProvider>
  )
  // 取出收集完成的head标签字符串
  const headTags = head.renderToString()
  // 将headTags插入HTML模板的<head>标签内返回即可
  res.send(`
    <!DOCTYPE html>
    <html>
      <head>
        <meta charset="UTF-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
        ${headTags}
      </head>
      <body>
        <div id="root">${appHtml}</div>
        <script src="/bundle.js"></script>
      </body>
    </html>
  `)
})

临时兼容方案 #

如果你暂时不想做迁移，直接执行npm install react-helmet-async把依赖显式写到package.json里也能解决当前报错，最新版的react-helmet-async已经兼容React 18客户端渲染，但它对React 18流式SSR、React Server Components的支持不完善，后续接入SSR时还是需要做迁移。

内容的提问来源于stack exchange，提问作者Dana Scheider