[!info] related notes

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

TypeScript 中的 moduleDetection

一句话定义

moduleDetection 用来决定 TypeScript 如何判断一个文件应该被当成 script 还是 module。

核心机制 / 工作原理

官方文档列出三种模式：

• "auto"：默认模式，不只看 import / export，还会结合 package.json 的 "type": "module" 和某些 JSX 场景判断
• "legacy"：更接近旧版本 TypeScript，只靠 import / export 判断
• "force"：把每个非声明文件都当成 module

所以它回答的是：

一份文件是否具备模块语义，到底由什么信号来决定。

最小例子 / 最小场景

{
  "compilerOptions": {
    "moduleDetection": "force"
  }
}

这种配置常见于：

• 想避免脚本级全局污染
• 希望所有源码都以模块心智来组织

边界与易混淆点

它不等于 module

module 主要回答：

• 输出成什么模块格式

而 moduleDetection 回答：

• 当前文件是否被视为模块文件

两者相关，但不是一层问题。

auto 比很多人想的更智能

官方文档特别说明，默认的 auto 不只是扫描 import / export，还会在 nodenext / node16 和 react-jsx 等语境下结合更多上下文判断。

force 常用于消除“这明明是源码文件，为什么还被当成 script”这类困惑

如果项目完全不希望脚本级全局语义存在，这个选项会很直接。

参考信息

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