静态Gatsby网站直接访问特定页面跳转至首页问题排查

问题原因 #

• S3资源匹配逻辑限制：手动输入example.com/path1时，S3会优先查找名为path1的文件或path1/index.html文件。如果Gatsby构建未生成对应路径的index.html（比如未配置正确的构建参数），或该文件未上传至S3，S3会返回403错误。
• CloudFront错误响应状态码未调整：虽然配置了403指向/index.html，但如果未将响应状态码改为200，浏览器收到的是带403状态的首页内容，Gatsby前端路由无法识别并渲染目标页面，最终自动跳转至首页。
• CloudFront路由规则缺失：未配置缓存行为将非根路径请求转发至index.html，导致SPA路由无法被正确处理。

解决方案 #

1. 确保Gatsby生成正确的静态文件结构 #

• 运行gatsby build后，检查本地public目录，确认存在path1/index.html文件（对应目标路由）。
• 若使用路径前缀，需在gatsby-config.js中添加pathPrefix: "/path1"，再用gatsby build --prefix-paths命令构建。

2. 调整CloudFront自定义错误响应配置 #

• 进入CloudFront控制台，找到目标分发，切换到「错误页面」标签：
  • 修改403错误的自定义响应：将HTTP响应代码设置为200，自定义错误路径保持/index.html。
  • 建议同步配置404错误的相同规则，覆盖所有资源未找到的场景。

3. 用Lambda@Edge实现优雅的SPA路由处理（可选） #

• 创建Origin Request类型的Lambda函数，将非静态资源请求转发至/index.html，示例代码：

exports.handler = (event, context, callback) => {
  const request = event.Records[0].cf.request;
  const uri = request.uri;

  // 仅转发非静态资源请求到首页
  if (!uri.includes('.') || uri.endsWith('/')) {
    request.uri = '/index.html';
  }

  callback(null, request);
};

• 将该函数关联到CloudFront分发的缓存行为中，确保所有SPA路由请求都能被正确处理。

4. 验证S3桶文件完整性 #

• 登录S3控制台，检查桶内是否存在path1/index.html文件。若缺失，重新上传Gatsby构建后的public目录所有内容，保持目录结构一致。

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