React应用构建部署后刷新页面返回404/空白页如何修复

问题涉及依赖版本 #

• react: ^17.0.2
• react-redux: ^7.2.5
• react-scripts: 4.0.3
• @reach/router: ^1.3.4

问题表现 #

• 本地执行yarn build完成构建后预览、部署到Netlify平台时，按下F5刷新非根路径页面出现异常：本地预览提示404: The requested path could not be found，Netlify环境返回空白页且控制台存在资源加载报错
• 本地开发环境执行yarn start启动服务时问题无法复现
• 构建完成后通过页面内菜单点击跳转路由时，所有页面可正常运行

已尝试的无效操作 #

• 在package.json中添加配置项"homepage": "."
• 在项目根目录、build输出文件夹下手动添加内容为/* /index.html 200的_redirects配置文件
• 无法定位故障源于构建设置问题还是@reach/router路由配置问题

根因说明 #

该问题是单页应用（SPA）客户端路由的典型故障：所有路由逻辑由前端JS在浏览器端解析执行，服务端默认只会查找请求路径对应的实体文件，子路径不存在对应实体文件时就会返回404，导致前端资源无法加载。之前的修复方案存在配置位置错误、反向干扰两个问题，所以没有生效。

分步修复方案 #

1. 修正基础配置 #

首先打开项目根目录的package.json，删除你添加的"homepage": "."配置项。

该配置仅适用于项目部署在站点二级子目录的场景，根路径部署时添加该配置会将静态资源引用改为相对路径，子路由刷新时浏览器会从当前子路径下查找JS/CSS资源，直接导致资源加载404触发空白页。

2. 修复本地构建预览404问题 #

不要使用不带SPA fallback规则的普通静态文件服务预览build产物，本地预览构建结果时统一执行以下命令：

npx serve -s build

命令中-s参数会自动开启单页应用路由重写规则，所有找不到对应实体文件的请求都会被重定向到index.html，和线上部署的路由逻辑完全对齐。

3. 修复Netlify部署刷新404问题 #

你之前添加的_redirects文件位置错误，Netlify只会读取构建产物根目录下的配置文件，手动往build文件夹加文件会在下次构建时被覆盖，正确配置方式：

• 在项目的public文件夹下新建名为_redirects的文件，写入以下重写规则：

/*    /index.html   200

放在public目录下的文件会在执行yarn build时被原封不动拷贝到build输出目录的根路径，Netlify构建时可自动识别该规则，将所有请求重定向到index.html交给前端路由解析。

• 检查@reach/router配置，根路径部署时不需要给Router组件设置额外的basepath属性，路由路径直接写绝对路径即可，示例配置：

import { Router } from '@reach/router';
import Home from './pages/Home';
import MarketList from './pages/MarketList';
import ShopDetail from './pages/ShopDetail';

function App() {
  return (
    <Router>
      <Home path="/" />
      <MarketList path="/market" />
      <ShopDetail path="/shop/:id" />
    </Router>
  );
}

export default App;

• 提交代码触发Netlify重新部署即可，如果之前开启了Netlify的资产优化功能，可以去站点后台「Deploy settings」-「Asset optimization」确认没有开启强制路径重写规则，避免覆盖自定义的_redirects配置。

4. 验证标准 #

• 本地执行yarn build后用npx serve -s build预览，刷新任意子路由页面，不再出现404提示
• Netlify部署完成后，刷新任意非根路径页面，页面正常加载，控制台无静态资源加载报错
• 页面内菜单跳转、浏览器前进后退功能均正常

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