TypeScript verbatimModuleSyntax 详解
verbatimModuleSyntax 让 TS 的 import 与编译产物严格一一对应，消除类型导入的歧义与副作用陷阱。本文讲解它的行为、收益与启用时机。
开启 verbatimModuleSyntax 后，类型导入必须写 import type，TS 不再"智能"省略导入——你写的就是编译产物。它消除两类隐患：类型导入被误判为值导入（运行时找不到模块报错）与副作用导入被误删。现代 TS 项目建议开启。
默认行为的坑
TS 默认会"推断"导入是否为类型，自动从产物中删除纯类型导入：
import { SomeType } from './types';
import './polyfill'; // 副作用导入
// TS 推断 SomeType 只用于类型 → 产物中删除该 import
// 但 './polyfill' 如果被误判为空模块……副作用就丢了
启发式推断在边界场景出错：该删的没删（运行时找不存在的模块报错）、不该删的删了（副作用丢失）。
开启后的规则
{ "compilerOptions": { "verbatimModuleSyntax": true } }
// 类型必须显式声明
import type { User } from './types';
import { createUser } from './api'; // 值导入正常写
// 混合导入
import { type Config, loadConfig } from './config';
导入语义完全显式：import type 编译后必然消失，普通 import 必然保留——所见即所得。
防止副作用问题
import './setup'; // 明确保留——副作用导入安全
开启后工具链（打包器、运行时转译器如 esbuild/tsx）也能正确处理模块——它们没有 tsc 的类型信息，verbatimModuleSyntax 让它们在无类型信息时也能做出正确决策。这是该选项对现代工具链（tsx/esbuild/SWC）项目的关键价值。
启用时机
- 新项目：直接开（搭配 module: NodeNext 的现代配置）；
- 用运行时转译器（tsx/SWC/esbuild）的项目：强烈建议开——它们按字面处理模块；
- 存量项目：开启后按报错逐个改 import type，一次性成本、长期收益。
常见问题（FAQ）
Q：开启后报一堆错怎么办？
报错点都是"该写 import type 的地方"——IDE 有一键修复，大项目可用 codemod 批量处理。
Q：和 isolatedModules 的关系？
verbatimModuleSyntax 是 isolatedModules 的超集方向——更严格的字面模块语义。两者可同开。
Q：对 CommonJS 项目有意义吗？
有——ESM/CJS 混用边界（import 一个 CJS 包）的行为也更可预测。现代配置一律建议开启。
参考文档
本文依据公开文档整理，示例需按项目依赖版本验证；不将文档中的性能描述视为本项目实测结果。
