求助：Docusaurus中.mdx文件Markdown跨页面链接失效问题

可能的原因及排查步骤 #

• 确认文件路径准确性
  检查../intermediate/01_create_project.mdx是否确实存在于项目的docs/intermediate/目录下。注意Docusaurus的链接解析基于当前文件相对路径，需确保大小写一致（部分系统区分大小写）。

• 验证MDX文件的路由配置
  确保docusaurus.config.js中presets的docs配置正确包含MDX扩展名：

  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          sidebarPath: require.resolve('./sidebars.js'),
          extensions: ['.md', '.mdx'], // 关键：添加.mdx支持
          editUrl: 'https://github.com/your/repo/edit/main/docs/',
        },
      },
    ],
  ],
  

• 使用Docusaurus推荐的链接语法
  尝试基于文档ID的链接格式（省略.mdx后缀），Docusaurus会自动解析对应文档：

  [创建项目](../intermediate/01_create_project)
  

• 清理缓存并重新构建
  执行命令清理缓存后重新构建，避免缓存导致的解析异常：

  npm run clear
  npm run build
  

• 检查侧边栏配置
  确保sidebars.js中包含目标MDX文件，未注册的文档可能无法被链接解析：

  module.exports = {
    docs: [
      {
        type: 'category',
        label: 'Intermediate',
        items: [
          'intermediate/01_create_project', // 包含目标文件路径（无扩展名）
        ],
      },
    ],
  };
  

额外提示 #

若以上步骤无效，可临时设置onBrokenLinks: 'warn'在docusaurus.config.js中，运行构建查看更详细的错误信息：

module.exports = {
  // 其他配置项
  onBrokenLinks: 'warn',
};

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