🎯 学习目标

学完本章，你将能够：

• 能够理解 JavaScript 动态类型带来的常见痛点与隐患
• 能够阐述 TypeScript 静态类型检查的核心价值与三大优势
• 能够理解 TypeScript 的编译原理与类型擦除机制
• 能够制定渐进式迁移策略将 JS 项目迁移到 TS
• 能够权衡 TypeScript 的取舍，在合适场景做出技术选型

你有没有遇到过

代码跑起来才报错，而且报错位置离真正的问题十万八千里？

比如调用 user.nmae（拼错了），JS 不会在写代码时提醒你，直到用户看到页面上显示 undefined。

或者 "1" + "2" 得到 "12" 而不是 3，这种隐式转换的 bug 找起来特别费劲。

TypeScript 就是为了解决这些问题而生的——它在编写代码时就能发现错误，而不是等到运行时。

Part 1: JS 工程痛点

看看 JavaScript 在大型项目中会遇到哪些让人头疼的问题

写个 user.nmae（拼错了），JS 不会提醒你，直到用户看到页面上显示 undefined。"1" + "2" 得到 "12" 而不是 3，这种 bug 找起来特别费劲。这一节我们先用 JS 写几个"会出事"的真实案例，看看没有类型系统保护时代码有多脆弱。

痛点一：拼写错误

运行时才发现，为时已晚

这段 JS 代码不会报错，但结果永远是 undefined：

// JS：拼写错误，不会报错
function greet(user) {
    return "Hello, " + user.nmae; // nmae 拼错了！
}
greet({ name: "张三" }); // "Hello, undefined"

痛点二：类型陷阱

"1" + "2" 等于 "12"，不是 3

// JS：参数类型不确定，结果不可预测
function add(a, b) {
    return a + b;
}

add(1, 2);       // 3 —— 正常
add("1", "2");   // "12" —— 字符串拼接
add(1, "2");     // "12" —— 混合更乱
add([], {});     // "[object Object]" —— 完全失控

JS 不会告诉你参数应该传什么类型。你传字符串、数字、甚至数组，它都不吭声，只是默默给你一个意料之外的结果。

痛点三：对象不确定

接口返回的数据，你确定有 email 字段吗？

// JS：API 返回什么字段，完全靠猜
fetch("/api/user")
    .then(res => res.json())
    .then(user => {
        console.log(user.email); // 如果 API 返回 mail 而非 email？
        // 不会报错，只是默默 undefined
    });

后端改了字段名，前端不知道，代码静默失败。这种 bug 在多人协作的项目中特别常见。

痛点总结

五大问题，每一个都在等你上线后才发现

JSDoc 的困境

既然 JS 有痛点，能不能用注释加上类型？

很多团队的第一反应是：用 JSDoc 注释来标注类型。这看起来是个轻量方案，不用改工具链。但实际用起来呢？

/**
 * 计算订单总价
 * @param {Array<{price: number, quantity: number}>} items - 商品列表
 * @param {{code: string, discount: number}} coupon - 优惠券
 * @returns {number} 总价
 */
function calcTotal(items, coupon) {
    const sub = items.reduce((s, i) => s + i.price * i.qty, 0);
    // qty 写错了，JSDoc 不会报错！
    const off = coupon.dicsount * 0.1;
    // dicsount 拼错了，JSDoc 也不会报错！
    return sub - off;
}

同样的功能，用 TypeScript 写：

interface CartItem { price: number; quantity: number; }
interface Coupon { code: string; discount: number; }

function calcTotal(items: CartItem[], coupon: Coupon): number {
    const sub = items.reduce((s, i) => s + i.price * i.quantity, 0);
    // 拼写错误？编辑器立即标红
    const off = coupon.discount * 0.1;
    return sub - off;
}

Part 2: TypeScript 来了

TypeScript 是 JavaScript 的超集，加了静态类型检查。写代码时就能发现错误

