Gatsby部署AWS S3+CloudFront：非首页先显404再加载内容问题排查

问题根源 #

你的情况是典型的静态页面未预生成+CloudFront/S3未配置Gatsby客户端路由 fallback导致的：Gatsby本应预渲染所有页面为静态HTML，但实际只有首页生成了静态文件，其他页面依赖客户端JS动态渲染；同时CloudFront在找不到对应静态文件时直接返回404页面，慢网下客户端JS加载延迟，就会先显示404再渲染内容。

分步修复 #

1. 修正gatsby-node.js的页面生成逻辑 #

确保createPages函数正确遍历所有WordPress页面/文章，并生成对应的静态HTML：

exports.createPages = async ({ graphql, actions }) => {
  const { createPage } = actions;
  // 查询所有WordPress文章和页面
  const { data } = await graphql(`
    query AllContent {
      allWpPost {
        nodes {
          slug
          id
        }
      }
      allWpPage {
        nodes {
          slug
          id
        }
      }
    }
  `);

  // 生成文章页面
  data.allWpPost.nodes.forEach(post => {
    createPage({
      path: `/${post.slug}/`, // 路径要和访问URL完全匹配（比如/the-sandman/）
      component: require.resolve("./src/templates/page-template.js"),
      context: { id: post.id },
    });
  });

  // 生成独立页面
  data.allWpPage.nodes.forEach(page => {
    createPage({
      path: `/${page.slug}/`,
      component: require.resolve("./src/templates/page-template.js"),
      context: { id: page.id },
    });
  });
};

• 运行gatsby build后，检查public目录下是否存在对应页面的文件夹（比如public/the-sandman/index.html），如果不存在，说明查询或路径生成有问题。

2. 配置CloudFront和S3的Fallback规则 #

这是关键，要让所有404请求转发到Gatsby的index.html，由客户端路由处理：

• S3桶设置：静态网站托管中，将“索引文档”和“错误文档”都设为index.html。
• CloudFront行为设置：
  1. 进入对应分发的“行为”标签，编辑默认行为。
  2. 找到“错误页面”配置，添加规则：
     • 错误代码：404
     • 响应页面路径：/index.html
     • HTTP响应代码：200
  3. 保存并等待CloudFront部署生效。

3. 排查插件与构建配置 #

• 移除所有客户端路由相关插件（比如gatsby-plugin-client-side-redirect），确保没有强制动态路由的配置。
• 检查gatsby-config.js，确认没有pathPrefix配置错误，或者禁用SSG的设置。

4. 验证缓存策略 #

• CloudFront中，确保index.html的缓存TTL不要过长（比如设为5分钟），避免旧的客户端JS缓存导致路由异常。
• 测试前先清空CloudFront缓存和本地浏览器缓存。

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