Gatsby MDX 页面在 src/pages 子目录中未完全渲染问题的解决

本文档旨在解决 Gatsby 项目中使用 MDX 文件时，当文件位于 `src/pages` 的子目录中，构建后部分页面出现样式丢失、布局组件缺失的问题。通过分析 `gatsby-plugin-page-creator` 插件可能导致的路由冲突，提供解决方案以确保所有页面正确渲染。

问题描述

在使用 Gatsby 构建网站时，如果将 MDX 文件放置在 src/pages 目录的子目录中，可能会出现部分页面在构建后渲染不完整的问题。具体表现为：页面内容（正文）可以正常显示，但页面的布局组件（如头部、尾部、侧边栏等）和样式丢失，导致页面显示异常。

例如，以下目录结构：

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

在构建后的网站中，访问 http://localhost:9000/contact 页面可能正常渲染，但访问 http://localhost:9000/project 或 http://localhost:9000/project/contact等页面时，只会显示页面内容，而缺少布局和样式。

问题分析

这种现象通常是由于 Gatsby 在页面创建过程中出现了路由冲突导致的。具体来说，可能存在以下原因：

1. gatsby-plugin-page-creator 插件的影响：该插件会自动扫描 src/pages 目录下的文件，并根据文件路径生成对应的页面路由。如果同时使用了 gatsby-plugin-mdx 插件，并且 MDX 文件也位于 src/pages 目录下，则可能导致重复创建相同路由的页面，从而引发冲突。
2. 页面路由冲突：在上述例子中，如果 src/pages/project/project.md 文件的 slug 被定义为 /project，而 src/pages/project/contact.md 文件的 slug 被定义为 /project/contact，那么 Gatsby 可能会尝试为 /project 路由创建两个不同的页面，从而导致冲突。

解决方案

解决此问题的关键在于避免重复创建相同路由的页面。以下是一些可能的解决方案：

1. 移除 gatsby-plugin-page-creator 插件

   如果你的项目已经使用了 gatsby-plugin-mdx 插件来处理 MDX 文件，那么通常不需要再使用 gatsby-plugin-page-creator 插件。移除该插件可以避免重复创建页面的问题。

   在 gatsby-config.js 文件中，找到 plugins 数组，并移除 gatsby-plugin-page-creator 插件的配置项：

   

   Magic Write

   Canva旗下AI文案生成器

   下载

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

2. 检查并修改页面 slug

   确保每个 MDX 文件的 slug 都是唯一的，并且没有重复。如果存在重复的 slug，则需要修改其中一个，以避免路由冲突。 例如，如果 src/pages/project/project.md 文件的 slug 为 /project，而你希望保留该文件，则可以考虑将 src/pages/project/contact.md 文件的 slug 修改为 /project-contact 或其他唯一的名称。

3. 调整目录结构

   如果以上方法无法解决问题，可以尝试调整目录结构，将 MDX 文件移动到 src/components 或其他非 src/pages 目录下的文件夹中。然后，使用 gatsby-source-filesystem 插件来读取这些文件，并在 gatsby-node.js 文件中使用 createPage API 来手动创建页面。

   例如，可以将 MDX 文件移动到 src/content 目录下：

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

   然后在 gatsby-config.js 文件中配置 gatsby-source-filesystem 插件：

   module.exports = {
     plugins: [
       {
         resolve: `gatsby-source-filesystem`,
         options: {
           name: `content`,
           path: `${__dirname}/src/content`,
         },
       },
       `gatsby-plugin-mdx`,
       // ...其他插件
     ],
   };

   最后，在 gatsby-node.js 文件中使用 createPage API 来手动创建页面：

   const path = require("path");
   
   exports.createPages = async ({ graphql, actions, reporter }) => {
     const { createPage } = actions;
   
     const result = await graphql(`
       query {
         allMdx {
           edges {
             node {
               id
               frontmatter {
                 slug
                 title
               }
               fileAbsolutePath
             }
           }
         }
       }
     `);
   
     if (result.errors) {
       reporter.panicOnBuild("ERROR: Loading \"createPages\" query");
     }
   
     const posts = result.data.allMdx.edges;
   
     posts.forEach(({ node }) => {
       createPage({
         path: node.frontmatter.slug,
         component: path.resolve(`./src/templates/page.js`),
         context: {
           id: node.id,
         },
       });
     });
   };

   注意： 确保在 gatsby-node.js 文件中正确设置 fileAbsolutePath 属性，以便 Gatsby 能够找到 MDX 文件。

总结

当 Gatsby 项目中使用 MDX 文件时，如果出现页面渲染不完整的问题，通常是由于路由冲突导致的。通过移除 gatsby-plugin-page-creator 插件、检查并修改页面 slug 或调整目录结构，可以有效地解决此问题。在解决问题时，需要仔细分析项目的配置和目录结构，并根据具体情况选择合适的解决方案。