NG-ZORRO项目中isolatedModules支持的解决方案

背景介绍

在TypeScript 5.5版本中，引入了一个重要的编译选项isolatedModules，这个选项旨在提高构建性能。当开发者在使用Angular 18.1及以上版本时，这个选项默认会被启用。isolatedModules模式要求每个文件必须是独立的模块，不能依赖于其他文件的类型信息，这样可以实现更高效的增量编译和并行处理。

问题现象

当开发者在项目中启用isolatedModules选项后，如果同时使用了NG-ZORRO组件库（特别是其中的图标模块），可能会遇到以下编译错误：

TS6053: File '.../node_modules/ng-zorro-antd/icon/public-api.ngtypecheck.d.ts' not found.

这个错误表明编译器无法找到类型检查文件，导致构建过程失败。问题的根源在于NG-ZORRO的图标模块中存在对.ngtypecheck.d.ts文件的引用，而这类文件在isolatedModules模式下不会被生成。

技术原理

isolatedModules是TypeScript的一个严格模式，它要求：

1. 每个文件必须能够独立编译，不依赖其他文件的类型信息
2. 禁止使用跨文件的类型合并
3. 所有导入必须包含文件扩展名

在Angular生态中，.ngtypecheck.d.ts文件是Angular编译器生成的临时类型检查文件，它们不是稳定的API，也不应该被直接引用。在isolatedModules模式下，这类文件不会被生成，因此导致引用失败。

解决方案

NG-ZORRO团队已经在v18.1.1版本中修复了这个问题。修复方案主要包括：

1. 移除了对.ngtypecheck.d.ts文件的直接引用
2. 重构了图标模块的类型定义方式
3. 确保所有类型声明符合isolatedModules的要求

对于开发者来说，解决方案非常简单：

1. 升级NG-ZORRO到v18.1.1或更高版本
2. 确保项目中的TypeScript版本为5.5或更高
3. 可以安全地启用isolatedModules选项

最佳实践

为了充分利用isolatedModules带来的性能优势，同时避免类似问题，建议开发者：

1. 保持NG-ZORRO和Angular的版本同步更新
2. 在大型项目中逐步启用isolatedModules，先在小范围测试
3. 定期检查项目中的类型定义，避免直接引用编译器生成的临时文件
4. 使用Angular官方推荐的构建工具链，确保编译过程的一致性

总结

TypeScript的isolatedModules选项为Angular项目带来了显著的构建性能提升，但也需要生态库做出相应的适配。NG-ZORRO团队及时响应，在v18.1.1版本中完美解决了兼容性问题，使开发者能够无缝享受新技术带来的优势。这体现了NG-ZORRO作为成熟UI组件库对开发者体验的重视和技术前瞻性。