为什么ReactDOM在Symfony5的Twig模板中无法正常渲染内容

问题根因及解决方案 #

先打开浏览器开发者工具的Console面板，查看具体报错信息可以快速定位问题，以下是最常见的几种场景：

• React18 语法不兼容
  如果你的项目安装的是React 18+版本，原来的ReactDOM.render API已经被废弃，不会生效，需要替换为React18的新渲染语法。
  解决：把assets/js/app.js里的渲染部分替换为以下代码：

import { createRoot } from 'react-dom/client';
const root = createRoot(document.getElementById('root'));
root.render(<Router><App /></Router>);

• BrowserRouter 路径配置错误
  你的项目访问路径不是站点根目录，而是/symfony1/public/shop，BrowserRouter默认匹配根路径，路由不匹配会导致组件不渲染。
  解决：给Router添加basename属性，指定你的项目子路径：

<Router basename="/symfony1/public/shop">
  <App />
</Router>

如果后续要部署到不同路径，可以用Symfony的Twig变量动态传basename，避免硬编码。

• Webpack Encore 未开启React预设
  如果你的webpack.config.js里没有添加React支持配置，JSX语法不会被正确编译，导致代码执行失败。
  解决：在webpack.config.js里添加.enableReactPreset()配置，示例：

Encore
  // ... 其他原有配置
  .addEntry('app', './assets/js/app.js')
  .enableReactPreset() // 新增这行
;

修改配置后重新执行yarn encore dev或者npm run dev编译资源即可。

• JS 加载顺序早于DOM渲染
  如果你的Twig模板里的javascripts块是放在<head>标签内，执行JS的时候id="root"的div还没渲染，会导致找不到节点渲染失败。
  解决：要么把javascripts块移动到</body>标签之前，要么给script标签全局添加defer属性，可在encore配置中开启：

Encore
  // ...其他原有配置
  .configureScriptTagAttributes((attributes) => {
    attributes.defer = true;
    return attributes;
  })

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