现有Rails+React应用迁移React on Rails SSR的组件报错与适配问题

模块解析报错修复 #

你遇到的Field 'browser' doesn't contain a valid alias configuration属于webpack服务端打包时的模块查找失败问题，和组件本身逻辑无关，按以下顺序排查即可：

• 先核对报错提示里的文件路径是否真实存在：报错指向./app/frontend/folder/my_component_server.js，先去对应目录确认文件是否存在，重点检查文件名大小写、文件夹层级是否和配置里写的完全一致，绝大多数这类问题都是直接复制客户端组件路径到服务端配置，实际没创建对应服务端入口文件、或者文件放错了目录。
• 核对服务端webpack配置的解析规则：不要只给客户端打包配置加resolve.extensions规则，服务端打包配置必须同样配置.js、.jsx、.ts、.tsx（使用TS的场景）这类后缀，否则webpack处理无后缀的模块引用时会直接抛错。
• 检查package.json的browser字段配置：SSR打包运行在Node环境，不需要走浏览器端的模块别名规则，如果browser字段里配置了错误的模块别名、或者把Node端依赖指向了不存在的浏览器polyfill，就会触发这个报错。临时排查可以给服务端webpack配置加一行resolve.aliasFields = []，跳过browser字段的别名解析，确认问题根因。
• 确认服务端打包入口包含所有SSR组件：不要只在客户端入口注册React on Rails组件，服务端打包的入口文件必须同样引入并注册所有需要SSR的组件，否则服务端bundle里根本没有对应组件代码，webpack查找时就会报路径错误。

HAML模板适配方案 #

React on Rails没有强制要求使用ERB模板，HAML可以直接使用框架提供的视图helper，不需要把现有模板全改成ERB。
你原来的客户端挂载写法是：

%div#root <-- here is attaching react app
  = stylesheet_pack_tag "fonts", "styles"
  = javascript_pack_tag "my_react_app_entry_point"

适配SSR只需要做少量调整，不需要手动写根节点和客户端挂载逻辑：

• 保留原有的样式、JS包引入标签即可，注意JS包名要和webpack配置里的entry名保持一致。
• 去掉手动写的%div#root节点，直接调用react_component helper渲染目标组件，传入prerender: true参数就会自动开启服务端渲染，helper会自动生成对应DOM节点、注入初始化数据、在客户端加载完成后自动执行hydrate，不需要你手动写ReactDOM.render相关代码。

基础适配示例：

= stylesheet_pack_tag "fonts", "styles"
= javascript_pack_tag "my_react_app_entry_point"

= react_component("YourBusinessComponent", props: { 初始化组件需要的props数据 }, prerender: true)

如果你需要保留原有的id="root"根节点标识，只需要给helper加id参数即可，同时可以把根组件直接挂载在这个节点上：

= react_component("App", props: @server_side_props, prerender: true, id: "root")

注意：开启SSR后，组件里直接访问window、document这类浏览器专属API的代码，必须放到useEffect或者componentDidMount这类客户端执行的生命周期里，服务端渲染阶段不会执行这部分逻辑，就不会出现Node环境下找不到浏览器对象的报错。

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