第 2 章:开发环境与第一个项目
这一章只干一件事:让你亲手把
.ts变成能跑的.js,并且知道每一步在发生什么。
学习目标
- 装好 Node 与 TypeScript,建出一个最小可编译的项目
- 分清
tsc编译和tsx直接运行两种方式,知道各自适合什么场景 - 看懂
tsconfig.json里最先必须理解的六个配置项 - 遇到"编译报错但 node 能跑""Cannot use import outside a module"这类问题时知道去哪查
2.1 准备 Node 环境
TypeScript 的编译器本身是一个 npm 包,所以先要有 Node。
node -v
npm -v能打印出版本号就说明装好了。建议用 Node 当前的 LTS 版本,太老的版本(比如 14 以下)在模块解析和 fetch 支持上会给你添麻烦。装 Node 推荐用 nvm(macOS / Linux)或 nvm-windows,方便多版本切换;直接装官方安装包也能用,只是升级麻烦。
版本建议:Node 18 以上。Node 18 开始内置
fetch,第 1 章那个fetch('/api/user')的例子不用装任何依赖就能跑。
2.2 建一个最小项目
mkdir ts-demo && cd ts-demo
npm init -y
npm install -D typescript
npx tsc --version最后一行应该打印出版本号(类似 Version 5.x.x)。-D 表示装成开发依赖,生产环境运行时不需要它。
接着生成配置文件:
npx tsc --init这个命令会生成一个注释非常多的 tsconfig.json,初学者容易被上百行注释吓到。把它删掉,换成下面这份最小配置:
{
"compilerOptions": {
"target": "ES2022",
"module": "commonjs",
"moduleResolution": "node",
"rootDir": "src",
"outDir": "dist",
"strict": true,
"esModuleInterop": true,
"skipLibCheck": true,
"sourceMap": true
},
"include": ["src"]
}建好目录和入口文件:
mkdir src// src/index.ts
interface Order {
id: number
amount: number
}
const orders: Order[] = [
{ id: 1, amount: 19.9 },
{ id: 2, amount: 35 }
]
const total = orders.reduce((sum, order) => sum + order.amount, 0)
console.log(`共 ${orders.length} 单,合计 ${total.toFixed(2)} 元`)编译并运行:
npx tsc
node dist/index.js屏幕上出现 共 2 单,合计 54.90 元,第一个 TS 项目就跑通了。
2.3 六个必须看懂的编译选项
tsconfig.json 里的选项几十个,初学阶段真正影响你日常的只有这几个。
target:编译成哪个年代的 JS
"target": "ES2022"决定产物的语法级别。设成 ES5 时,async/await、可选链 ?.、?? 都会被降级成兼容写法;设成 ES2022 则基本原样保留。现代项目部署环境(浏览器、Node)都支持 ES2022,设高一点产物更干净、调试更直观。只有要兼容老浏览器时才往低调。
module 与 moduleResolution:模块怎么组织
"module": "commonjs",
"moduleResolution": "node"commonjs产物用require/module.exports,Node 直接能跑,最适合入门;ESNext/NodeNext产物用import/export,是现在的主流写法。
两者必须搭配:module 是"产物长什么样",moduleResolution 是"编译器按什么规则找模块"。初学先用 commonjs + node,跑通之后再考虑切 ESM(2.6 节讲切换时会踩的坑)。
strict:类型检查的强度总开关
"strict": true这一项等于一次性打开一整套严格检查,主要包括:
| 子选项 | 作用 |
|---|---|
strictNullChecks | null / undefined 不能随便赋给其他类型(最重要) |
noImplicitAny | 推断不出类型时不允许悄悄变成 any |
strictFunctionTypes | 函数参数类型检查更严格(逆变) |
strictPropertyInitialization | 类字段必须在构造函数里初始化(第 9 章) |
useUnknownInCatchVariables | catch 到的错误是 unknown 而不是 any |
新项目一定要开。 关掉 strict 的 TS,几乎等于只保留了智能提示,第 1 章说的那些好处一大半没了。
rootDir 与 outDir:源文件和产物分开
"rootDir": "src",
"outDir": "dist"rootDir 告诉编译器"源码都在这下面",outDir 决定编译产物放哪。不设 outDir 时,.js 会直接生成在 .ts 旁边,源码目录很快被产物污染;不设 rootDir 时,编译器会自己推算公共父目录,偶尔算错会多套一层 src/ 目录。
include:哪些文件参与编译
"include": ["src"]只编译 src 下的文件。注意它和 files 的区别:files 是逐个列文件,include 用通配符。另外 exclude 可以排除 node_modules、dist(node_modules 默认已排除)。
skipLibCheck:跳过第三方声明的检查
"skipLibCheck": true第三方库的类型声明之间经常互相打架,检查它们既慢又容易报出你根本改不了的错误(错在别人的 .d.ts 里)。设成 true 只检查你自己的代码,是几乎所有项目的默认选择。
2.4 两种开发姿势:编译 vs 直接运行
姿势一:tsc 编译,node 运行
npx tsc # 有错就报错,没错就生成 dist/
node dist/index.js这是最"正统"的方式,产物可控,适合生产构建。缺点是每次改代码都要重新编译再运行,循环慢。
加一个监听模式会好一些:
npx tsc --watch改一次存一次,tsc 自动增量编译,你只需要另开一个终端跑 node dist/index.js(或者用 nodemon 监听 dist)。
姿势二:tsx 直接跑
npm install -D tsx
npx tsx src/index.tstsx 用 esbuild 在内存里即时转译并执行,不产生 dist/ 目录,启动快,是本地开发和跑脚本最省事的方式。监听模式:
npx tsx watch src/index.ts| 方式 | 产物 | 启动速度 | 适合 |
|---|---|---|---|
tsc + node | 有 dist/ | 慢(要编译) | 生产构建、需要产物检查 |
tsx | 无 | 快 | 本地开发、一次性脚本 |
ts-node | 无 | 较慢 | 老项目常见,功能与 tsx 类似 |
tsx不做类型检查,只做转译。也就是说类型错误它不会拦你——类型检查交给编辑器或tsc --noEmit。把npx tsc --noEmit放进 CI 是很常见的做法。
2.5 编辑器为什么能提前报错
你在 VS Code 里敲错类型,还没编译就出现红线,是因为编辑器内置了 TypeScript 语言服务(tsserver),它在后台按 tsconfig.json 实时分析。这带来三个必须会用的能力:
| 操作 | 快捷键(VS Code) | 用途 |
|---|---|---|
| 跳转到定义 | F12 / Ctrl+点击 | 看某个类型到底在哪定义的 |
| 查找所有引用 | Shift+F12 | 改字段前先看谁在用 |
| 悬停看类型 | 鼠标停留 | 不确定一个变量是什么类型时,直接看提示 |
第 13 章会专门讲怎么用这几个能力读陌生项目。
如果你用 WebStorm、Vim、Neovim,同样有 tsserver 集成,快捷键不同而已。
2.6 切换到 ESM 时会踩的坑
很多新项目直接用 "type": "module"(ESM)。这套组合需要四处一起改:
// package.json
{
"type": "module"
}// tsconfig.json
{
"compilerOptions": {
"target": "ES2022",
"module": "NodeNext",
"moduleResolution": "NodeNext",
"rootDir": "src",
"outDir": "dist",
"strict": true
}
}改完会遇到两个高频错误:
错误一:Cannot use import statement outside a module → 运行时把 ESM 语法当成了 CommonJS。检查 package.json 里有没有 "type": "module",或者产物后缀是不是 .mjs。
错误二:Relative import paths need explicit file extensions → NodeNext 模式下,相对导入必须写扩展名,而且要写编译后的 .js,不是 .ts:
// 在 src/index.ts 里
import { formatPrice } from './format.js' // 正确,哪怕源文件叫 format.ts
import { formatPrice } from './format' // NodeNext 下报错这个规则第一次见很别扭,但它是 ESM 的原生要求:Node 运行时按路径找文件,不知道 .ts 的存在。理解了这一点就不会再觉得是 TS 在刁难你。
2.7 常见误区
误区一:类型报错,但 node 照样能跑,所以报错可以无视。 → 能跑是因为类型在编译时已被擦除,运行时根本不看类型。类型报错意味着"你的代码和你声明的类型不自洽",现在不炸只是恰好没走到那条路。第 1 章说过,TS 的价值就在这个提前量。
误区二:outDir 不设也没关系。 → 不设的话,编译产物会和源码混在一起,git status 里一堆 .js,还容易把旧产物提交上去。至少加一行 .gitignore:node_modules/、dist/。
误区三:tsx 能跑就说明代码没问题。 → tsx 只转译不检查类型。本地跑通、CI 里 tsc --noEmit 报出 30 个错,是新手最常遇到的"打脸"场景。养成习惯:提交前跑一次 npx tsc --noEmit。
误区四:把 strict 关掉,先让项目跑起来,以后再开。 → "以后"通常不会来。项目一旦在非严格模式下长起来,再打开 strictNullChecks 会一次性冒出几百个错误,没人愿意改。新项目第一天就开,代价最小。
本章小结
| 要点 | 说明 |
|---|---|
| 装环境 | Node 18+,npm i -D typescript,npx tsc --version 验证 |
| 最小配置 | target ES2022、module commonjs、rootDir src、outDir dist、strict true |
| 两种运行方式 | tsc + node 适合生产;tsx 适合开发与脚本 |
strict 必开 | 关掉后 TS 只剩智能提示,失去大部分价值 |
| ESM 后缀规则 | NodeNext 下相对导入写 .js,不是 .ts |
| 提交前检查 | npx tsc --noEmit 不产生产物,只做类型检查 |
下一章预告
环境跑通了,接下来正式学类型。下一章从最基础的
string、number讲到数组、元组,再讲清any、unknown、never这三个最容易混的类型到底怎么选。