docusaurus 默认会将 src/pages/ 下所有 .mdx 或 .jsx 文件作为页面处理，可通过 @docusaurus/plugin-content-pages 的 exclude 配置项精准排除特定路径，实现开发环境可访问、生产构建不打包的灵活控制。
docusaurus 默认会将 src/pages/ 下所有 .mdx 或 .jsx 文件作为页面处理，可通过 @docusaurus/plugin-content-pages 的 exclude 配置项精准排除特定路径，实现开发环境可访问、生产构建不打包的灵活控制。
在 Docusaurus 2 中，页面内容由 @docusaurus/plugin-content-pages 插件统一管理。即使你已从侧边栏（sidebar）中移除了某个子目录的链接，只要该目录下存在合法页面文件（如 dev-notes/index.mdx），它仍会在 docusaurus build 时被编译并输出到 build/ 目录中，并可通过直接 URL 访问——这不符合“仅用于开发”的设计意图。
✅ 正确做法是：利用插件原生支持的 exclude 选项，按构建环境动态过滤路径。你只需在 docusaurus.config.js 的 plugins 或 presets 对应配置中添加 exclude 字段：
// docusaurus.config.js
module.exports = {
// ... 其他配置
presets: [
[
'@docusaurus/preset-classic',
/** @type {import('@docusaurus/preset-classic').Options} */
({
pages: {
exclude: process.env.NODE_ENV === 'production'
? [/^\/dev-notes\//, /\/src\/pages\/dev-notes\//]
: [],
},
// 其他 preset 配置（docs, blog 等）
}),
],
],
};
⚠️ 注意事项：
- 正则表达式需匹配路由路径（URL path），而非文件系统路径。例如，若 dev-notes/index.mdx 生成的路由为 /dev-notes/，则应匹配 /^\/dev-notes\//；
- 若页面位于 src/pages/ 下（如 src/pages/dev-notes/index.mdx），其默认路由即为 /dev-notes/，无需额外配置 routeBasePath；
- exclude 作用于插件解析阶段，早于路由注册和静态生成，因此被排除的文件不会出现在 HTML 输出中，也无法通过任何 URL 访问（生产环境）；
- 开发服务器（docusaurus start）中保持 exclude: []，确保调试顺畅；
- 不要依赖 sidebar 隐藏或 .gitignore 来规避构建——它们均不影响页面打包逻辑。
? 进阶提示：你也可结合 process.env.DOCUSAURUS_ENV 自定义环境变量，或使用 fs.existsSync() 动态判断路径是否存在，进一步增强配置鲁棒性。最终目标是让文档站点专注交付，而开发资产真正“隐身”于生产构建之外。
