1.3 安装配置与首个程序

1.3 安装配置与首个程序

这节是地图里"基础环境"的最后一站，把前面两节说的契约真正落到你的机器上。我们走一条最朴素的路径：Node + tsc + 一个 tsconfig + 一个编辑器，不引入打包器、不引入框架，先让最小的类型检查跑起来。等这道链路通了，后面所有章节的代码你都能本地验证。

先确认 Node 与包管理器

TypeScript 编译器本身是 Node 上的一个包，不需要浏览器。打开终端：

# 确认 Node 已装（建议 18 以上）
node -v
npm -v
# 全局安装编译器（也可项目内局部装）
npm install -g typescript
# 验证版本
tsc -v
​

输入输出：命令执行后终端打印 Version 5.x.x 即成功。如果报"command not found"，说明 Node 没进 PATH，先修 Node 安装再回来。

初始化一份 tsconfig

tsconfig 是类型系统的"总开关"，所有严格度、模块解析规则都在这。先建项目目录：

mkdir ts-demo && cd ts-demo
npm init -y
npx tsc --init
​

tsc --init 会生成一份带全部注释的 tsconfig.json。我们精简成实战常用的最小集：

// tsconfig.json —— 最小可跑、且开启基础严格的配置
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "CommonJS",
    "moduleResolution": "node",
    "strict": true,
    "noImplicitAny": true,
    "strictNullChecks": true,
    "outDir": "./dist",
    "rootDir": "./src",
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}
​

背景：新手常被默认 tsconfig 的上百行注释劝退。操作：砍到上面这版，每个字段都是实战里立刻用得到的。结果：一份清晰、严格、可演进的基线。解读：strict: true 一次性打开 7 个检查子项，noImplicitAny/strictNullChecks 都在其中；单独列出是为可读性。skipLibCheck 跳过第三方 .d.ts 内部检查，能显著提速老项目。变式：前端项目把 module 换成 ESNext、moduleResolution 换成 bundler。

写第一个带契约的程序

// src/index.ts
interface User {
  id: number;
  name: string;
  role: "admin" | "guest";
}
function greet(u: User): string {
  return `你好 ${u.name}，角色是 ${u.role}`;
}
const me: User = { id: 1, name: "张三", role: "admin" };
console.log(greet(me));
// 故意写错，看编译器如何拦
const wrong: User = { id: 2, name: "李四" }; // 报错：缺少 role 属性
​

编译运行：

# 只做类型检查，不输出
npx tsc --noEmit
# 编译并运行（需先 npm i -g ts-node 或编译后 node）
npx tsc
node dist/index.js
​

输入输出：tsc --noEmit 会报 Property 'role' is missing，这就是契约在起作用；修正后 node dist/index.js 打印"你好 张三，角色是 admin"。

编辑器实时反馈：VS Code 四件套

编辑器是契约的"实时显示牌"。VS Code 内置 TS 支持，装上后保存即标红，不用每次切终端。

// .vscode/settings.json —— 让编辑器用项目里的 tsc 而非自带版本
{
  "typescript.tsdk": "node_modules/typescript/lib",
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
    "source.fixAll.ts": true
  }
}
​

这张图给出"从源码到运行"的整条流水线，方便你定位每次改动落在哪个环节：

常见安装坑

# 坑1：全局和项目版本不一致，导致编辑器与命令行检查结果不同
# 解决：项目内局部安装，命令行用 npx tsc
npm install -D typescript

# 坑2：改了 tsconfig 不生效
# 解决：确认文件在 include 范围内，且没被上层 tsconfig 的 extends 覆盖

# 坑3：node 跑 .ts 直接报语法错误
# 解决：node 不认 TS，必须先 tsc 编译，或用 ts-node / tsx 直接跑
npx tsx src/index.ts
​

工程取舍：全局装还是局部装

个人练手全局装最省事。团队协作务必局部装（devDependencies 里锁版本），并在 package.json 加脚本：

// package.json 片段
{
  "scripts": {
    "typecheck": "tsc --noEmit",
    "build": "tsc"
  }
}
​

局部装保证每个人、每次 CI 用的编译器版本一致，避免"我机器上是好的"这种扯皮。契约统一口径，比编译器新特性更重要。

本节要点回顾

• 链路：Node 装 tsc → tsconfig 定严格度 → 写 .ts → tsc 检查/编译 → node 运行
• strict: true 是实战基线，新项目直接开
• 编辑器用项目内 tsc 做实时反馈，保存即标红
• 团队项目局部装并锁版本，CI 跑 tsc --noEmit

⚠️ 不要全局装了就以为万事大吉。团队不锁版本，不同人编译器差异会导致类型检查结果不一致，CI 也救不了。

💡 把 tsc --noEmit 接进提交钩子（husky），能在代码进仓库前拦下类型错误，比事后在 PR 里才看到红线更省时间。