JS 的痛点看够了，该看解决方案了。TypeScript 不是一门新语言，它只是在 JS 上面加了一层类型标注。编译的时候类型信息被擦掉，浏览器和 Node.js 看到的还是纯 JS。这一节你会看到同样的代码用 TS 写是什么样，体验一下"还没运行就知道哪里有错"的快感。

编译哲学

类型注解写完就被擦除，输出纯 JavaScript

TypeScript 是编译时工具，不改变运行时行为。编译 = 类型检查 + 类型擦除，输出纯 JS。

// TS 代码
function greet(name: string): string {
    return `Hello, ${name}`;
}

// 编译后的 JS（类型注解被完全擦除）
function greet(name) {
    return `Hello, ${name}`;
}

对比：计算面积

同样的功能，JS 和 TS 的写法对比

JS 写法——运行时才能发现错误：

// JS 版本：拼写错误、遗漏分支都不会提示
function calculateArea(shape) {
    if (shape.type === "circle") {
        return Math.PI * shape.radius * shape.radius;
    }
    return shape.width * shape.height;
    // 如果传入 { type: "unknown" }？返回 NaN
}

TS 写法——编写时就能发现所有问题：

// TS 版本：编译时就能发现错误
interface Circle { type: "circle"; radius: number; }
interface Rectangle { type: "rectangle"; width: number; height: number; }
type Shape = Circle | Rectangle;

function calculateArea(shape: Shape): number {
    switch (shape.type) {
        case "circle":
            return Math.PI * shape.radius ** 2;
        case "rectangle":
            return shape.width * shape.height;
    }
}
// 拼写错误立即标红、自动补全属性、遗漏分支报警告

TS 的三大优势

为什么越来越多项目选择 TypeScript

静态 vs 动态

一张表看清 JS 和 TS 的核心差异

工业界采用

谁在用 TypeScript？几乎所有主流框架和公司

2024 年，TypeScript 在 npm 的周下载量已经超过 5000 万，是 JavaScript 生态中最受欢迎的静态类型方案。

迁移案例

这些知名项目都从 JavaScript 迁移到了 TypeScript

TypeScript 不是纸上谈兵——看看这些你天天在用的项目是怎么迁移的：

渐进式迁移

JS 项目不用重写，一步步"渗透"就行

你不需要一天就把整个项目改成 TS。推荐分四步走：

迁移阶段一

允许 JS 和 TS 混合共存，零风险起步

第一阶段的目标很简单：让项目能编译通过，不需要改任何类型。关键是配置 tsconfig.json 允许 JS 和 TS 文件共存。

// tsconfig.json —— 阶段一：混合模式
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "node",
    "allowJs": true,
    "noImplicitAny": false,
    "strict": false,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "outDir": "./dist",
    "rootDir": "./src"
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}

迁移二三阶段

从宽松检查到严格模式，逐步收紧

阶段二：开启基本检查，开始给公共接口加类型注解。

// tsconfig.json —— 阶段二：基本检查
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "node",
    "allowJs": true,
    "noImplicitAny": true,
    "strictNullChecks": true,
    "strict": false,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "outDir": "./dist"
  },
  "include": ["src/**/*"]
}

阶段三：全面开启严格模式。这是大多数团队的目标状态。

// tsconfig.json —— 阶段三：严格模式
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "node",
    "allowJs": false,
    "strict": true,
    "noImplicitAny": true,
    "strictNullChecks": true,
    "strictFunctionTypes": true,
    "noImplicitThis": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "outDir": "./dist"
  },
  "include": ["src/**/*"]
}

迁移阶段四

极致严格：让编译器帮你挡住更多边界情况

当团队对 TS 已经很熟悉后，可以开启更严格的选项，让类型系统发挥最大威力：

// tsconfig.json —— 阶段四：极致严格
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "node",
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true,
    "noPropertyAccessFromIndexSignature": true,
    "forceConsistentCasingInFileNames": true,
    "noImplicitOverride": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "outDir": "./dist"
  },
  "include": ["src/**/*"]
}

ts-check 方案

不改后缀、不配编译器，也能享受类型检查

如果你的项目非常大（几十万行 JS），连阶段一都不想碰，还有一个更轻量的选择：// @ts-check。

