[!info] related notes

• 所属 MOC: TypeScript MOC
• 配置入口: tsconfig 使用详解
• 并列概念: TypeScript 中的 import type 与普通 import, TypeScript 中的 module, TypeScript 中的 isolatedModules
• 已替代旧项: TypeScript 中的 importsNotUsedAsValues（已废弃）, TypeScript 中的 preserveValueImports（已废弃）

TypeScript 中的 verbatimModuleSyntax

一句话定义

verbatimModuleSyntax 让 TypeScript 更接近“你写什么模块语法，就按什么语法保留”。

核心机制 / 工作原理

在这个选项开启后，规则会明显变简单：

• 带 type 的 import / export 会在 emit 时被擦除
• 不带 type 的 import / export 会被原样保留

也就是：

type 修饰符决定哪些只是类型依赖，其他模块语法按字面保留。

这也是官方强调的“所写即所得”思路。

最小例子 / 最小场景

{
  "compilerOptions": {
    "verbatimModuleSyntax": true
  }
}

配合：

import { createApp } from "vue";
import type { User } from "./user";

通常会表现成：

• createApp 相关导入保留
• User 的类型导入被擦除

边界与易混淆点

它会让 import type 变得更重要

如果你没有明确写 type，TypeScript 更倾向于把这条导入视为真正的模块语法保留下来。

所以这个选项常和：

• import type

一起理解。

它会更早暴露模块配置不一致

官方文档特别指出，在这个选项下，TypeScript 不再把 ESM 语法静默改写成 require 风格。

这意味着如果你当前文件和模块配置本质上是 CommonJS 语境，却写了 ESM 风格语法，问题会更早暴露出来。

它也是旧导入 emit 选项的收敛终点

当前官方文档已经把下面两个旧选项都标成：

• Deprecated in favor of verbatimModuleSyntax

也就是：

• TypeScript 中的 importsNotUsedAsValues（已废弃）
• TypeScript 中的 preserveValueImports（已废弃）

它主要简化的是 emit 语义，不是模块解析算法

它不负责决定：

• 模块怎么找
• package exports 怎么选

这些仍然更接近：

• module
• moduleResolution

参考信息

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