Gatsby MDX 页面在子目录中渲染不完整的问题解决

新闻中心 NEWS CENTER

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

Gatsby MDX 页面在子目录中渲染不完整的问题解决

2025-10-29

浏览次数：次

返回列表

gatsby mdx 页面在子目录中渲染不完整的问题解决

本文档旨在帮助解决 Gatsby 项目中使用 MDX 文件时，将页面放置在 `src/pages` 的子目录中可能出现的渲染不完整问题。我们将分析问题的根本原因，并提供详细的解决方案，确保所有页面都能正确渲染布局和样式。

问题描述

在使用 Gatsby 构建网站时，如果将 MDX 文件放置在 src/pages 目录的子目录中，可能会遇到部分页面渲染不完整的问题。具体表现为，这些页面只显示内容主体（文本），而缺少布局组件的包裹以及样式。例如，如果你的目录结构如下：

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

访问 /contact 页面时可能渲染正常，但访问 /project 或其子页面时，页面可能缺少布局和样式。

问题原因分析

问题的根本原因在于 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-plugin-page-creator 插件会自动将 src/pages 目录下的文件转换为页面。当同时使用 gatsby-plugin-mdx 时，它也会根据 MDX 文件创建页面。这样就可能导致同一个路由被创建两次，从而引发渲染问题。

解决方案

解决此问题的关键是移除 gatsby-plugin-page-creator 插件，让 gatsby-plugin-mdx 插件单独负责页面创建。

移除 gatsby-plugin-page-creator 插件：

打开 gatsby-config.js 文件，找到 plugins 数组，移除 gatsby-plugin-page-creator 插件的配置。
万相营造
阿里妈妈推出的AI电商营销工具
168 查看详情
```
module.exports = {
  plugins: [
    // ... 其他插件
    // 移除以下插件
    // `gatsby-plugin-page-creator`,
    // ... 其他插件
  ],
};
```
检查 MDX 文件扩展名：

如果之前使用 gatsby-plugin-page-creator 插件是为了支持 .mdx 扩展名的 Markdown 文件，现在可以考虑将文件扩展名更改为标准的 .md。这样，gatsby-plugin-mdx 插件就能正确解析这些文件。
清理缓存并重新构建：

移除插件后，建议清理 Gatsby 的缓存，并重新构建项目，以确保更改生效。
```
gatsby clean
gatsby build
```

代码示例

以下是一个典型的 gatsby-config.js 文件的示例，展示了如何配置 gatsby-plugin-mdx 插件：

module.exports = {
  plugins: [
    {
      resolve: `gatsby-source-filesystem`,
      options: {
        name: `pages`,
        path: `${__dirname}/src/pages`,
      },
    },
    {
      resolve: `gatsby-plugin-mdx`,
      options: {
        extensions: [`.md`, `.mdx`, `.markdown`],
        gatsbyRemarkPlugins: [
          {
            resolve: `gatsby-remark-images`,
            options: {
              maxWidth: 1024,
            },
          },
        ],
      },
    },
  ],
};