// @ts-check
// 在 JS 文件顶部加这一行，VS Code 就会启动类型检查

/** @type {number} */
let count = 0;

/**
 * 计算折扣价
 * @param {number} price - 原价
 * @param {number} discount - 折扣率（0-1）
 * @returns {number}
 */
function getSalePrice(price, discount) {
    return price * (1 - discount);
}

// 如果这样调用，编辑器会标红：
getSalePrice("99", 0.2); // 错误："99" 不是 number
count = "hello";          // 错误：不能把 string 赋给 number

版本选择

TypeScript 版本那么多，该用哪个？

# 查看当前安装的版本
$ npx tsc --version
# TypeScript 5.7

# 安装指定版本
$ npm install typescript@5.6 --save-dev

# 安装最新版
$ npm install typescript@latest --save-dev

// package.json —— 库的 typesVersions 配置
{
  "name": "my-lib",
  "main": "dist/index.js",
  "types": "dist/index.d.ts",
  "typesVersions": {
    ">=5.0": { "*": ["dist/ts5.0/*"] },
    "*":     { "*": ["dist/legacy/*"] }
  }
}

编译流程

.ts 文件是怎么变成 .js 的？三步走

TypeScript 编译器（tsc）的工作可以拆成三步：

  .ts 源码
     ↓
  ① 解析 → 生成 AST（抽象语法树）
     ↓
  ② 类型检查 → 检查所有类型是否匹配
     ↓
  ③ 类型擦除 → 移除注解，输出纯 .js

// 输入：src/hello.ts
const name: string = "张三";
function greet(n: string): string {
    return `Hello, ${n}`;
}

// 输出：dist/hello.js
const name = "张三";
function greet(n) {
    return `Hello, ${n}`;
}

综合练习

找出下面 JS 代码中的所有类型隐患

// 一个"订单处理"函数，藏着多少类型隐患？
function processOrder(order) {
    const total = order.items.reduce((sum, item) => {
        return sum + item.price * item.quantity;
    }, 0);

    const discount = order.coupon * 0.1;
    const finalPrice = total - discount;

    order.customer.balance -= finalPrice;
    sendEmail(order.customer.emial, "订单确认");

    return { sucess: true, price: finalPrice };
}

processOrder({
    items: [{ price: "99", quantity: 2 }],
    coupon: null,
    customer: { balance: 500, email: "test@test.com" }
});

// 类型隐患清单：
// 1. item.price 是字符串 "99"，乘法结果变成 NaN
// 2. order.coupon 是 null，null * 0.1 得到 0（碰巧没报错）
// 3. order.customer.emial 拼写错误（应该是 email）
// 4. balance 可能为负数，没有校验
// 5. 返回值 sucess 拼写错误（应该是 success）
// 6. reduce 初始值 0 没问题，但 item.price 如果是 undefined 就炸了
// 这些问题 TS 都能在编译时发现！

常见疑问

疑问一：TS 是不是要重写所有代码？

不是。所有合法的 JS 都是合法的 TS。你可以把 .js 改成 .ts，就能开始用。类型注解可以逐步添加。

疑问二：TS 在浏览器里能直接运行吗？

不能。TS 需要编译成 JS 才能运行。但这个过程通常由构建工具（如 Vite）自动完成。

疑问三：学习 TS 之前需要精通 JS 吗？

不需要。边学 JS 边学 TS 反而更好，TS 能帮你更早发现 JS 代码里的错误。

试一试

function getUserInfo(id) {
    const user = database.find(id);
    return user.age + "岁";
}
getUserInfo("abc");

// 隐患：
// 1. id 可能是字符串，但数据库可能期望数字
// 2. user 可能是 null（找不到），访问 .age 会报错
// 3. user.age 如果是 undefined，结果变成 "undefined岁"

// JS 版本
function formatPrice(price) {
    return "¥" + price.toFixed(2);
}

// TS 版本
function formatPrice(price: number): string {
    return "¥" + price.toFixed(2);
}
// 现在传入字符串会编译报错

📝 要点总结

本章核心知识点