React自定义404 NotFound页面在生产环境无法正常显示

问题根源 #

开发环境的React Dev Server默认会把所有路由请求转到index.html，交给React Router处理路由匹配；但生产环境的静态服务器（比如Nginx、Apache）会优先找对应路径的物理文件，找不到就直接返回服务器自带的404页面，根本没让React Router的通配符路由生效。

解决方法 #

根据你用的生产服务器，添加对应配置，让所有非静态资源的请求都指向index.html：

1. Nginx配置 #

修改Nginx的站点配置，加上try_files指令：

location / {
  try_files $uri $uri/ /index.html;
}

这样Nginx找不到对应文件时，就返回index.html，让React Router处理路由，包括你的自定义404。

2. Apache配置 #

在项目根目录创建或修改.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开启了mod_rewrite模块。

3. Netlify部署 #

在项目根目录建_redirects文件，加一行：

/*    /index.html   200

4. Vercel部署 #

创建vercel.json文件，写入：

{
  "rewrites": [
    { "source": "/(.*)", "destination": "/index.html" }
  ]
}

5. Create React App 补充配置 #

如果用CRA创建的项目，先在package.json里加homepage字段（没加的话）：

"homepage": ".",

但这只是处理资源路径，核心还是得做上面的服务器fallback配置。

额外要检查的点 #

• 确认NotFound组件没被生产环境的tree-shaking优化掉，可以在组件里加个console.log，构建后看控制台有没有输出。
• 通配符路由一定要放在所有其他路由的最后，比如：

<Routes>
  <Route path="/" element={<Home />} />
  <Route path="/about" element={<About />} />
  {/* 其他业务路由 */}
  <Route path="*" element={<NotFound />} /> {/* 最后放这个 */}
</Routes>

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