订单详情页上线第二天,客服转来一张截图:页面空白,控制台一行 Cannot read properties of undefined (reading 'price')。这个项目「全量上了 TypeScript」,Order 接口定义得明明白白,每个函数都有返回值标注。可问题还是发生了。

翻代码,第一行就露馅:

const order = (await res.json()) as Order;
const total = order.items[0].price * order.items[0].count;

res.json() 返回的是 any,as Order 只是告诉编译器「相信我」,并不检查接口真的返回了什么。当天后端把空订单的 items 返回成了空数组,items[0] 自然是 undefined。类型标注一个没少,运行时该崩还是崩。

这篇讲什么:TypeScript 在什么阶段工作、能保证什么;标注和推断各用在哪;any、unknown、联合类型和类型收窄怎么用;tsconfig 里哪几项真的影响安全。读完你能做到:不再把 as 当类型转换用;在接口边界加运行时校验;让编辑器在你写错时真的报错,而不是全程绿灯。

版本说明:本文按 TypeScript 6 写,5.x 的写法基本通用。7.0 的原生编译器已经进入 RC 阶段,类型语法和检查行为没有推翻重来,换版本时主要看构建工具链的兼容性。

TypeScript 只在编译期存在

先把最容易误解的一点说透:TypeScript 的类型在运行时不存在。编译后,接口、泛型、类型标注全部被擦掉,浏览器拿到的还是普通 JavaScript。所以类型错误分两类:

编译期能抓到的

拼错属性名、参数类型不对、漏处理 null、联合类型少写分支。这些在编辑器里就报红,不用等上线。

编译期抓不到的

接口返回结构和声明不一致、数组越界、用户输入、第三方库的类型撒谎、类型断言硬压。这些只能靠运行时校验和测试。

TypeScript 的价值在于把第一类错误提前,让你在改代码时就有反馈。它不负责保证数据真的长成那个样子。把这两件事分开,后面很多争论就没必要了。

还有一层:tsc 默认只做类型检查,不做运行时代码生成里的「转换」。像枚举、装饰器、参数属性这些语法,需要编译器生成额外代码;而类型标注、接口、泛型参数,是纯擦除。现代构建工具(Vite、SWC、Rolldown)多数只擦除、不检查,所以「构建成功」不等于「类型没问题」。

标注和推断:别把每个变量都写上类型

TypeScript 的类型有两个来源:你写的标注,和编译器从代码里推断出来的。新手常犯的错是到处写标注,把代码写得比 JavaScript 还啰嗦:

// 不需要标注,推断已经足够
const count: number = 3;
const names: string[] = ["a", "b"];
const total: number = items.reduce((sum: number, item: Order) => sum + item.price, 0);

上面这些标注没有增加任何信息,反而在改动时多一处要维护。什么时候该写标注?答案是「类型无法从右边推断出来」或者「这个位置的类型是团队约定」的时候:

  • 函数参数。参数没有初始值,编译器不知道它是什么。
  • 函数的公开返回值。尤其是库或模块的导出函数,返回值标注就是契约。
  • 对象的结构。从接口、配置、API 响应来的数据,写清楚字段。
  • 空数组、空对象。推断出来是 never[] 或 {},后面再加内容就对不上。
// 该标注的地方
function calcTotal(items: OrderItem[]): number {
  return items.reduce((sum, item) => sum + item.price * item.count, 0);
}

// 空数组先声明元素类型
const errors: string[] = [];

// 配置对象用接口约束
interface AppConfig {
  apiBase: string;
  timeout: number;
}

const config: AppConfig = { apiBase: "/api", timeout: 5000 };

推断不是「不写类型」,而是编译器替你写。编辑器里把鼠标悬停在变量上,能看到推断结果。如果推断出来的类型比预期宽(比如变成了 string 而不是字面量联合),再补标注或用 as const。

any、unknown、never:三个容易混淆的类型

any 是「关掉检查」。任何值都能赋给它,它也能赋给任何类型,还能随便点属性。它的问题是会把污染扩散出去:一个 any 传进函数,函数内部的所有检查都失效。

unknown 是「我不知道,但你用之前必须先证明」。它也能接任何值,但你不能直接读属性、不能直接调用,必须先收窄:

