React项目部署至Render后路由失效：非根路径页面空白

1. 确认Render部署配置正确性 #

• 检查Publish Directory设置：必须设为build（React默认构建输出目录），填错路径会直接导致静态资源加载失败。
• 核对构建命令：确保使用npm run build（或yarn build）；如果项目需要开发依赖才能完成构建，需修改构建命令为npm install --include=dev && npm run build，避免缺失babel等构建依赖导致产物异常。

2. 验证重写规则是否正确生效 #

Render的重写规则需确保所有非静态资源请求都指向index.html，两种配置方式：

• 项目根目录创建render.yaml文件，添加：

  routes:
    - type: rewrite
      source: /*
      destination: /index.html
  

• 或在Render控制台项目设置的Rewrites and Redirects中添加规则：

  /*    /index.html   200
  

  注意：规则中的/*必须是全匹配，不要遗漏星号，且优先级要高于其他自定义规则。

3. 检查HashRouter的配置细节 #

如果改用HashRouter仍无效，需确认：

• 已将BrowserRouter完全替换为react-router-dom导出的HashRouter，不要混用或自定义组件。
• 组件内的Link直接写to="/home"即可，HashRouter会自动在URL中添加#，访问路径应为https://your-app.onrender.com/#/home。
• 核对react-router-dom版本：v6版本需用Routes包裹Route，且通过element属性指定组件，示例：

  import { HashRouter, Routes, Route, Link } from 'react-router-dom';
  
  function App() {
    return (
      <HashRouter>
        <nav>
          <Link to="/">Page</Link>
          <Link to="/home">Home</Link>
          <Link to="/test">Test</Link>
        </nav>
        <Routes>
          <Route path="/" element={<Page />} />
          <Route path="/home" element={<Home />} />
          <Route path="/test" element={<Test />} />
        </Routes>
      </HashRouter>
    );
  }
  

  若仍使用v5的Switch和component属性，会导致路由无法匹配。

4. 检查构建产物的资源路径 #

打开build后的index.html文件，确认所有静态资源（JS、CSS、图片）的引用路径为相对路径（以./开头），比如：

<script src="./static/js/main.abc123.js"></script>
<link href="./static/css/main.def456.css" rel="stylesheet">

如果是绝对路径（以/开头），需确保package.json中的"homepage": "."配置正确；若仍有问题，可尝试在webpack.config.js（或craco.config.js，若使用craco）中手动设置publicPath: "./"。

5. 排查路由大小写与组件导出问题 #

• Render服务器区分URL路径大小写，确保路由路径（如/home）与Link的to属性、Route的path属性完全一致，避免大小写差异导致的404。
• 检查Page、Home、Test组件是否正确导出（默认导出或命名导出），确保在路由中正确引入。

6. 查看Render部署日志 #

进入Render控制台的项目Logs页面，查看构建和部署过程中的报错信息：

• 若构建阶段出现Module not found，需确认依赖是否正确安装，或是否缺失必要的开发依赖。
• 若部署阶段出现404错误，说明请求未被正确重写到index.html，需重新检查重写规则。

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