====== 什么是 tsc ======
''tsc'' 就是 **TypeScript Compiler**,TypeScript 官方自带的命令行编译器。它随 ''typescript'' 包一起安装,负责两件事:按类型规则**检查**你的代码,并把 ''.ts'' / ''.tsx'' **编译**成 JavaScript。
要区分两个名字:官方的**包名**是 ''typescript'',''tsc'' 是它装出来的**命令名**(另一个命令 ''tsserver'' 是给编辑器用的语言服务)。
npm install -g typescript # 全局安装;项目里更推荐:npm i -D typescript
tsc -v # 查看版本
npx tsc # 没有全局安装也能跑
===== 一、它做哪三件事 =====
^ 能力 ^ 说明 ^ 相关选项 ^
| **类型检查** | 按 ''tsconfig.json'' 里的规则静态检查,报告编译期错误 | ''strict''、''noImplicitAny''、''strictNullChecks'' |
| **编译成 JS** | 把类型擦除,输出指定版本的 JavaScript | ''target''、''module''、''outDir'' |
| **产出附属文件** | 类型声明和调试用的映射文件 | ''declaration''、''sourceMap'' |
类型检查是它区别于普通转译工具的核心价值:报错发生在**编译时**,而不是等代码在浏览器或 Node 里跑起来才炸。
===== 二、常用命令 =====
tsc # 无参数:读当前目录的 tsconfig.json,全量编译
tsc --init # 生成一份 tsconfig.json 模板
tsc index.ts # 只编译指定文件(此时 tsconfig.json 会被忽略)
tsc -p ./tsconfig.json # 指定配置文件(-p / --project)
tsc -w # --watch,监听文件改动自动重编译
tsc --noEmit # 只做类型检查,不产出任何文件
tsc --build # 项目引用 / 增量构建(-b)
tsc --showConfig # 打印最终生效的完整配置
===== 三、常用编译选项 =====
写在 ''tsconfig.json'' 的 ''compilerOptions'' 里:
^ 选项 ^ 作用 ^
| ''target'' | 输出的 JS 版本,如 ''es5''、''es2022''、''esnext''。不配置时默认 ''es5''(TS 5.0 起,更早为 ''es3'') |
| ''module'' | 模块规范,如 ''commonjs''、''esnext''、''node16''、''nodenext'' |
| ''moduleResolution'' | 模块解析策略,建议 ''module'' 为 node16/nodenext 时配 ''node16'' |
| ''outDir'' | 产物目录,如 ''./dist'' |
| ''rootDir'' | 源码根目录,用来保持输出目录结构 |
| ''strict'' | 开启全部严格检查,**建议打开** |
| ''declaration'' | 额外生成 ''.d.ts'' 声明文件 |
| ''sourceMap'' | 生成 ''*.js.map'',方便断点调试 |
| ''noEmit'' | 不产出文件,只检查 |
| ''noEmitOnError'' | 有类型错误时不产出 JS(默认是**照样产出**) |
| ''skipLibCheck'' | 跳过对依赖 ''.d.ts'' 的检查,编译更快 |
| ''incremental'' | 增量编译,配合 ''.tsbuildinfo'' 缓存 |
默认扫描范围:''include'' 不写时相当于包含 tsconfig 所在目录下所有 ''.ts'' / ''.tsx'' / ''.d.ts'';''exclude'' 不写时默认排除 ''node_modules''、''bower_components''、''jspm_packages'' 和 ''outDir''。
===== 四、和打包器、转译器的分工 =====
这是最容易混淆的一点:**''tsc'' 不是打包器**。
- 它**逐文件转译**,不做 bundle 合并(除非 ''outFile'' 配 ''amd'' / ''system'' 这种老模块方案),没有 tree-shaking,不做压缩,也不处理 CSS、图片等非 JS 资源。
- **Vite、webpack 里的 ''.ts'' 通常不是 tsc 编译的**:它们用 esbuild / babel / swc 转译,速度快但**不做类型检查**,类型错误在开发服务器里可能一直不报。
- 所以现代项目里常见这样的分工:包管理器脚本里单独跑一条 ''tsc --noEmit'' 保证类型安全,真正的打包交给 Vite / webpack / Rollup。
// package.json 片段
{
"scripts": {
"typecheck": "tsc --noEmit",
"build": "tsc --noEmit && vite build"
}
}
===== 五、常见坑 =====
- **命令行指定了文件名,''tsconfig.json'' 就被忽略**:''tsc index.ts'' 不会读配置,会用默认的 ''target'' / ''module''。想要配置生效就用 ''tsc -p''。
- **有类型错误也会生成 JS**:''tsc'' 默认“报错归报错,产物照给”。CI 里想拦住,除了看退出码,最好把 ''noEmitOnError'' 打开。
- **没配 ''outDir'' 时产物会和源码混在一起**,''index.js'' 就生成在 ''index.ts'' 旁边。
- **''declaration'' 需要先有 ''outDir'' 之外的合理结构**,否则 ''.d.ts'' 也跟着源码散落;''declaration'' 与 ''allowJs'' 组合受限,''isolatedDeclarations'' 下要求显式标注导出类型。
- **''skipLibCheck'' 只跳过声明文件检查**,不减少你自己代码的错误,别指望它“让报错消失”。
- **纯类型项目**(比如只发布 ''.d.ts'')应该用 ''emitDeclarationOnly'' 而不是 ''declaration'' 加 ''noEmit'',后者会互相冲突。
===== 六、小结 =====
- ''tsc'' = TypeScript 官方编译器,装 ''typescript'' 包就有,命令名是 ''tsc''。
- 三件事:**类型检查**、**编译出 JS**、**产出 ''.d.ts'' 和 source map**。
- 无参数运行读 ''tsconfig.json'';只传文件名时**配置不生效**。
- 它**不负责打包**,Vite / webpack 里的转译也不做类型检查,所以项目里通常还要单独跑 ''tsc --noEmit''。
- 记住两个默认行为:不配 ''target'' 默认 ''es5'';有报错也照样产出 JS(要 ''noEmitOnError'' 才拦)。
相关:[[typescript:第十章_编译配置|编译配置(tsconfig)]]、[[typescript:什么是mts文件]]、[[typescript:module与cjs的区别|module 与 CommonJS 的区别]]、[[typescript:第十一章_类型声明文件|类型声明文件(.d.ts)]]、[[typescript:什么是use_strict|什么是 use strict]]