function handle(input: unknown) {
  // input.toFixed();          // 报错,unknown 不能直接用
  if (typeof input === "number") {
    input.toFixed(2);          // 这里收窄成 number,才能用
  }
}

所有外部输入都应该先当 unknown:JSON.parse、fetch 的响应、localStorage、postMessage、用户上传的文件。先收窄,再使用。

never 是「不可能有值」。它有两个常见用途:函数永远不返回(抛错或死循环),以及穷尽检查:

type Status = "pending" | "paid" | "shipped";

function describe(status: Status) {
  switch (status) {
    case "pending": return "待支付";
    case "paid": return "已支付";
    case "shipped": return "已发货";
    default: {
      const exhaustive: never = status;   // 新增状态时这里会报错
      return exhaustive;
    }
  }
}

如果哪天有人给 Status 加了 "refunded",default 里的赋值就会报「string 不能赋给 never」,逼你处理新分支。这是类型系统里少有的「主动提醒你漏了业务」的机制。

对象、联合类型和类型收窄

业务里最常见的数据形状,不是单一类型,而是「可能是 A,也可能是 B」。比如接口返回可能是成功也可能是失败:

interface Success {
  ok: true;
  data: Order;
}

interface Failure {
  ok: false;
  message: string;
}

type Result = Success | Failure;

function render(result: Result) {
  if (result.ok) {
    console.log(result.data.id);     // 收窄成 Success
  } else {
    console.log(result.message);     // 收窄成 Failure
  }
}

这叫可辨识联合:用一个固定字段(这里是 ok)区分分支。它比「所有字段都可选」的接口安全得多,因为编译器能根据字段判断当前是哪一支,访问不存在的属性会直接报错。

收窄的手段有 typeof、instanceof、in、字面量比较、自定义类型守卫。数组和对象还要注意可选链:

interface Order {
  id: string;
  coupon?: { code: string; discount: number };
}

function discountOf(order: Order): number {
  return order.coupon?.discount ?? 0;   // 没有优惠券时给 0
}

可辨识联合和可选链解决的是「值可能不存在」。还有一种更隐蔽的:数组下标。默认配置下,items[0] 的类型仍然是 OrderItem,编译器不会提醒你可能越界。要抓这类问题,得打开 noUncheckedIndexedAccess,代价是每个下标访问都要判空。团队可以按项目风险决定,公共组件库值得开,内部小工具未必。

interface 和 type,怎么选不纠结

两者大部分场景可以互换:

interface User {
  id: string;
  name: string;
}

type User = {
  id: string;
  name: string;
};

差别在扩展能力和语义:

能力interfacetype
声明合并支持,同名接口会合并不支持,重复声明报错
联合、交叉、条件类型不能直接定义可以
扩展已有类型extends& 交叉
错误信息可读性通常更好复杂类型会展开成一大串

我的习惯:描述一个对象的结构用 interface;需要联合类型、映射类型、从别的类型算出来的类型,用 type。一个文件里不要两套风格乱跳。声明合并这个特性,业务代码里很少主动用,更多是给第三方库补充类型时才需要。

结构类型是 TypeScript 的底层规则:只要字段对得上,类型就兼容,名字不重要。这带来灵活性,也带来两个坑。第一,对象字面量直接赋值会触发「多余属性检查」,多写一个字段就报错;但先把对象存进变量再赋值,检查就放过了。第二,两个结构相同但语义不同的类型会被认为兼容,比如 UserId 和 OrderId 都是 string,传错了编译器不拦。要区分语义,得用品牌类型(前面加一个只读标记字段),那属于进阶篇的内容。

函数、事件和 catch:三个高频标注点

函数参数是推断不出来的,必须标。回调函数里,编译器能从上下文推断参数类型,不用手写:

const ids = orders.map((order) => order.id);   // order 自动推断

// 单独抽出来的处理函数,参数要标
function onOrderClick(event: MouseEvent, orderId: string) {
  console.log(orderId, event.clientX);
}

DOM 事件最容易标错。写 Event 就访问不到 clientX,写 MouseEvent 才行;表单提交是 SubmitEvent,输入框是 InputEvent 或 Event,取决于监听方式。拿不准时先写 Event,看报错提示缺哪个属性,再换成具体类型。

catch 的变量默认是 unknown(开启 strict 后)。这是对的:抛出来的可能是 Error,也可能是字符串、对象,甚至 undefined。不要直接 err.message:

