Gatsby使用{mdx.slug}生成页面时cycling路径下mdx返回404问题排查

安全阿岳

2026-10-1

排查解决步骤

第一步：检查页面生成逻辑（一般在gatsby-node.js文件的createPages方法中）
大概率是你生成页面路径时写死了前缀，比如类似如下的硬编码：
```
createPage({
  path: `/mountains/${node.slug}`,
  // 其余配置
})
```
你需要根据mdx文件所属的文件夹动态拼接路径前缀，区分mountains和cycling两类内容。
第二步：如果使用Gatsby文件系统路由（即动态路由文件放在src/pages目录下，命名为{mdx.slug}.js这类格式）
确认你是否把动态路由文件只放在了src/pages/mountains路径下，如果是，将同一份动态路由文件复制到src/pages/cycling路径下即可自动生成对应前缀的路由。

第三步：修正GraphQL查询，增加路径过滤条件
你的原有查询没有区分文件所属目录，当两个目录下出现重名slug时会出现数据匹配错误，修改查询增加fileAbsolutePath过滤：

export const query = graphql`
  query($slug: String, $dirRegex: String) {
    mdx(
      slug: {eq: $slug}
      fileAbsolutePath: {regex: $dirRegex}
    ) {
      body
      frontmatter {
        title
        date(formatString: "MMMM DD, YYYY")
        hero_image_alt
        hero_image_credit_link
        hero_image_credit_text
        hero_image {
          childImageSharp {
            gatsbyImageData
          }
        }
      }
    }
  }
`

生成页面时根据文件所属目录传入对应正则即可，比如cycling目录的内容传入"/cycling/"作为$dirRegex参数。

第四步：验证slug生成逻辑
打开Gatsby内置的GraphiQL调试工具（开发环境下默认访问http://localhost:8000/___graphql），执行如下查询确认cycling目录下文件的slug生成是否正确，没有多余的路径前缀：
```
query {
  allMdx {
    nodes {
      slug
      fileAbsolutePath
    }
  }
}
```
如果slug生成异常，检查gatsby-node.js中createFilePath的配置，确认是否正确裁剪了父级路径。
第五步：清除缓存重启服务
所有修改完成后重新执行gatsby clean，再启动开发服务验证路由是否正常。