阮一峰《TypeScript 教程》学习笔记——tsc 命令
1. 一段话总结
tsc是TypeScript官方命令行编译器，核心功能是检查代码类型与将TS编译为JavaScript；默认优先使用当前目录的tsconfig.json配置，但命令行参数可覆盖配置；基本用法包括编译指定文件（如tsc index.ts）、批量编译目录文件（如tsc src/*.ts）、指定配置文件（如tsc --project tsconfig.prod.json）；关键命令行参数涵盖配置生成（–init，生成tsconfig.json）、观察模式（–watch，文件修改自动重编译）、仅类型检查（–noEmit，不生成JS产物）、仅生成类型声明（–emitDeclarationOnly）等，且大部分参数与tsconfig.json属性一一对应，可灵活控制编译行为。
2. 思维导图
3. 详细总结
一、tsc命令简介
- 定义
tsc（TypeScript Compiler）是TypeScript官方提供的命令行编译器，是TS项目编译与类型检查的核心工具。 - 核心作用
- 对TS代码进行类型检查，检测类型错误；
- 将TS代码编译为JavaScript代码，支持指定输出JS版本、模块格式等；
- 生成类型声明文件（.d.ts），供其他项目引用类型。
- 配置优先级
- 默认优先读取当前目录的
tsconfig.json配置； - 命令行参数可覆盖
tsconfig.json中的同名属性（如命令行--strict true会覆盖配置文件中strict: false）。
- 默认优先读取当前目录的
二、tsc基本用法（按场景分类）
| 用法场景 | 命令示例 | 说明 |
|---|---|---|
| 默认编译（用tsconfig.json） | tsc | 从当前目录向上查找tsconfig.json，按配置编译所有匹配文件 |
| 编译单个文件 | tsc index.ts | 仅编译index.ts，忽略tsconfig.json的files/include配置 |
| 编译目录批量文件 | tsc src/*.ts | 编译src目录下所有.ts文件，支持通配符*（匹配单层文件）、**（匹配多层目录） |
| 指定配置文件 | tsc --project tsconfig.prod.json | 或简写tsc -p ./config（指定配置文件所在目录），优先使用该配置 |
| 仅类型检查（不生成产物） | tsc --noEmit | 执行类型检查，但不生成任何JS或.d.ts文件 |
| 生成类型声明文件 | tsc index.ts --declaration --emitDeclarationOnly | 仅生成index.d.ts类型声明文件，不输出JS文件 |
| 多文件合并编译 | tsc app.ts util.ts --outfile index.js | 仅支持module为None/System/AMD的模块，合并为单个JS文件 |
三、核心命令行参数（按功能分类，关键参数加粗）
| 功能分类 | 参数名称 | 核心作用 | 关键说明 |
|---|---|---|---|
| 配置生成与指定 | –init | 在当前目录生成全新的tsconfig.json文件 | 包含预设配置（带注释），无需手动编写基础配置 |
| –project/-p | 指定tsconfig.json文件或其所在目录 | 示例：tsc -p ./config（使用config目录下的tsconfig.json） | |
| –showConfig | 在终端输出最终生效的编译配置（不执行编译） | 用于调试配置，查看命令行参数与配置文件的合并结果 | |
| 编译输出控制 | –outDir | 指定编译产物（JS/.d.ts）的存放目录 | 示例：tsc --outDir ./dist（产物输出到dist目录） |
| –outFile | 将所有非模块文件合并为单个指定JS文件 | 仅支持module为None/System/AMD，不支持CommonJS/ES模块 | |
| –declaration | 为每个.ts文件生成对应的.d.ts类型声明文件 | 需配合--declarationDir指定声明文件目录（如--declarationDir ./types） | |
| –emitDeclarationOnly | 仅生成.d.ts文件，不输出JS文件 | 适用于仅需提供类型声明的场景（如发布TS库时） | |
| –removeComments | 从编译产物中移除所有代码注释 | 默认保留注释，开启后产物无注释 | |
| 类型检查控制 | –noEmit | 仅执行类型检查，不生成任何编译产物（JS/.d.ts） | 适用于快速校验代码类型正确性，不需要产物的场景 |
| –strict | 开启所有严格类型检查（等价开启7个子选项，如--strictNullChecks） | 可单独关闭子选项（如tsc --strict --alwaysStrict false） | |
| –checkJs | 对JS文件进行类型检查（自动开启--allowJs） | 等价于在JS文件头部添加// @ts-check注释 | |
| –noImplicitAny | 当变量/参数被隐式推断为any类型时，编译报错 | --strict开启时默认生效，强制显式声明类型 | |
| 观察与增量编译 | –watch/-w | 进入观察模式，文件修改后自动重新编译 | 适用于开发阶段，无需手动重复执行编译命令 |
| –build | 启用增量编译，仅重新编译修改过的文件及依赖 | 需配合tsconfig.json的composite: true，加快大型项目编译速度 | |
| –incremental | 生成tsbuildinfo文件，记录编译状态，实现增量构建 | 与--build配合使用，进一步优化编译效率 | |
| 模块与解析 | –module | 指定编译产物的模块格式（如commonjs/esnext/node16） | 默认值与--target关联（如target=es5时默认commonjs） |
| –moduleResolution | 指定模块定位算法（如node/node16/classic） | 默认值与--module关联（如module=node16时默认node16） | |
| –resolveJsonModule | 允许在TS代码中使用import命令加载JSON文件 | 需配合--allowJs，加载后JSON文件类型会被自动推断 |
4. 关键问题
问题1：tsc命令的基本用法涵盖哪些核心场景？如何指定非默认的tsconfig.json文件？
答案：
tsc命令的基本用法涵盖5个核心场景，具体如下：
- 默认编译场景：执行
tsc，从当前目录向上递归查找tsconfig.json，按配置编译所有匹配文件（如include指定的文件）； - 单文件/批量文件编译场景：执行
tsc index.ts（单文件）或tsc src/*.ts（src目录所有.ts文件），忽略tsconfig.json的files/include配置； - 仅类型检查场景：执行
tsc --noEmit，仅检测代码类型错误，不生成任何JS或.d.ts产物； - 生成类型声明场景：执行
tsc index.ts --declaration --emitDeclarationOnly，仅生成index.d.ts类型声明文件，不输出JS； - 多文件合并场景：执行
tsc app.ts util.ts --outfile index.js，将多个文件合并为单个JS（仅支持module为None/System/AMD）。
指定非默认tsconfig.json文件的方式：使用**–project（简写-p）参数**，后跟配置文件路径或其所在目录。示例：
- 指定配置文件：
tsc --project tsconfig.production.json； - 指定配置目录（目录下需有tsconfig.json）：
tsc -p ./config（使用config目录的配置）。
问题2：tsc命令行参数与tsconfig.json属性的关系是什么？如何体现“命令行参数覆盖配置文件”的规则？
答案：
两者的核心关系是**“大部分tsc命令行参数与tsconfig.json的属性一一对应”（如--outDir对应compilerOptions.outDir，--strict对应compilerOptions.strict），且命令行参数的优先级高于tsconfig.json**，即当两者存在同名配置时，命令行参数会覆盖配置文件的设置。
“覆盖规则”的具体体现：
- 若
tsconfig.json中compilerOptions.outDir = "./build"，但命令行执行tsc --outDir ./dist，最终产物会输出到./dist（命令行参数覆盖配置）； - 若
tsconfig.json中compilerOptions.strict = false，但命令行执行tsc --strict true，最终会开启严格类型检查（命令行参数覆盖配置）； - 特殊场景：若命令行指定了编译文件（如
tsc index.ts），会直接忽略tsconfig.json中files/include/exclude的文件匹配规则，仅编译指定文件。
例外：部分参数仅存在于命令行（如--init生成配置文件、--watch观察模式、--showConfig输出配置），无对应的tsconfig.json属性。
问题3：--noEmit、--emitDeclarationOnly、--watch三个参数的核心作用、适用场景及关键限制分别是什么？
答案：
三个参数的核心差异体现在“是否生成产物”“生成何种产物”“是否自动重编译”，具体如下表：
| 参数名称 | 核心作用 | 适用场景 | 关键限制 |
|---|---|---|---|
| –noEmit | 仅执行类型检查，不生成任何编译产物（JS/.d.ts） | 1. 开发中快速校验代码类型正确性； 2. 代码评审前的类型合规检查 | 无产物输出，仅用于类型校验，无法获取可执行JS |
| –emitDeclarationOnly | 仅生成.d.ts类型声明文件，不输出JS文件 | 1. 发布TS库时，仅需提供类型声明（JS由其他工具编译）； 2. 为JS项目补全类型声明 | 需配合--declaration参数使用，否则无法生成.d.ts |
| –watch/-w | 进入观察模式，文件修改后自动重新编译 | 1. 开发阶段实时预览编译结果； 2. 避免手动重复执行 tsc命令 | 仅在开发环境使用，生产环境编译需手动执行tsc（避免意外重编译） |
示例：
- 开发中校验类型：
tsc --noEmit； - 发布TS库：
tsc --declaration --emitDeclarationOnly --outDir ./types； - 开发实时编译：
tsc --watch --outDir ./dist。