TypeDoc 0.26新特性：简化多包项目的文档配置

在大型TypeScript项目中，特别是采用monorepo结构的项目，为每个子包维护独立的TypeDoc配置往往会导致大量重复工作。TypeDoc 0.26版本引入了一项重要改进，通过新的packageOptions配置项，显著简化了多包项目的文档生成流程。

传统配置方式的痛点

在之前的TypeDoc版本中，每个子包都需要单独维护一个配置文件，即使这些配置大部分内容相同。典型的配置结构如下：

{
    "extends": ["../../typedoc.base.json"],
    "entryPoints": ["src/index.ts"]
}

这种模式存在几个明显问题：

1. 配置重复率高，维护成本大
2. 修改公共配置需要同步更新所有子包
3. 增加了项目管理的复杂性

新解决方案：packageOptions

TypeDoc 0.26引入的packageOptions允许在根配置文件中统一管理所有子包的配置。这个新特性：

1. 支持在根目录的TypeDoc配置中定义公共设置
2. 采用递归引用机制，确保配置的完整性和一致性
3. 仍然允许子包覆盖特定配置项

实际应用示例

假设一个monorepo项目结构如下：

my-project/
├── packages/
│   ├── pkg1/
│   ├── pkg2/
│   └── pkg3/
├── typedoc.base.json
└── typedoc.json

现在可以在根目录的typedoc.json中统一配置：

{
    "packageOptions": {
        "entryPoints": ["src/index.ts"],
        "theme": "default",
        "out": "docs"
    }
}

技术实现原理

packageOptions的工作机制是：

1. 首先加载根配置中的packageOptions
2. 然后加载子包特定的配置
3. 最后将两者合并，子包配置优先

这种实现方式既保持了配置的灵活性，又避免了重复。

与其他工具的关系

值得注意的是，虽然TypeDoc解决了自身的配置重复问题，但TypeScript项目中的tsconfig.json文件仍然需要在每个子包中单独维护。这是由于TypeScript编译器本身的限制所致。

升级建议

对于现有项目：

1. 检查并整理各子包的TypeDoc配置
2. 将公共配置提取到根目录的packageOptions中
3. 移除子包中冗余的配置项
4. 测试文档生成结果是否符合预期

TypeDoc 0.26的这一改进显著提升了大型TypeScript项目的文档维护效率，是monorepo项目架构的重要优化。