verbatimModuleSyntax是TypeScript 5.0引入的一个编译选项，它的核心作用是让编译输出中的模块语句与源码保持高度一致：源码里写了什么import和export，输出的JavaScript文件中就保留或擦除什么，完全不做“智能猜测”。这个看似简单的规则却改变了以往TypeScript自动擦除类型导入的行为，很多项目在开启它之后遇到了大量编译报错。本文将从原理、迁移步骤和常见问题三个方面，详细讲解如何平滑地把项目迁移到verbatimModuleSyntax之下。
一、verbatimModuleSyntax到底改变了什么
在没有这个配置之前，TypeScript编译器会分析每一条import语句，判断导入的标识符是否只被用作类型。如果某个导入在整个文件中只出现在类型位置，编译器会在输出时自动把这条导入整个删掉，这个过程是静默完成的，开发者通常感知不到。这种行为在大多数情况下没有问题，但在一些特定场景会出错，最典型的就是配合Babel、esbuild、swc这类单文件编译器使用时，这些工具无法像完整编译器那样做跨文件的类型信息分析，只能按照“单文件内可见的信息”来做擦除决策，一旦判断失误，输出的代码就会引用一个不存在的运行时绑定。
verbatimModuleSyntax的出现就是为了终结这种不确定性。它的语义非常直白：你在源码中写的模块语句，编译输出时原样保留；需要被擦除的内容，必须由你显式标记出来。具体来说有两条规则：第一，凡是没有标记为type的导入，一律视为运行时值导入，会被完整保留在输出中，即使它实际上只被用作类型；第二，凡是用import type语法标记的导入，一定会被完全擦除，即使其中某个成员恰好有运行时值。这两条规则叠加的效果是：编译器不再做任何推断，擦除行为完全由开发者控制。
这个选项实际上取代了之前的两个配置：importsNotUsedAsValues和preserveValueImports。前者控制“只用作类型的导入如何处理”，后者控制“疑似类型的值导入是否保留”。这两个旧选项的组合语义比较绕，而且无法覆盖所有边界情况，官方在5.0版本中把它们标记为废弃，推荐统一使用verbatimModuleSyntax。简单对照一下：preserveValueImports配合importsNotUsedAsValues等于preserve模式，而verbatimModuleSyntax等于更严格的preserve加上对import type的强制擦除。
二、迁移前的准备与tsconfig调整
迁移的第一步是确认TypeScript版本不低于5.0，可以通过项目目录下执行tsc --version来检查。接着打开项目根目录的tsconfig.json，在compilerOptions中添加verbatimModuleSyntax并设为true，同时删除已经废弃的importsNotUsedAsValues和preserveValueImports字段。一个典型的Windows项目配置文件路径是C:\Projects\my-app\tsconfig.json，用任意编辑器打开后修改compilerOptions节点即可。
{
"compilerOptions": {
"target": "ES2020",
"module": "ESNext",
"moduleResolution": "bundler",
"verbatimModuleSyntax": true,
"strict": true
}
}需要特别注意的是verbatimModuleSyntax与CommonJS输出的兼容问题。当module设置为commonjs时，开启verbatimModuleSyntax会要求所有导入必须显式区分默认导入和命名空间导入，因为默认导入在编译为require调用时的形式与ESM中的解构不同。此外，verbatimModuleSyntax会自动启用isolatedModules的检查行为，如果你之前开启了isolatedModules，可以保留也可以删除，二者并存不会冲突。修改配置后执行npx tsc --noEmit，把当前所有报错记录下来，这就是接下来迁移工作的任务清单。
三、常见报错与修复方案
开启后最常见的一类报错是“XXX is a type and must be imported using a type-only import”。意思是某个导入只被用作类型，但源码里没有加type标记，而编译器被要求把它原样保留到输出中，这会导致运行时引用一个类型声明。修复方式很简单，把对应的导入改写成import type形式。如果是混合导入，也就是同一个模块既有类型又有值，可以把类型部分拆出来单独写一行type导入。
import { SomeComponent, SomeComponentProps } from "./components";
// 改写为：值和类型分开导入
import { SomeComponent } from "./components";
import type { SomeComponentProps } from "./components";
// 内联type标记也可以，适合只改一两个成员的情况
import { SomeComponent, type SomeComponentProps } from "./components";第二类常见问题出现在re-export场景。使用export { Foo } from "./foo"重导出一个纯类型时，同样需要写成export type { Foo } from "./foo"。这个位置很容易被忽略，因为很多项目的入口文件会有一个index.ts做统一导出，如果里面重导出了大量接口和类型，报错会集中爆发在这里。第三类问题是动态导入和import()表达式不受影响，它们本身就是运行时行为，无需改动。
还有一个容易踩坑的点是Enum和普通类的处理。Enum在TypeScript中既是类型也是运行时值，即使你只在类型位置用了某个Enum，它依然有运行时代码，所以不能把它标记为type导入，否则编译输出中会缺少Enum的定义导致运行时报错。反过来，如果一个文件里同时存在值使用和类型使用，就不要加type标记，保持普通导入即可，verbatimModuleSyntax允许这样做，它只会原样保留。
四、迁移效率工具与注意事项
如果项目规模较大，手工修改会非常耗时。目前社区主流的迁移辅助工具是typescript-eslint中的consistent-type-imports规则，它可以在保存时自动把只用作类型的导入改写为import type形式。在项目的eslint配置文件（例如C:\Projects\my-app\.eslintrc.cjs）中启用该规则，配合编辑器的自动修复功能，大部分机械性修改都能自动完成。除此之外，官方提到的isolatedModules迁移工具和codemod脚本也能批量处理，建议先在独立分支上执行，跑通构建和测试后再合并。
迁移完成后建议做一次完整的构建验证，包括tsc编译、打包工具构建以及单元测试。特别要关注运行时行为是否变化：如果你之前依赖了TypeScript自动擦除类型导入的行为，那么现在某些导入会被保留，可能引入多余的副作用代码，例如某个原本被擦除的import语句会触发模块副作用执行。这种情况下要么给导入加type标记，要么确认副作用是预期的。总体来说，verbatimModuleSyntax带来的显式化虽然增加了少量书写成本，但它让类型导入和值导入的边界清晰可预测，对构建工具链的兼容性和输出稳定性都是明显的提升，值得在新项目中默认开启。
TypeScriptverbatimModuleSyntax模块编译配置修改时间：2026-09-14 07:57:39