在 Docusaurus 中，可通过配置 @docusaurus/plugin-content-pages 的 exclude 选项，精准控制哪些路径不参与生产构建（如开发专用文档），同时保留在开发环境可访问，实现环境差异化路由管理。

在 docusaurus 中，可通过配置 `@docusaurus/plugin-content-pages` 的 `exclude` 选项，精准控制哪些路径不参与生产构建（如开发专用文档），同时保留在开发环境可访问，实现环境差异化路由管理。

Docusaurus 默认会将 src/pages/（或 docs/ 等内容目录）下的所有 Markdown/JSX 文件自动注册为页面。即使你从侧边栏（sidebar）中移除了某个子文件夹的链接，其页面仍可能通过直接 URL 访问——这在生产环境中存在安全与维护风险。真正有效的解决方案是在构建阶段彻底排除该路径。

✅ 正确做法：使用 plugin-content-pages 的 exclude 配置

@docusaurus/plugin-content-pages（Docusaurus v2+ 内置插件）支持 exclude 字段，接收正则表达式数组，匹配的路径将完全跳过页面生成和路由注册（包括 SSR 和客户端导航）。

以你的情况为例：假设开发专用文件夹为 src/pages/dev-only/，希望仅在生产构建（docusaurus build）中排除，而开发服务器（docusaurus start）中保留以便调试：

// docusaurus.config.js
module.exports = {
  // ... 其他配置
  plugins: [
    [
      '@docusaurus/plugin-content-pages',
      {
        path: 'src/pages',
        exclude: process.env.NODE_ENV === 'production' 
          ? [/^dev-only\//]  // 匹配 src/pages/dev-only/ 下所有文件
          : [],
      },
    ],
  ],
};

? 注意正则写法：路径匹配基于 src/pages/ 下的相对路径（不含 src/pages/ 前缀）。例如 src/pages/dev-only/guide.md 对应匹配路径为 dev-only/guide.md，因此 /^dev-only\// 是准确的。

⚠️ 关键注意事项

• exclude 仅作用于 plugin-content-pages 管理的页面（即 src/pages/ 及其子目录），不适用于 docs/ 目录；若需排除 docs/ 下的文件，请改用 @docusaurus/preset-classic 中 docs 插件的 exclude 选项：

  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          exclude: process.env.NODE_ENV === 'production' 
            ? ['dev-guide/**'] // 支持 glob 模式（v2.4+）
            : [],
        },
      },
    ],
  ],

• 排除后，对应 URL 将返回 404（生产环境），且不会出现在任何静态 HTML 输出或路由映射中，彻底杜绝意外访问。

• 若使用自定义 path（如 path: 'content/pages'），请确保正则匹配的是该自定义路径下的相对路径。

✅ 验证方式

1. 运行 NODE_ENV=production npm run build，检查输出日志是否不再出现 dev-only/xxx 相关页面构建记录；
2. 打开生成的 build/ 目录，确认无 dev-only/ 对应的 HTML 文件；
3. 在本地 build/ 静态服务中访问 /dev-only/，应返回 404；
4. 对比 npm run start 时仍可正常访问该路径，验证环境区分生效。

通过此方案，你既能保持开发调试便利性，又能确保生产站点干净、安全、符合文档发布规范。