Gatsby MDX 页面在子目录中不完全渲染的解决方案

新闻中心 NEWS CENTER

您当前位置：首页 > 新闻中心 > 网络学院

Gatsby MDX 页面在子目录中不完全渲染的解决方案

2025-10-28

浏览次数：次

返回列表

gatsby mdx 页面在子目录中不完全渲染的解决方案

本文旨在解决 Gatsby 项目中使用 MDX 文件时，当文件位于 `src/pages` 的子目录中，构建后页面可能无法完全渲染的问题。通过分析问题根源，提供了一种移除 `gatsby-plugin-page-creator` 插件的解决方案，并解释了其背后的原理，帮助开发者避免类似问题。

问题描述

在使用 Gatsby 构建网站时，如果 MDX 文件存储在 src/pages 目录的子目录中，例如：

src/pages/
  --project/
    --contact.md
    --outputs.md
    --project.md
    --sources.md
  --software/
    --apps.md
    --frontend.md
    --system.md

在执行 gatsby build 后，部分页面可能会出现只渲染页面主体内容，而缺失布局组件和样式的情况。例如，访问 http://localhost:9000/project 时，可能只显示文本内容，而访问 http://localhost:9000/software 下的页面则正常。

问题分析

问题的根源在于 gatsby-plugin-page-creator 插件可能与 gatsby-plugin-mdx 插件产生冲突，导致重复创建页面。在构建过程中，会出现类似以下的警告信息：

warn Non-deterministic routing danger: Attempting to create page: "/project/contact/", but page
"/project/contact" already exists

这个警告表明 Gatsby 试图创建重复的路由，最终导致页面渲染不完整。

解决方案

移除 gatsby-plugin-page-creator 插件通常可以解决这个问题。

找到 gatsby-config.js 文件。
Mureka
Mureka是昆仑万维最新推出的一款AI音乐创作工具，输入歌词即可生成完整专属歌曲。
1091 查看详情

移除 gatsby-plugin-page-creator 插件的配置。 从 plugins 数组中删除包含 gatsby-plugin-page-creator 的对象。

// gatsby-config.js
module.exports = {
  plugins: [
    // 其他插件...
    // {
    //   resolve: `gatsby-plugin-page-creator`,
    //   options: {
    //     path: `${__dirname}/src/pages`,
    //   },
    // },
    // 其他插件...
  ],
};

重新构建项目。 运行 gatsby clean 清理缓存，然后运行 gatsby build 重新构建项目。
```
gatsby clean
gatsby build
```

原因解释

gatsby-plugin-page-creator 的作用是根据 src/pages 目录下的文件自动创建页面。在早期，如果使用非标准的 Markdown 文件扩展名（如 .mdx），可能需要此插件来确保这些文件被正确解析为页面。然而，现在 gatsby-plugin-mdx 插件已经能够处理 MDX 文件的页面创建，因此 gatsby-plugin-page-creator 变得多余，反而可能导致冲突。

移除 gatsby-plugin-page-creator 后，gatsby-plugin-mdx 将负责所有 MDX 文件的页面创建，从而避免重复创建和渲染问题。

注意事项

在移除 gatsby-plugin-page-creator 之前，请确保你使用的是 gatsby-plugin-mdx 来处理 MDX 文件。
如果你的项目中依赖 gatsby-plugin-page-creator 的其他功能（例如，处理非 MDX 文件的页面创建），请谨慎操作，并确保移除后不会影响其他页面的渲染。
在移除插件后，务必清理 Gatsby 的缓存，以确保新的配置生效。