01 起步与工具链

01 起步与工具链

本页回答两个问题：这段 TypeScript 代码怎么跑起来，以及出了问题用什么命令查。

基线：TypeScript 6.0.3，Node.js v24.20.0。所有命令输出均为实测结果。

安装

1
2
3

npm install -D typescript        # 项目内（推荐，版本随项目锁定）
npm install -g typescript        # 全局（只为了有个 tsc 应急）
npx tsc --version                # 检查版本

⚠️ 6.0 重大变化：types 默认值变为 []。6.0 之前 node_modules/@types 下所有包会被自动加载，现在不会了。升级后如果突然报 Cannot find name 'process'，就是这个原因：

1	{ "compilerOptions": { "types": ["node"] } }

五种运行方式

TypeScript 不能直接被任何运行时执行。类型要么被擦除，要么被转换成 JS。「哪种方式」只影响开发体验，不影响语言语义。

• ① tsc 编译后运行
• ② Node 原生运行 🆕
• ③ tsx / ts-node
• ④ 打包器 / 框架
• ⑤ 浏览器 / 在线

1
2

npx tsc                      # 读 tsconfig.json 编译到 outDir
node dist/index.js           # 运行产物

1

node index.ts

1

node --experimental-transform-types index.ts

1
2
3

npx tsx index.ts                 # 推荐：esbuild 驱动，快，ESM 友好 🔥
npx tsx watch index.ts           # 监听重启
npx ts-node index.ts             # 老牌，可做完整类型检查

tsc 命令行速查

文件与项目

6.0 新增 TS5112：如果目录里有 tsconfig.json，同时又在命令行传了文件名，tsc 会报错而不是忽略配置：

1 2	error TS5112: tsconfig.json is present but will not be loaded if files are specified on commandline. Use '--ignoreConfig' to skip this error.

用意是消除「命令行参数悄悄绕过项目配置」这个长期困惑源。加 --ignoreConfig 即可恢复旧行为。

检查与产物

目标与模块

诊断（本页最有价值的部分）

排查「类型为什么是这个」的标准动作：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# 1. 报错信息被截断了，看不到完整类型
npx tsc --noEmit --noErrorTruncation

# 2. 不知道某个文件为什么被编译进来（幽灵文件、多余 @types）
npx tsc --noEmit --explainFiles | head -50

# 3. 某个 import 解析到了错误的位置
npx tsc --noEmit --traceResolution 2>&1 | grep -A5 "some-package"

# 4. 编译慢，想知道瓶颈
npx tsc --noEmit --extendedDiagnostics

--extendedDiagnostics 输出解读：

💭 大多数「tsc 好慢」的根因是 Instantiations 数量过大，也就是泛型/条件类型被反复实例化。缓解手段见 17 编译器与性能。

错误抑制指令

三者的语义完全不同，选错的代价很大。

1
2
3
4
5
6
7

// ✅ 推荐：不仅抑制，还保证「这里确实该报错」
// @ts-expect-error 故意传错类型，验证运行时兜底
doSomething("wrong type");

// 🛑 不推荐：写错了也发现不了
// @ts-ignore
doSomething("wrong type");

@ts-expect-error 的额外好处：当上游修复后它会提示你删除。因为不再报错时，它会变成「未使用的 expect-error」提示，形成自我清理。💭

作用域：这三个指令作用于下一行（@ts-nocheck / @ts-check 作用于整个文件，且必须写在文件顶部注释区）。

迁移期开关（渐进引入类型）

老 JS 项目不必一次性改完。按这个顺序推进，每一步都可运行：

1
2
3
4
5
6
7
8

// 阶段 1~2 的典型配置
{
  "compilerOptions": {
    "allowJs": true,
    "checkJs": true,          // 配合 per-file 的 // @ts-check
    "noEmit": true             // 先只检查，产物仍交给原有工具链
  }
}

⚠️ 6.0 迁移注意：由于 strict 默认变为 true，从旧版本升级的项目第一次跑 tsc 可能一次性爆出大量错误。务实做法是先显式固定：

1	{ "compilerOptions": { "strict": false } } // 先恢复旧行为，再逐项开启

然后按 noImplicitAny → strictNullChecks → 其余 的顺序逐项打开。详见 15 从 JS 迁移。

编辑器：tsserver

VS Code 等编辑器用的不是 tsc，而是 tsserver（语言服务）。二者共享同一套类型系统，但可能使用不同的配置。

排查命令（VS Code）：

1
2

// .vscode/settings.json：强制使用项目内的 TS 版本
{ "typescript.tsdk": "node_modules/typescript/lib" }

💡 训练肌肉记忆：编辑器红了先 Restart TS Server，能解决相当一部分「明明没问题却报错」。

常见启动问题速查

一句话总结