Fumadocs项目中使用src目录时Loader不识别rootDir的问题解析

在Fumadocs项目中，当开发者尝试将文档内容迁移到src目录下时，可能会遇到一个常见问题：虽然MDX文件的数据已经成功生成在.source/index.js文件中，但通过getPages()和getPage()等API却无法获取到这些数据。

问题本质

这个问题的核心在于对Fumadocs构建流程的误解。Fumadocs的source API实际上是一个构建时(build time)的功能，它会在项目根目录下生成.source/index.js文件。这个生成过程与开发者在代码中设置的rootDir参数无关。

正确配置方法

要解决这个问题，开发者应该：

1. 保持.source目录在项目根目录下生成，这是Fumadocs的默认行为
2. 在source.config.ts文件中配置文档目录路径，而不是尝试通过rootDir参数修改
3. 可以通过TypeScript的路径别名(alias)功能来简化导入路径

技术原理

Fumadocs的构建流程分为两个阶段：

1. 构建阶段：扫描指定目录下的MDX文件，在根目录生成.source/index.js
2. 运行时：应用程序通过getPages()等API读取生成的数据

这种设计分离了构建时和运行时的关注点，使得构建过程更加高效，同时也保持了运行时的灵活性。

最佳实践

对于希望将文档内容放在src目录下的项目，建议采用以下结构：

project-root/
  .source/          // 自动生成，不要手动修改
  src/
    content/
      docs/         // 实际存放MDX文件
    app/
      // Next.js应用代码

然后在tsconfig.json中配置路径别名，例如：

{
  "compilerOptions": {
    "paths": {
      "@docs/*": [".source/*"]
    }
  }
}

这样既保持了Fumadocs的标准构建流程，又能让项目代码组织更加清晰。

总结

理解Fumadocs的构建流程和API设计理念对于正确使用这个工具至关重要。开发者应该遵循框架的约定，通过正确的配置文件来定义文档目录，而不是尝试通过参数覆盖默认行为。这种设计模式在很多现代前端工具中都很常见，它通过约定优于配置的原则，简化了项目的设置过程。