try {
  await saveOrder(order);
} catch (err: unknown) {
  const message = err instanceof Error ? err.message : String(err);
  reportError({ message, context: "saveOrder" });
}

表单还有一类固定坑:input.value 永远是字符串。类型标注成 number 不会让浏览器给你数字,得自己 Number() 或 parseInt(),还要处理空字符串和 NaN。类型系统只能提醒你「这里声明的是数字」,不能替你做转换。

tsconfig:哪几项真的影响安全

一个能用的最小配置,重点是 strict 和构建工具的衔接:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "lib": ["ES2022", "DOM", "DOM.Iterable"],
    "strict": true,
    "noEmit": true,
    "isolatedModules": true,
    "verbatimModuleSyntax": true,
    "skipLibCheck": true,
    "baseUrl": ".",
    "paths": { "@/*": ["src/*"] }
  },
  "include": ["src"]
}

strict 是一组开关的集合,最重要的是 strictNullChecks:null 和 undefined 不再能随便赋给其他类型。关掉它,TypeScript 的价值少一半。

noEmit 是因为构建交给 Vite,tsc 只负责检查。如果还让 tsc 输出文件,容易和构建工具的产物打架。moduleResolution: "bundler" 让类型解析按打包工具的规则来,支持 package.json 的 exports 字段,避免「运行时能 import、类型却找不到」。

isolatedModules 和 verbatimModuleSyntax 是为了兼容「单文件擦除」式构建:每个文件必须能独立编译,类型导入必须写 import type,否则构建工具可能把只用于类型的导入保留成真实导入,运行时找不到。

skipLibCheck 跳过第三方声明文件的检查,能显著加快启动,代价是库自身的类型错误不报。现代项目基本都开,因为第三方声明文件的质量不受你控制。

Vite 构建时只擦除类型,不做检查。必须单独跑 tsc --noEmit,并放进 CI。只依赖「编辑器没红线」的项目,迟早会把类型错误带上线。

完整场景走查:订单页从 JavaScript 迁到 TypeScript

需求不复杂:一个订单列表和详情页,调接口拿数据,算总价,处理优惠券。项目是 Vite 搭的,原来是纯 JS。计划是先把类型加上,不改业务,再逐步收紧。

第一步,加 tsconfig.json,先开 strict: false 和 allowJs: true,让老的 .js 文件也能参与编译。此时跑 tsc --noEmit,错误是零,但这是因为大部分文件还没改成 TS,不是代码真的干净。

第二步,改入口和工具函数。给 formatPrice(cents: number): string 加参数和返回值,调用处立刻暴露出两个传字符串的地方:一个是从 input.value 直接传,一个是接口字段没转数字。这两处都是线上已经存在的隐患,类型检查只是把它们提前了。

第三步,定义数据接口。这里犯了一个错:照着后端文档写 interface Order,然后在请求处 as Order。类型检查全绿,但运行时没有任何保障。后来改成在边界做校验:

function parseOrder(input: unknown): Order {
  if (typeof input !== "object" || input === null) {
    throw new Error("订单数据不是对象");
  }
  const raw = input as Record<string, unknown>;
  if (typeof raw.id !== "string" || !Array.isArray(raw.items)) {
    throw new Error("订单缺少必要字段");
  }
  return {
    id: raw.id,
    items: raw.items.map(parseOrderItem),
    coupon: parseCoupon(raw.coupon)
  };
}

这一步的价值在后来的联调里体现了:后端把 items 从数组改成对象,前端没有白屏,而是弹出了「订单数据异常」,日志里带着原始结构。错误从「页面崩了」变成「一条可定位的业务报错」。

第四步,处理可选字段。优惠券从「一定有」改成「可能没有」,类型改成 coupon?: Coupon。改完编译器立刻在六个地方报「对象可能为 undefined」,逐个加 ?. 和默认值。其中一个地方原来写的是 order.coupon.discount,线上没有券时就会崩,类型检查提前抓到了。

第五步,处理事件和 catch。事件处理函数从 (e) => 改成 (e: MouseEvent) =>,catch 里不再直接读 err.message。同步把 strict 打开,又冒出一批 any 和隐式类型,逐个处理。第一批 47 个错误里,大约一半是真正的空值风险,另一半是标注噪音。

