编译选项 - TypeScript 中文文档

使用 CLI

在本地运行 tsc 会编译由最近的 tsconfig.json 定义的项目；你也可以通过传入所需文件的 glob 来编译一组 TypeScript 文件。当在命令行中指定输入文件时，会忽略 tsconfig.json 文件。

sh
# Run a compile based on a backwards look through the fs for a tsconfig.json
tsc
# Emit JS for just the index.ts with the compiler defaults
tsc index.ts
# Emit JS for any .ts files in the folder src, with the default settings
tsc src/*.ts
# Emit files referenced in with the compiler settings from tsconfig.production.json
tsc --project tsconfig.production.json
# Emit d.ts files for a js file with showing compiler options which are booleans
tsc index.js --declaration --emitDeclarationOnly
# Emit a single .js file from two files via compiler options which take string arguments
tsc app.ts util.ts --target esnext --outfile index.js

编译器选项

如果你想进一步了解 tsconfig 中的编译器选项，请查看 TSConfig 参考

CLI 命令

标志	类型
`--all`	`boolean`
显示所有编译器选项。
`--help`	`boolean`
提供关于 CLI 帮助的本地信息。
`--ignoreConfig`	`boolean`
忽略找到的 tsconfig，并使用命令行选项和文件进行构建。
`--init`	`boolean`
初始化一个 TypeScript 项目并创建 tsconfig.json 文件。
`--listFilesOnly`	`boolean`
打印属于本次编译的文件名，然后停止处理。
`--locale`	`string`
设置 TypeScript 消息的语言。这不会影响输出。
`--project`	`string`
编译给定的项目，参数为配置文件路径或包含 tsconfig.json 的文件夹。
`--showConfig`	`boolean`
打印最终配置而不进行构建。
`--version`	`boolean`
打印编译器版本。

构建选项

标志	类型
`--build`	`boolean`
构建一个或多个项目及其依赖（如果已过期）
`--clean`	`boolean`
删除所有项目的输出。
`--dry`	`boolean`
显示将要构建（或在使用 --clean 时删除）的内容
`--force`	`boolean`
构建所有项目，包括看起来已是最新的项目。
`--verbose`	`boolean`
启用详细日志记录。

监视选项

标志	类型
`--excludeDirectories`	`list`
从监视进程中移除一组目录。
`--excludeFiles`	`list`
从监视模式的处理中移除一组文件。
`--fallbackPolling`	`fixedinterval`, `priorityinterval`, `dynamicpriority`, or `fixedchunksize`
指定当系统用尽原生文件监视器时，监视器应采用的方案。
`--synchronousWatchDirectory`	`boolean`
在不原生支持递归监视的平台上，同步调用回调并更新目录监视器的状态。
`--watch`	`boolean`
监视输入文件。
`--watchDirectory`	`usefsevents`, `fixedpollinginterval`, `dynamicprioritypolling`, or `fixedchunksizepolling`
指定在缺少递归文件监视功能的系统上如何监视目录。
`--watchFile`	`fixedpollinginterval`, `prioritypollinginterval`, `dynamicprioritypolling`, `fixedchunksizepolling`, `usefsevents`, or `usefseventsonparentdirectory`
指定 TypeScript 监视模式的工作方式。

编译器标志

标志	类型	默认值
`--allowArbitraryExtensions`	`boolean`	`false`
在存在声明文件的前提下，允许导入任意扩展名的文件。
`--allowImportingTsExtensions`	`boolean`	如果启用 `rewriteRelativeImportExtensions` 则为 `true`；否则为 `false`。
允许导入中包含 TypeScript 文件扩展名。
`--allowJs`	`boolean`	`false`，除非设置了 `checkJs`
允许 JavaScript 文件成为程序的一部分。使用 `checkJS` 选项以获取这些文件中的错误。
`--allowSyntheticDefaultImports`	`boolean`	如果启用了 `esModuleInterop`、`module` 为 `system`，或 `moduleResolution` 为 `bundler`，则为 `true`；否则为 `false`。
当模块没有默认导出时，允许 import x from y。
`--allowUmdGlobalAccess`	`boolean`	`false`
允许从模块访问 UMD 全局变量。
`--allowUnreachableCode`	`boolean`
禁用不可达代码的错误报告。
`--allowUnusedLabels`	`boolean`
禁用未使用标签的错误报告。
`--alwaysStrict`	`boolean`	如果启用 `strict` 则为 `true`；否则为 `false`。
确保始终输出 use strict。
`--assumeChangesOnlyAffectDirectDependencies`	`boolean`	`false`
使使用 `incremental` 和 `watch` 模式的项目在重新编译时，假定文件内的更改只影响直接依赖该文件的文件。
`--baseUrl`	`string`
指定用于解析裸说明符模块名称的基础目录。
`--charset`	`string`	`utf8`
已不再支持。在早期版本中，用于手动设置读取文件的文本编码。
`--checkJs`	`boolean`	`false`
在经类型检查的 JavaScript 文件中启用错误报告。
`--composite`	`boolean`	`false`
启用允许 TypeScript 项目与项目引用一起使用的约束。
`--customConditions`	`list`
解析导入时，在解析器特定默认值之外额外设置的条件。
`--declaration`	`boolean`	如果启用 `composite` 则为 `true`；否则为 `false`。
从项目中的 TypeScript 和 JavaScript 文件生成 .d.ts 文件。
`--declarationDir`	`string`
指定生成的声明文件的输出目录。
`--declarationMap`	`boolean`	`false`
为 d.ts 文件创建 sourcemap。
`--diagnostics`	`boolean`	`false`
在构建后输出编译器性能信息。
`--disableReferencedProjectLoad`	`boolean`	`false`
减少 TypeScript 自动加载的项目数量。
`--disableSizeLimit`	`boolean`	`false`
移除 TypeScript 语言服务器中 JavaScript 文件源代码总大小 20mb 的上限。
`--disableSolutionSearching`	`boolean`	`false`
在编辑时让项目不参与多项目引用检查。
`--disableSourceOfProjectReferenceRedirect`	`boolean`	`false`
在引用复合项目时，禁止优先使用源文件而非声明文件。
`--downlevelIteration`	`boolean`	`false`
为迭代生成更符合规范、但更冗长且性能更低的 JavaScript。
`--emitBOM`	`boolean`	`false`
在输出文件开头生成 UTF-8 字节顺序标记（BOM）。
`--emitDeclarationOnly`	`boolean`	`false`
仅输出 d.ts 文件，不输出 JavaScript 文件。
`--emitDecoratorMetadata`	`boolean`	`false`
为源文件中带装饰器的声明生成设计类型元数据。
`--erasableSyntaxOnly`	`boolean`	`false`
不允许使用不属于 ECMAScript 的运行时构造。
`--esModuleInterop`	`boolean`	如果 `module` 为 `node16`、`nodenext` 或 `preserve`，则为 `true`；否则为 `false`。
生成额外的 JavaScript，以便更轻松地导入 CommonJS 模块。这会为类型兼容性启用 `allowSyntheticDefaultImports`。
`--exactOptionalPropertyTypes`	`boolean`	`false`
按书写原样解释可选属性类型，而不是额外加上 `undefined`。
`--experimentalDecorators`	`boolean`	`false`
启用对 TC39 第 2 阶段草案装饰器的实验性支持。
`--explainFiles`	`boolean`	`false`
打印编译期间读取的文件，包括其被包含的原因。
`--extendedDiagnostics`	`boolean`	`false`
构建后输出更详细的编译器性能信息。
`--forceConsistentCasingInFileNames`	`boolean`	`true`
确保导入中的大小写正确。
`--generateCpuProfile`	`string`	`profile.cpuprofile`
生成编译器运行的 v8 CPU 配置文件，用于调试。
`--generateTrace`	`string`
生成事件追踪和类型列表。
`--importHelpers`	`boolean`	`false`
允许每个项目只从 tslib 导入一次辅助函数，而不是在每个文件中重复包含。
`--importsNotUsedAsValues`	`remove`、`preserve` 或 `error`	`remove`
指定仅用于类型的导入的生成与检查行为。
`--incremental`	`boolean`	如果启用了 `composite`，则为 `true`；否则为 `false`。
保存 .tsbuildinfo 文件，以支持项目的增量编译。
`--inlineSourceMap`	`boolean`	`false`
将源码映射文件嵌入生成的 JavaScript 中。
`--inlineSources`	`boolean`	`false`
将源代码包含在生成的 JavaScript 内的源码映射中。
`--isolatedDeclarations`	`boolean`	`false`
要求导出上有充分的类型标注，以便其他工具能轻松生成声明文件。
`--isolatedModules`	`boolean`	如果启用了 `verbatimModuleSyntax`，则为 `true`；否则为 `false`。
确保每个文件都能在不依赖其他导入的情况下安全转译。
`--jsx`	`preserve`、`react`、`react-native`、`react-jsx` 或 `react-jsxdev`
指定生成何种 JSX 代码。
`--jsxFactory`	`string`	`React.createElement`
指定以 React JSX 作为输出目标时使用的 JSX 工厂函数，例如 “React.createElement” 或 “h”。
`--jsxFragmentFactory`	`string`	`React.Fragment`
指定以 React JSX 作为输出目标时用于片段的 JSX Fragment 引用，例如 “React.Fragment” 或 “Fragment”。
`--jsxImportSource`	`string`	`react`
指定使用 `jsx: react-jsx*` 时用于导入 JSX 工厂函数的模块说明符。
`--keyofStringsOnly`	`boolean`	`false`
使 keyof 仅返回字符串，而不是字符串、数字或 symbol。旧版选项。
`--lib`	`list`
指定一组内置的库声明文件，用于描述目标运行时环境。
`--libReplacement`	`boolean`	`false`
允许用自定义文件替换默认的 `lib` 文件。
`--listEmittedFiles`	`boolean`	`false`
在编译后打印生成文件的名称。
`--listFiles`	`boolean`	`false`
打印编译期间读取的所有文件。
`--mapRoot`	`string`
指定调试器查找映射文件的位置，而不是生成文件所在的位置。
`--maxNodeModuleJsDepth`	`number`	`0`
指定检查来自 `node_modules` 的 JavaScript 文件时使用的最大文件夹深度。仅在启用 `allowJs` 时适用。
`--module`	`none`、`commonjs`、`amd`、`umd`、`system`、`es6`/`es2015`、`es2020`、`es2022`、`esnext`、`node16`、`node18`、`node20`、`nodenext` 或 `preserve`	如果 `target` 为 `ES5`，则为 `CommonJS`；否则为 `ES6`/`ES2015`。
指定生成何种模块代码。
`--moduleDetection`	`legacy`, `auto`, or `force`	"auto"：把带有 imports、exports、import.meta、jsx（配合 jsx: react-jsx）或 esm 格式（配合 module: node16+）的文件视为模块。
指定用于检测文件是脚本还是模块的方法。
`--moduleResolution`	`classic`, `node10`/`node`, `node16`, `nodenext`, or `bundler`	若 `module` 为 `CommonJS`，则为 `Node10`；若 `module` 为 `Node16`、`Node18` 或 `Node20`，则为 `Node16`；若 `module` 为 `NodeNext`，则为 `NodeNext`；若 `module` 为 `Preserve`，则为 `Bundler`；否则为 `Classic`。
指定 TypeScript 如何根据给定的模块说明符查找文件。
`--moduleSuffixes`	`list`
解析模块时要搜索的文件名后缀列表。
`--newLine`	`crlf` or `lf`	`lf`
设置输出文件时使用的换行符。
`--noCheck`	`boolean`	`false`
禁用完整的类型检查（只会报告关键的解析和输出错误）。
`--noEmit`	`boolean`	`false`
禁止输出编译产生的文件。
`--noEmitHelpers`	`boolean`	`false`
禁止在编译输出中生成像 `__extends` 这样的自定义辅助函数。
`--noEmitOnError`	`boolean`	`false`
如果报告了任何类型检查错误，则禁止输出文件。
`--noErrorTruncation`	`boolean`	`false`
禁止在错误消息中截断类型。
`--noFallthroughCasesInSwitch`	`boolean`	`false`
为 switch 语句中的贯穿（fallthrough）情况启用错误报告。
`--noImplicitAny`	`boolean`	`true` if `strict`; `false` otherwise.
为具有隐式 `any` 类型的表达式和声明启用错误报告。
`--noImplicitOverride`	`boolean`	`false`
确保派生类中被重写的成员用 override 修饰符标记。
`--noImplicitReturns`	`boolean`	`false`
为函数中没有显式返回的代码路径启用错误报告。
`--noImplicitThis`	`boolean`	`true` if `strict`; `false` otherwise.
当 `this` 被赋予类型 `any` 时启用错误报告。
`--noImplicitUseStrict`	`boolean`	`false`
禁止在输出的 JavaScript 文件中添加 'use strict' 指令。
`--noLib`	`boolean`	`false`
禁止包含任何库文件，包括默认的 lib.d.ts。
`--noPropertyAccessFromIndexSignature`	`boolean`	`false`
强制对使用索引类型声明的键使用索引访问器。
`--noResolve`	`boolean`	`false`
禁止 `import`、`require` 或 `<reference>` 增加 TypeScript 应添加到项目中的文件数量。
`--noStrictGenericChecks`	`boolean`	`false`
禁用对函数类型中泛型签名的严格检查。
`--noUncheckedIndexedAccess`	`boolean`	`false`
通过索引访问时，向类型添加 `undefined`。
`--noUncheckedSideEffectImports`	`boolean`	`true`
检查副作用导入。
`--noUnusedLocals`	`boolean`	`false`
当局部变量未被读取时启用错误报告。
`--noUnusedParameters`	`boolean`	`false`
当函数参数未被读取时抛出错误。
`--out`	`string`
已弃用的设置。请改用 `outFile`。
`--outDir`	`string`
为所有输出文件指定输出文件夹。
`--outFile`	`string`
指定一个文件，将所有输出打包到一个 JavaScript 文件中。如果 `declaration` 为 true，还会指定一个打包所有 .d.ts 输出的文件。
`--paths`	`object`
指定一组将导入重新映射到其他查找位置的条目。
`--plugins`	`list`
指定要包含的语言服务插件列表。
`--preserveConstEnums`	`boolean`	`true` if `isolatedModules`; `false` otherwise.
禁止在生成的代码中擦除 `const enum` 声明。
`--preserveSymlinks`	`boolean`	`false`
禁止将符号链接解析为其真实路径。这与 node 中的同名标志行为一致。
`--preserveValueImports`	`boolean`	`false`
在 JavaScript 输出中保留原本会被删除的未使用导入值。
`--preserveWatchOutput`	`boolean`	`false`
禁止在监视模式下清空控制台。
`--pretty`	`boolean`	`true`
在 TypeScript 的输出中启用颜色和格式，使编译器错误更易于阅读。
`--reactNamespace`	`string`	`React`
指定为 `createElement` 调用的对象。这仅在以 `react` JSX 输出为目标时适用。
`--removeComments`	`boolean`	`false`
禁止输出注释。
`--resolveJsonModule`	`boolean`	`false`
允许导入 .json 文件。
`--resolvePackageJsonExports`	`boolean`	当 `moduleResolution` 为 `node16`、`nodenext` 或 `bundler` 时为 `true`；否则为 `false`
解析包导入时使用 package.json 的 'exports' 字段。
`--resolvePackageJsonImports`	`boolean`	当 `moduleResolution` 为 `node16`、`nodenext` 或 `bundler` 时为 `true`；否则为 `false`
解析导入时使用 package.json 的 'imports' 字段。
`--rewriteRelativeImportExtensions`	`boolean`	`false`
将相对导入路径中的 `.ts`、`.tsx`、`.mts` 和 `.cts` 文件扩展名改写为输出文件中对应的 JavaScript 扩展名。
`--rootDir`	`string`	由输入文件列表计算得出。
指定源文件中的根文件夹。
`--rootDirs`	`list`	由输入文件列表计算得出。
解析模块时允许将多个文件夹视为一个。
`--skipDefaultLibCheck`	`boolean`	`false`
跳过对 TypeScript 自带的 .d.ts 文件的类型检查。
`--skipLibCheck`	`boolean`	`false`
跳过对所有 .d.ts 文件的类型检查。
`--sourceMap`	`boolean`	`false`
为输出的 JavaScript 文件生成源码映射文件。
`--sourceRoot`	`string`
指定调试器查找引用源代码的根路径。
`--stableTypeOrdering`	`boolean`	`false`
确保各次编译之间类型的排序稳定且确定。
`--stopBuildOnErrors`	`boolean`
当上游项目出错时跳过构建下游项目。
`--strict`	`boolean`	`true`
启用所有严格类型检查选项。
`--strictBindCallApply`	`boolean`	当 `strict` 开启时为 `true`；否则为 `false`。
检查 `bind`、`call` 和 `apply` 方法的参数是否与原函数匹配。
`--strictBuiltinIteratorReturn`	`boolean`	当 `strict` 开启时为 `true`；否则为 `false`。
内置迭代器实例化时，TReturn 类型为 undefined 而不是 any。
`--strictFunctionTypes`	`boolean`	当 `strict` 开启时为 `true`；否则为 `false`。
在赋值函数时，检查参数和返回值是否子类型兼容。
`--strictNullChecks`	`boolean`	当 `strict` 开启时为 `true`；否则为 `false`。
进行类型检查时，将 `null` 和 `undefined` 纳入考虑。
`--strictPropertyInitialization`	`boolean`	当 `strict` 开启时为 `true`；否则为 `false`。
检查已声明但未在构造函数中设置的类属性。
`--stripInternal`	`boolean`	`false`
禁止输出 JSDoc 注释中包含 `@internal` 的声明。
`--suppressExcessPropertyErrors`	`boolean`	`false`
禁止在创建对象字面量时报告多余属性错误。
`--suppressImplicitAnyIndexErrors`	`boolean`	`false`
对缺少索引签名的对象进行索引时，抑制 `noImplicitAny` 错误。
`--target`	`es3`, `es5`, `es6`/`es2015`, `es2016`, `es2017`, `es2018`, `es2019`, `es2020`, `es2021`, `es2022`, `es2023`, `es2024`, `es2025`, or `esnext`	若 `module` 为 `node20`，则为 `es2023`；若 `module` 为 `nodenext`，则为 `esnext`；否则为 `ES5`。
设置输出的 JavaScript 所使用的 JavaScript 语言版本，并包含兼容的库声明。
`--traceResolution`	`boolean`	`false`
记录 `moduleResolution` 过程中使用的路径。
`--tsBuildInfoFile`	`string`	`.tsbuildinfo`
用于存放 `.tsbuildinfo` 增量构建信息的文件。
`--typeRoots`	`list`
指定多个作用类似于 `./node_modules/@types` 的文件夹。
`--types`	`list`
指定无需在源文件中引用即可包含的类型包名称。
`--useDefineForClassFields`	`boolean`	若 `target` 为 `ES2022` 或更高版本（包括 `ESNext`），则为 `true`；否则为 `false`。
输出符合 ECMAScript 标准的类字段。
`--useUnknownInCatchVariables`	`boolean`	当 `strict` 开启时为 `true`；否则为 `false`。
默认将 catch 子句变量设为 `unknown` 而不是 `any`。
`--verbatimModuleSyntax`	`boolean`	`false`
不转换也不省略任何未标记为仅类型的导入或导出，确保它们按照 'module' 设置以输出文件的格式写出。

每个选项的完整说明都在 TSConfig 参考中。
了解如何使用 tsconfig.json 文件。
了解如何在 MSBuild 项目中工作。

tsc CLI 选项

使用 CLI

编译器选项

CLI 命令

构建选项

监视选项

编译器标志

相关内容