Gatsby中src/pages子文件夹下MDX页面构建后无法完整渲染

核心原因 #

Gatsby会自动将src/pages目录下的所有文件（包括MDX）生成对应路径的页面，而你同时通过gatsby-node.js的createPages手动创建了相同路径的页面，导致页面生成冲突：开发环境和生产构建的页面优先级不同，最终生产环境加载了Gatsby自动生成的纯MDX内容页面（无布局和样式），而非你通过模板创建的页面。

解决方案（推荐方案一） #

方案一：将MDX文件移出src/pages目录 #

彻底避免自动生成页面的冲突，完全通过createPages控制页面渲染：

1. 在项目根目录创建src/content目录，将src/pages下的project、software子文件夹全部移动到src/content中，最终结构如下：

src/content/
  --project/
    --contact.md
    --outputs.md
    --project.md
    --sources.md
  --software/
    --apps.md
    --frontend.md
    --system.md
src/pages/
  # 保留原有的JS/JSX页面（如404.js、index.js等）

2. 更新gatsby-config.js中gatsby-source-filesystem的路径配置：

{
  resolve: `gatsby-source-filesystem`,
  options: {
    name: `pages`,
    path: `${__dirname}/src/content`, // 改为新的content目录
  },
},

3. 重新执行gatsby build，此时所有MDX页面都会通过你定义的templates/page.js模板渲染，布局和样式正常加载。

方案二：禁用Gatsby自动处理src/pages中的MDX文件 #

如果不想移动文件，可修改MDX插件配置，让Gatsby仅将src/pages中的MDX作为数据源，不自动生成页面：

1. 修改gatsby-config.js中gatsby-plugin-mdx的配置，添加exclude规则：

{
  resolve: `gatsby-plugin-mdx`,
  options: {
    extensions: [`.md`, `.mdx`, `.markdown`],
    exclude: /src\/pages\/(project|software)/, // 排除需要手动生成的目录
    gatsbyRemarkPlugins: [
      {
        resolve: `gatsby-remark-images`,
        options: {
          maxWidth: 1024,
        },
      },
    ],
  },
},

2. 确保src/pages中仅保留需要自动生成的JS/JSX页面，重新构建即可。

额外说明 #

• 你之前尝试将project.md重命名为index.md无效，是因为src/pages/project/index.md会被Gatsby自动生成/project路径的页面，仍然和createPages创建的页面冲突。
• software目录下页面正常，是因为该目录下没有顶级的software.md或index.md，自动生成的页面路径（如/software/apps）与你手动创建的路径一致，且在构建时未发生覆盖冲突，但这属于偶然情况，仍需统一处理避免后续问题。

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