Gatsby v5.12.11生产环境自定义404页面失效求助

1. 检查cPanel自带错误页面设置 #

• 登录cPanel，找到「高级」分类下的「错误页面」工具
• 选中404错误选项，确认是否被设置为跳转首页或其他自定义页面，而非指向Gatsby生成的/404.html
• 若有自定义设置，改为直接调用/404.html，或选择「使用文档根目录中的默认文档」

2. 修正.htaccess配置（核心步骤） #

Gatsby静态站点在cPanel上需要正确的重写规则处理SPA路由和404，将根目录的.htaccess替换为以下内容：

<IfModule mod_rewrite.c>
  RewriteEngine On
  RewriteBase /
  RewriteRule ^index\.html$ - [L]
  RewriteCond %{REQUEST_FILENAME} !-f
  RewriteCond %{REQUEST_FILENAME} !-d
  # 优先返回404页面，而非转发到index.html
  RewriteRule ^(.*)$ /404.html [L,R=404]
</IfModule>

• 若站点部署在子目录（如xxx.com/blog），需将RewriteBase /改为RewriteBase /blog/，/404.html改为/blog/404.html
• 保存后用隐私窗口测试无效URL，避免缓存干扰

3. 确认构建产物上传完整性 #

• 本地执行gatsby build后，检查public目录是否同时存在404.html和404/index.html
• 上传到cPanel时，确保public下所有文件（含这两个404相关文件）完整上传至站点根目录（或对应子目录）
• 直接访问你的域名/404.html，若无法打开，说明文件未传全或存在权限问题

4. 调整文件权限 #

• 打开cPanel的「文件管理器」，选中404.html和404目录，右键选择「更改权限」
• 文件权限设为644，目录权限设为755，确保服务器可正常读取这些文件

5. 排查Gatsby配置冲突 #

• 检查gatsby-config.js中的插件（如gatsby-plugin-netlify等部署插件）是否覆盖404设置，可暂时禁用后重新构建测试
• 查看gatsby-browser.js中是否存在onRouteUpdate等路由监听代码，是否在生产环境误判路由并强制跳转首页

6. 验证服务器响应状态 #

• 执行命令curl -I 你的域名/无效路径，查看响应头信息
• 若返回302跳转首页，说明服务器层面的重定向优先级更高；若为404状态但内容是首页，说明.htaccess配置有误

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