Gatsby混合应用模板页面子路由问题：静态与客户端路由冲突

问题复盘 #

你现在的核心困境很清晰：要给2.5万+页面做静态生成的父路由（默认页），同时在父路由下挂载客户端专属子路由，但当前用createPage模板+pages目录组件的双Router方案，会触发全页重渲染，导致父路由的持久化数据丢失；而Derek Nguyen的小站点方案，因为会把所有matchPath数据打包进JS，直接造成Bundle体积暴增至3.1MB，完全没法适配你的大站点规模。

核心思路：统一路由控制，拆分静态与客户端逻辑 #

解决问题的关键是不要在两个地方（createPage模板和pages组件）分别加Router，而是把静态生成逻辑和客户端路由逻辑合并到同一个入口：让Gatsby只负责父路由的静态HTML生成，子路由完全交给客户端React Router接管，同时保证父组件的状态/数据不被销毁。

步骤1：重构createPage配置，仅生成父路由静态HTML #

首先在gatsby-node.js里，用createPage只生成需要静态渲染的父路由，模板里不需要加Router，只负责渲染父容器和默认内容，预留客户端子路由的挂载插槽：

// gatsby-node.js 中的 createPage 配置
exports.createPage = async ({ graphql, actions }) => {
  const { createPage } = actions;
  // 从GraphQL拉取所有页面的slug/id数据
  const pages = await graphql(`
    query {
      allYourPageData {
        nodes {
          slug
          id
        }
      }
    }
  `);

  pages.data.allYourPageData.nodes.forEach(page => {
    createPage({
      path: `/test/${page.slug}/${page.id}`, // 父路由路径
      component: require.resolve("./src/templates/ParentContainer.js"),
      context: { slug: page.slug, id: page.id },
    });
  });
};

然后是父容器模板ParentContainer.js，这里只处理静态内容和持久化数据，用Outlet作为子路由的挂载点：

// src/templates/ParentContainer.js
import React from "react";
import { useStaticQuery, graphql } from "gatsby";
import { Outlet } from "react-router-dom";

const ParentContainer = ({ pageContext }) => {
  // 获取父路由需要持久化的静态数据
  const staticData = useStaticQuery(graphql`
    query {
      # 你的父路由数据查询逻辑
    }
  `);

  return (
    <div className="parent-container">
      {/* 静态渲染的父内容，比如导航、默认页面内容 */}
      <div className="default-static-content">
        {/* 这里是预生成的静态HTML内容 */}
      </div>
      {/* 客户端子路由的挂载插槽，只有访问子路由时才渲染对应组件 */}
      <Outlet />
    </div>
  );
};

export default ParentContainer;

步骤2：在pages目录创建客户端路由入口，接管子路由 #

在pages目录下创建动态匹配父路由的组件，用React Router的Routes和Route定义子路由，把父容器作为布局组件复用：

// src/pages/test/[slug]/[id].js
import React from "react";
import { Routes, Route, useParams } from "react-router-dom";
import ParentContainer from "../../../templates/ParentContainer";
import SecondTabRoute from "../../../components/SecondTabRoute";
import ThirdTabRoute from "../../../components/ThirdTabRoute";

const ClientRouterWrapper = () => {
  const { slug, id } = useParams();

  return (
    <ParentContainer pageContext={{ slug, id }}>
      <Routes>
        {/* 客户端子路由1：第二个标签页 */}
        <Route path="second-tab-route" element={<SecondTabRoute />} />
        {/* 客户端子路由2：第三个标签页 */}
        <Route path="third-tab-route" element={<ThirdTabRoute />} />
      </Routes>
    </ParentContainer>
  );
};

export default ClientRouterWrapper;

步骤3：配置Gatsby的客户端路由规则 #

最后在gatsby-config.js里告诉Gatsby，哪些子路由是客户端专属的，不要尝试静态生成：

// gatsby-config.js
module.exports = {
  // 其他配置项...
  plugins: [
    // 其他插件...
    {
      resolve: `gatsby-plugin-react-router`,
      options: {
        // 排除子路由，交给React Router接管
        excludePaths: [`/test/*/*/second-tab-route`, `/test/*/*/third-tab-route`],
      },
    },
  ],
};

如果不想用插件，也可以在gatsby-browser.js里全局包裹React Router：

// gatsby-browser.js
import React from "react";
import { BrowserRouter } from "react-router-dom";

export const wrapRootElement = ({ element }) => {
  return <BrowserRouter>{element}</BrowserRouter>;
};

方案优势 #

• Bundle体积控制：不再打包所有matchPath数据，静态生成仅针对父路由，子路由完全是客户端动态匹配，不会额外增加Bundle体积。
• 避免全页重渲染：父容器ParentContainer仅渲染一次，子路由通过Outlet挂载，切换子路由时只会更新插槽内的内容，父组件的状态和数据全程持久化。
• 适配Gatsby规则：父路由走createPage静态生成HTML，子路由作为客户端路由被Gatsby忽略，完美匹配你的需求。

额外注意事项 #

• 确保安装了react-router-dom和gatsby-plugin-react-router（使用插件方案时）。
• 子路由跳转必须用React Router的Link组件，不要用普通<a>标签，否则会触发全页刷新。
• 父路由需要的动态参数，要通过useParams()获取后传递给ParentContainer的pageContext。

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