Docusaurus 文档插件中Globby扫描node_modules的性能问题分析

问题背景

在使用Docusaurus构建文档网站时，许多开发者会遇到一个性能问题：当启动开发服务器时，控制台会卡在"Starting the development server..."信息处，长时间没有响应。经过深入分析，发现这与插件内容文档(plugin-content-docs)的侧边栏生成机制有关。

问题根源

Docusaurus的文档插件在生成侧边栏时会使用Globby工具扫描项目目录，寻找_category_.*配置文件。默认情况下，这个扫描过程会包含项目中的所有目录，包括node_modules文件夹。当项目中存在大量依赖时，扫描node_modules目录会导致严重的性能问题，甚至内存溢出。

典型场景

这个问题在以下项目结构中尤为明显：

1. 大型monorepo项目
2. 将整个包目录设置为文档内容路径
3. 使用pnpm或yarn等包管理工具的项目
4. 项目依赖数量庞大

解决方案

推荐方案

最佳实践是避免将整个包目录设置为文档内容路径。建议：

1. 为文档创建专用目录(如docs)
2. 对于需要包含的README等文件，使用MDX导入方式：

import Readme from "../README.md";
<Readme />

配置调整方案

如果确实需要扫描整个目录，可以通过配置排除node_modules：

// docusaurus.config.js
module.exports = {
  plugins: [
    [
      '@docusaurus/plugin-content-docs',
      {
        // 其他配置...
        ignore: ['**/node_modules']
      }
    ]
  ]
};

性能优化建议

1. 精确指定文档路径，避免宽泛的目录包含
2. 对于大型项目，考虑拆分文档结构
3. 监控构建过程中的内存使用情况
4. 定期清理不必要的依赖

总结

Docusaurus作为优秀的文档工具，在特定场景下可能会遇到性能瓶颈。理解其内部工作机制并合理配置，可以显著提升开发体验。通过本文介绍的方法，开发者可以有效解决Globby扫描node_modules导致的性能问题，确保文档网站的高效运行。