cPanel部署React应用访问子路由报URL不存在404故障求助

这是React单页应用部署到Apache环境（cPanel默认Web服务为Apache）的典型路由适配问题：React Router在客户端侧处理路由逻辑，但Apache默认会优先匹配服务器上的实体文件/目录，访问/contact这类子路由时，服务器找不到public_html目录下对应的contact文件或文件夹，就会直接返回404，不会将请求转发给React应用的入口文件index.html交由前端路由匹配。你提到的ErrorDocument处理时报404，本质也是因为服务器没找到对应路由资源，且自定义错误规则指向的路径也不存在导致的。

1. 新增.htaccess重写规则 #

在public_html根目录创建.htaccess文件（注意文件名以英文点开头，是Apache的隐藏配置文件，需要先在cPanel文件管理器的设置中开启「显示隐藏文件」选项才能正常编辑/查看），写入以下配置：

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

配置作用：所有在服务器上找不到对应实体文件、目录的请求，全部重定向到根目录的index.html，交给React Router接管路由匹配逻辑。

2. 校验路由配置 #

确认项目中使用的React Router为BrowserRouter模式（如果用的是HashRouter不会出现这个问题，但url会带#号，体验较差），且package.json中配置的homepage字段值为你的主域名或者/即可，不要带多余的子路径。

3. 排查ErrorDocument 404异常 #

如果写入配置后仍然出现ErrorDocument相关报错，按以下顺序排查：

• 确认.htaccess文件权限为644，权限过高会导致Apache拒绝读取该配置文件
• 确认Apache已开启mod_rewrite模块，cPanel环境默认开启该模块，如果未开启可以在cPanel面板的Apache模块管理中勾选启用，或联系主机服务商协助开启
• 删除cPanel面板「自定义错误页」中配置的404规则，避免自定义错误路径不存在导致的二次404

4. 资源路径校验 #

确认你移动文件后，public_html根目录下直接存在index.html、static文件夹等build产物，不要把build文件夹本身留在public_html下导致资源路径错位。配置完成后清除浏览器缓存再测试子路由访问即可。

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