[!info] related notes

• 所属 MOC: TypeScript MOC
• 配置入口: tsconfig 使用详解
• 并列概念: TypeScript 中的 noEmit, TypeScript 中的 verbatimModuleSyntax, TypeScript 中的 jsx 编译选项

TypeScript 中的 isolatedModules

一句话定义

isolatedModules 用来提前检查：这份代码是否能被“逐文件独立转译”的工具安全处理。

核心机制 / 工作原理

很多现代工具链并不会像 tsc 一样先构建整个 TypeScript program，再统一分析所有文件。

它们更像是：

• Babel
• SWC
• esbuild

这种一份文件一份文件地转译。

开启：

{
  "compilerOptions": {
    "isolatedModules": true
  }
}

后，TypeScript 会对那些“只有跨文件全局信息才能正确理解”的写法提前报警。

最小例子 / 最小场景

这在以下项目里尤其常见：

• noEmit: true，由 bundler 负责真正转译
• React / Vue / Vite 项目
• Babel / SWC 驱动的 app 项目

边界与易混淆点

它不是更严格的类型系统

官方文档明确说明，这个选项本身并不改变代码的运行行为。

它更像是一组“单文件转译兼容性检查”。

它会提前暴露某些 tsc 能理解、但单文件转译器难处理的写法

官方文档举到的典型问题包括：

• 导出一个纯类型名称
• 在非模块脚本里使用 namespace
• 引用 ambient const enum

这些问题本质上都和“转译器拿不到完整 program 信息”有关。

bundler 项目里经常值得开启

如果真正负责输出的是 Babel、SWC、esbuild 或框架内置转译器，这个选项通常能更早暴露兼容性边界。

参考信息

• TSConfig isolatedModules: https://www.typescriptlang.org/tsconfig/isolatedModules.html