Skip to content
Lv1TypeScript进度 2 / 14

第 2 章:开发环境与第一个项目 ​

这一章只干一件事:让你亲手把 .ts 变成能跑的 .js,并且知道每一步在发生什么。


学习目标 ​

  • 装好 Node 与 TypeScript,建出一个最小可编译的项目
  • 分清 tsc 编译和 tsx 直接运行两种方式,知道各自适合什么场景
  • 看懂 tsconfig.json 里最先必须理解的六个配置项
  • 遇到"编译报错但 node 能跑""Cannot use import outside a module"这类问题时知道去哪查

2.1 准备 Node 环境 ​

TypeScript 的编译器本身是一个 npm 包,所以先要有 Node。

bash
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 建一个最小项目 ​

bash
mkdir ts-demo && cd ts-demo
npm init -y
npm install -D typescript
npx tsc --version

最后一行应该打印出版本号(类似 Version 5.x.x)。-D 表示装成开发依赖,生产环境运行时不需要它。

接着生成配置文件:

bash
npx tsc --init

这个命令会生成一个注释非常多的 tsconfig.json,初学者容易被上百行注释吓到。把它删掉,换成下面这份最小配置:

json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "commonjs",
    "moduleResolution": "node",
    "rootDir": "src",
    "outDir": "dist",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "sourceMap": true
  },
  "include": ["src"]
}

建好目录和入口文件:

bash
mkdir src
typescript
// 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)} 元`)

编译并运行:

bash
npx tsc
node dist/index.js

屏幕上出现 共 2 单,合计 54.90 元,第一个 TS 项目就跑通了。


2.3 六个必须看懂的编译选项 ​

tsconfig.json 里的选项几十个,初学阶段真正影响你日常的只有这几个。

target:编译成哪个年代的 JS ​

json
"target": "ES2022"

决定产物的语法级别。设成 ES5 时,async/await、可选链 ?.、?? 都会被降级成兼容写法;设成 ES2022 则基本原样保留。现代项目部署环境(浏览器、Node)都支持 ES2022,设高一点产物更干净、调试更直观。只有要兼容老浏览器时才往低调。

module 与 moduleResolution:模块怎么组织 ​

json
"module": "commonjs",
"moduleResolution": "node"
  • commonjs 产物用 require / module.exports,Node 直接能跑,最适合入门;
  • ESNext / NodeNext 产物用 import / export,是现在的主流写法。

两者必须搭配:module 是"产物长什么样",moduleResolution 是"编译器按什么规则找模块"。初学先用 commonjs + node,跑通之后再考虑切 ESM(2.6 节讲切换时会踩的坑)。

strict:类型检查的强度总开关 ​

json
"strict": true

这一项等于一次性打开一整套严格检查,主要包括:

子选项作用
strictNullChecksnull / undefined 不能随便赋给其他类型(最重要)
noImplicitAny推断不出类型时不允许悄悄变成 any
strictFunctionTypes函数参数类型检查更严格(逆变)
strictPropertyInitialization类字段必须在构造函数里初始化(第 9 章)
useUnknownInCatchVariablescatch 到的错误是 unknown 而不是 any

新项目一定要开。 关掉 strict 的 TS,几乎等于只保留了智能提示,第 1 章说的那些好处一大半没了。

rootDir 与 outDir:源文件和产物分开 ​

json
"rootDir": "src",
"outDir": "dist"

rootDir 告诉编译器"源码都在这下面",outDir 决定编译产物放哪。不设 outDir 时,.js 会直接生成在 .ts 旁边,源码目录很快被产物污染;不设 rootDir 时,编译器会自己推算公共父目录,偶尔算错会多套一层 src/ 目录。

include:哪些文件参与编译 ​

json
"include": ["src"]

只编译 src 下的文件。注意它和 files 的区别:files 是逐个列文件,include 用通配符。另外 exclude 可以排除 node_modules、dist(node_modules 默认已排除)。

skipLibCheck:跳过第三方声明的检查 ​

json
"skipLibCheck": true

第三方库的类型声明之间经常互相打架,检查它们既慢又容易报出你根本改不了的错误(错在别人的 .d.ts 里)。设成 true 只检查你自己的代码,是几乎所有项目的默认选择。


2.4 两种开发姿势:编译 vs 直接运行 ​

姿势一:tsc 编译,node 运行 ​

bash
npx tsc        # 有错就报错,没错就生成 dist/
node dist/index.js

这是最"正统"的方式,产物可控,适合生产构建。缺点是每次改代码都要重新编译再运行,循环慢。

加一个监听模式会好一些:

bash
npx tsc --watch

改一次存一次,tsc 自动增量编译,你只需要另开一个终端跑 node dist/index.js(或者用 nodemon 监听 dist)。

姿势二:tsx 直接跑 ​

bash
npm install -D tsx
npx tsx src/index.ts

tsx 用 esbuild 在内存里即时转译并执行,不产生 dist/ 目录,启动快,是本地开发和跑脚本最省事的方式。监听模式:

bash
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)。这套组合需要四处一起改:

json
// package.json
{
  "type": "module"
}
json
// 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:

typescript
// 在 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 这三个最容易混的类型到底怎么选。

👉 第 3 章:基础类型与类型推断

本文阅读--次|全站访问--次|访客--人