Gatsby生产环境动态路由刷新页面出现404问题求助

我之前也碰到过完全一样的状况，太懂这种客户端跳转正常、一刷新就报错的憋屈感了！核心原因是Gatsby作为静态站点生成器，默认只会构建你显式生成的静态页面，而你现在的动态路由（比如/blog/my-post、/blog/category/react这类）在构建阶段并没有生成对应的HTML文件。刷新页面时浏览器直接向服务器请求这些路径，服务器找不到对应文件就返回404；但客户端跳转是前端React Router在处理，所以不会有问题。

下面给你一步步梳理解决方案：

1. 用createPages预生成所有动态页面 #

你当前的gatsby-node.js只配置了客户端路由的匹配规则，但没有实际生成每个动态页面的静态文件。我们需要遍历博客、分类、标签、作者的数据源，为每个条目生成对应的静态页面：

修改你的gatsby-node.js，替换成类似这样的代码（根据你实际的数据源调整查询语句）：

exports.createPages = async ({ graphql, actions }) => {
  const { createPage } = actions;

  // 查询所有需要生成页面的动态数据
  const data = await graphql(`
    query DynamicPagesQuery {
      # 替换成你实际的博客数据查询，这里以Markdown为例
      allMarkdownRemark(filter: {frontmatter: {type: {eq: "blog"}}}) {
        nodes {
          frontmatter {
            slug
            category
            tags
            author
          }
        }
      }
      # 查询分类、标签、作者数据（如果有单独数据源）
      allCategories {
        nodes {
          name
        }
      }
      allTags {
        nodes {
          name
        }
      }
      allAuthors {
        nodes {
          name
        }
      }
    }
  `);

  // 生成博客详情页
  data.data.allMarkdownRemark.nodes.forEach(blog => {
    createPage({
      path: `/blog/${blog.frontmatter.slug}`,
      // 替换成你的BlogDetail组件实际路径
      component: require.resolve("./src/templates/BlogDetail.js"),
      context: {
        slug: blog.frontmatter.slug,
      },
    });
  });

  // 生成分类页
  data.data.allCategories.nodes.forEach(category => {
    createPage({
      path: `/blog/category/${category.name}`,
      component: require.resolve("./src/templates/Category.js"),
      context: {
        category: category.name,
      },
    });
  });

  // 生成标签页
  data.data.allTags.nodes.forEach(tag => {
    createPage({
      path: `/blog/tags/${tag.name}`,
      component: require.resolve("./src/templates/Category.js"),
      context: {
        tag: tag.name,
      },
    });
  });

  // 生成作者页
  data.data.allAuthors.nodes.forEach(author => {
    createPage({
      path: `/blog/author/${author.name}`,
      component: require.resolve("./src/templates/Category.js"),
      context: {
        author: author.name,
      },
    });
  });
};

// 保留原有的onCreatePage配置，确保客户端路由的 fallback 逻辑
exports.onCreatePage = async ({ page, actions }) => {
  const { createPage } = actions;
  if (page.path.match(/^\/blog/)) {
    page.matchPath = "/blog/*";
    createPage(page);
  }
};

这里的核心是：在构建阶段把每个动态路由对应的页面都生成出来，这样刷新时服务器就能找到对应的HTML文件了。

2. 配置服务器Fallback（针对无法预生成的动态页面） #

如果你的动态数据是实时获取的（比如来自后端API，无法在构建阶段拿到），没法预生成所有页面，这时候需要配置服务器，让所有/blog/*的请求都跳转到index.html，交给前端React Router处理路由：

• Netlify：在项目根目录创建_redirects文件，内容如下：

  /blog/* /index.html 200
  

• Vercel：创建vercel.json文件，添加配置：

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

• Nginx：在站点配置的location块中添加：

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

3. 检查客户端路由细节 #

• 尽量使用Gatsby自带的<Link>组件做跳转，不要用原生<a>标签——<Link>是客户端跳转，不会触发页面刷新，能避免不必要的服务器请求。
• 确认你用的Router组件（不管是@reach/router还是react-router-dom）的basepath配置和生成的页面路径一致，避免路由匹配混乱。

4. 测试生产构建 #

一定要运行gatsby build之后再用gatsby serve测试，因为gatsby develop的开发服务器会自动处理路由，和生产环境的静态服务器行为不一样，只有生产构建后才能验证真实效果。

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