React应用部署后刷新子页面空白问题求助

问题本质 #

SPA使用BrowserRouter时，应用内跳转由前端路由接管，但刷新页面时浏览器会直接向服务器请求对应路径的物理文件，服务器找不到对应文件就返回404。核心解决思路是配置服务器将所有路由请求转发到index.html，交由前端路由处理。

针对不同托管环境的解决方案 #

1. AWS Amplify 配置 #

Amplify默认不会自动处理SPA路由，需手动添加重写规则：

• 方法一：项目根目录创建amplify.yml

  version: 1
  frontend:
    phases:
      build:
        commands:
          - npm run build
    artifacts:
      baseDirectory: build
      files:
        - '**/*'
    cache:
      paths:
        - node_modules/**/*
    rewrites:
      - source: '/<*>'
        target: '/index.html'
        status: 200
  

• 方法二：Amplify控制台配置
  进入Amplify控制台对应应用 → Rewrites and redirects → 添加规则：
  • 源地址：</^[^.]+$|\.(?!(css|gif|ico|jpg|js|png|txt|svg|woff|ttf|map|json)$)([^.]+$)/>
  • 目标地址：/index.html
  • 类型：200 (Rewrite)

2. cPanel 托管配置 #

静态文件托管（无Node.js服务器）

在build文件夹下创建.htaccess文件，内容如下：

<IfModule mod_rewrite.c>
  RewriteEngine On
  RewriteBase /
  RewriteRule ^index\.html$ - [L]
  RewriteCond %{REQUEST_FILENAME} !-f
  RewriteCond %{REQUEST_FILENAME} !-d
  RewriteRule . /index.html [L]
</IfModule>

该配置会让Apache服务器将所有非文件/目录的请求转发到index.html。

Node.js服务器托管

如果使用cPanel的Node.js应用管理器，确保server.js完整配置：

const express = require('express');
const path = require('path');
const app = express();

// 托管build文件夹下的静态资源
app.use(express.static(path.join(__dirname, 'build')));

// 所有路由请求转发到index.html
app.get('*', (req, res) => {
  res.sendFile(path.join(__dirname, 'build', 'index.html'));
});

const port = process.env.PORT || 3000;
app.listen(port, () => {
  console.log(`Server running on port ${port}`);
});

在cPanel中设置启动命令为node server.js，并确保应用根目录指向包含server.js和build文件夹的路径。

3. 前端配置修正 #

• package.json的homepage设置：
  • 根域名部署："homepage": "/"
  • 子路径部署（如https://example.com/myapp）："homepage": "/myapp/"
    避免使用"./"，否则会导致静态资源路径解析错误。
• 路由嵌套检查：如果HomeUS或HomeGB内有子路由，需在组件内使用<Outlet />（来自react-router-dom）渲染子路由内容，否则嵌套路由无法正常显示。

验证步骤 #

1. 修改配置后重新执行npm run build生成生产包
2. 重新部署到对应托管环境
3. 刷新子页面（如/us），检查是否正常渲染
4. 查看浏览器控制台，确认静态资源（css、js）是否加载正常

关于HashRouter #

HashRouter通过URL中的#隔离路由，服务器只会解析#前的根路径，因此不会出现404，但会导致URL不美观，且对SEO不友好，官方不推荐使用，优先通过服务器配置解决问题。

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