Gatsby未知路径动态创建页面出现WIN32非法路径字符如何解决

问题原因 #

该报错由Windows系统的路径字符限制触发：冒号:属于WIN32系统的非法文件名/路径字符，Gatsby在构建阶段会尝试为你通过createPage声明的路径生成对应的静态HTML文件，路径中:id携带的冒号触发了系统层面的路径校验错误。
你需要的是无需预生成所有页面对应的客户端动态路由场景，无需用冒号声明参数，按以下方案修改即可：

解决方案 #

方案1：使用Gatsby文件系统路由（推荐，无需编写createPage逻辑） #

直接在src/pages目录下创建嵌套的方括号命名文件：
src/pages/account/orders/[id].tsx
Gatsby会自动识别方括号包裹的内容为动态参数，无需额外配置gatsby-node.js，自动兼容全平台路径规则，客户端可以直接通过useParams钩子获取id参数：

import { useParams } from "gatsby"
const OrderPage = () => {
  const { id } = useParams()
  // 后续业务逻辑
}

方案2：修改createPage配置适配动态路由 #

如果你需要保留在gatsby-node.js中声明路由的写法，将路径参数的声明方式改为方括号格式，同时调整配置：

createPage({
  path: '/account/orders/[id]',
  matchPath: '/account/orders/:id', // 这里的matchPath是客户端路由匹配规则，依然用冒号声明参数即可
  component: path.resolve('./src/templates/order.tsx'),
})

修改后构建阶段生成的静态文件名为[id].html，方括号属于Windows合法路径字符，不会触发报错，客户端访问时依然可以匹配任意/account/orders/xxx格式的路径，参数可以通过Gatsby的路由钩子获取。

低版本Gatsby额外配置 #

如果你的Gatsby版本低于4，需要额外安装gatsby-plugin-create-client-paths插件，在gatsby-config.js中声明动态路由前缀：

module.exports = {
  plugins: [
    {
      resolve: `gatsby-plugin-create-client-paths`,
      options: { prefixes: [`/account/orders/*`] },
    },
  ],
}

配置后所有/account/orders/开头的路径都会指向你指定的order模板组件，无需预生成所有id对应的页面。

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