如何在 Docusaurus 构建过程中排除指定文件夹-js教程-PHP中文网

如何在 Docusaurus 构建过程中排除指定文件夹

本文介绍如何通过配置 @docusaurus/plugin-content-pages 的 exclude 选项，在生产构建（docusaurus build）中彻底移除特定文件夹，使其既不生成页面、也不可被 url 访问，同时保留在开发环境（docusaurus start）中用于调试或临时查阅。

本文介绍如何通过配置 @docusaurus/plugin-content-pages 的 exclude 选项，在生产构建（docusaurus build）中彻底移除特定文件夹，使其既不生成页面、也不可被 url 访问，同时保留在开发环境（docusaurus start）中用于调试或临时查阅。

Docusaurus 默认会将 src/pages/ 和文档目录（如 docs/）下的所有 .md/.mdx 文件自动转换为可访问页面。即使你从侧边栏（sidebar）中隐藏了某子目录（例如存放 Swagger 原始 JSON、脚本或草稿的 dev-assets/），该路径仍可能通过直接 URL 访问——这在生产环境中存在安全与维护风险。

✅ 正确做法是：在插件层面对内容进行构建时过滤，而非仅依赖 UI 隐藏。核心方案是利用 @docusaurus/plugin-content-pages（Docusaurus 2 内置插件）提供的 exclude 配置项，它支持正则表达式数组，匹配的路径将被完全跳过解析与路由注册。

✅ 配置步骤（推荐动态环境判断）

在 docusaurus.config.js 中定位 plugins 或 presets 配置（通常 @docusaurus/preset-classic 已内置 plugin-content-pages），显式覆盖其配置：

// docusaurus.config.js
module.exports = {
  // ... 其他配置
  presets: [
    [
      '@docusaurus/preset-classic',
      /** @type {import('@docusaurus/preset-classic').Options} */
      ({
        docs: {
          // ... docs 配置
        },
        pages: {
          // ? 显式配置 plugin-content-pages 的 exclude 行为
          exclude: process.env.NODE_ENV === 'production' 
            ? ['**/dev-assets/**', '**/drafts/**'] 
            : [],
        },
      }),
    ],
  ],
};

? 提示：exclude 接受 glob 模式（如 **/dev-assets/**）或正则（如 /\/dev-assets\//）。推荐使用 glob，语义清晰且兼容性更好。

⚠️ 注意事项

路径匹配基于文件系统相对路径：例如 dev-assets/ 若位于 src/pages/dev-assets/，则 **/dev-assets/** 可精准匹配；若在 docs/dev-assets/，需确认 docs/ 是否被 plugin-content-pages 扫描（默认仅扫描 src/pages/；文档类应配置 plugin-content-docs 的 exclude）。
文档目录需单独处理：如果你的待排除文件夹实际位于 docs/ 下（如 docs/api-specs/swagger.json），请改用 docs 插件的 exclude：
```
docs: {
  exclude: process.env.NODE_ENV === 'production' 
    ? ['api-specs/**'] 
    : [],
}
```
缓存影响：修改 exclude 后，建议清除缓存再构建：npm run build -- --no-cache。
开发体验保留：上述 process.env.NODE_ENV === 'production' 判断确保开发服务器（start）仍可访问这些路径，便于本地验证或调试。