第六步,接 CI。加一条 tsc --noEmit,和 Lint、构建并列。第一次跑用了四十秒,项目变大后可以考虑增量检查。这一步之后,「类型写了但没检查」的口子才算堵上。

整个过程没有引入任何运行时校验库,先用一个手写的小函数守住接口边界。项目变大、接口变多时,再考虑用成熟的 schema 校验库,把「解析」和「类型推导」合并成一份定义。

错误现象对照

现象真实原因第一步查什么
Cannot read properties of undefined,类型却写得很全用了 as 或 any,绕过了检查;数据本身缺字段搜代码里的 as 和 any,在接口边界加校验
Object is possibly 'undefined'可选字段或数组下标没处理看该值的来源,用 ?.、默认值或提前判空
Type 'string' is not assignable to type 'number'表单值、URL 参数天然是字符串检查赋值处是否漏了 Number() 并处理 NaN
Parameter 'e' implicitly has an 'any' type开了 noImplicitAny,回调参数没有上下文推断给处理函数补事件类型,别用 any 蒙混
构建成功,CI 的 tsc 却报一堆错构建工具只擦除类型,不做检查确认 CI 有独立的 tsc --noEmit 步骤
Cannot find module 'x' or its type declarations缺 @types/x,或 moduleResolution 配置不对看包是否自带类型,再查 moduleResolution 与 paths
改成 TS 后运行时找不到导入只用于类型的导入没写 import type,被当成真实导入保留开 verbatimModuleSyntax,按报错改成类型导入

边界与代价

TypeScript 的收益在「改动频繁、多人协作、生命周期长」的项目里最大。一个只活两周的活动页,从零配 TS、写接口、补校验,可能比直接写 JS 花的时间还多。判断标准不是「TypeScript 更高級」,而是这个代码未来还要被改几次、由几个人改。

类型不是免费的。标注会增加阅读负担,复杂类型会让错误信息变成一屏天书;strict 打开后,老项目会一次性冒出几百个错误,如果团队没有排期处理,最后往往是把 strict 关回去,顺便对 TS 失去信心。迁移要分批:先开 strict 之外的基础项,按目录逐步收紧,每一批都进 CI,别搞「大爆炸式」改造。

最大的误区是把类型当运行时保障。类型断言、any、第三方库的错误声明、后端契约变更,都能让「类型全绿」的代码在线上崩掉。边界数据必须校验,关键流程必须有测试,类型只是第一道筛子。

类型建模也有过度设计的风险。为了一个只有三个字段的接口,写五层泛型和条件类型,后人改一个字段要在五个类型之间跳转,维护成本远超收益。类型应该服务业务,不是展示技巧;能用一个联合类型说清的事,不要用类型体操。

编译时间也是成本。类型越多、泛型越深,tsc 越慢。大项目要关注检查耗时,必要时拆分项目引用、限制 include 范围、避免在全局类型里堆大对象。

小结

类型只在编译期擦除之后就是普通 JS;类型检查能抓拼写和空值,抓不到接口撒谎和用户输入。
标注用在边界,推断留给局部函数参数、返回值、数据结构要标;局部变量让编译器推断,少写废话。
外部数据先当 unknown收窄后再用;any 会扩散污染,as 不是转换,是让编译器闭嘴。
strict 和独立类型检查是底线构建工具不检查类型,CI 必须有 tsc --noEmit;边界再加运行时校验。

今天可以自己验证的练习:

  1. 写一个函数接收 unknown,用 typeof 和 in 收窄后读取属性,观察哪些操作必须判空。
  2. 把 fetch 的返回值改成 unknown,去掉 as,体验编译器逼你做校验的过程。
  3. 给一个联合类型加新成员,看 never 穷尽检查是否在 default 分支报错。
  4. 打开 noUncheckedIndexedAccess,跑一遍项目,统计数组下标相关的报错数量。
  5. 在 CI 里加 tsc --noEmit,故意把一个数字写成字符串,确认流水线会红。

下一篇讲TypeScript 进阶。这一篇解决「怎么把类型写对」,下一篇解决「怎么让类型跟着数据走」:泛型、条件类型、工具类型,以及什么时候该停手。真实项目里的接口和组件,很少是固定形状,类型系统得能表达变化。