基础类型

是什么，为什么存在

TypeScript 是带静态类型检查的 JavaScript。 它分析源码，在程序运行前判断某个值能否被调用、是否具有指定属性，以及参数和返回值能否相互赋值。 通过检查的 TypeScript 最终仍作为 JavaScript 运行，所以语言的运行时语义没有因为类型注解而变成另一套规则。

类型描述的是一组允许的值，以及这些值上允许的操作。 string 表示 JavaScript 字符串，number[] 表示元素为数字的数组，{ id: string } 表示具有字符串 id 属性的对象。 类型越精确，编辑器和编译器就越能在重构、属性访问和函数调用时指出不一致。

类型注解（type annotation） 是源码中显式写出的类型，例如函数参数后的 : number。 类型推断（type inference） 则让编译器根据初始化值、实参和周围的预期类型得出类型。 日常代码通常只在函数边界、空容器或需要表达更宽契约的位置添加注解，其余局部变量交给推断。

类型系统解决的是“某种操作是否适用于这个值”这类可静态判断的问题。 它能在运行前发现拼错属性、漏传参数、没有处理 null，或者把字符串交给只接受数字的函数。 它不能判断一笔订单是否真实、用户是否有权限，也不能仅凭声明证明网络响应符合预期结构。

你会在变量、函数、对象、数组、异步结果和库 API 中持续遇到这些基础类型。 枚举、泛型、类型守卫和高级类型各有独立主题；这里建立阅读这些主题所需的共同模型，而不罗列整套语法。

工作原理

TypeScript 同时面对两个世界：编译器看到的静态类型，以及 JavaScript 引擎看到的运行时值。 编译器根据声明与控制流拒绝不安全的操作，然后移除大多数类型语法并输出 JavaScript。 运行时只会执行保留下来的表达式和检查。

常用值类型

JavaScript 的原始值在 TypeScript 中使用小写类型名：string、number、boolean、bigint、symbol、null 和 undefined。 应使用 string 而不是包装对象类型 String；前者描述普通字符串值，后者描述很少需要手动创建的对象包装器。 number 同时覆盖 JavaScript 的整数和浮点数，bigint 则是不能与 number 直接混算的另一种运行时类型。

数组可以写成 number[] 或 Array<number>，两种形式表示同一类可变数组。 readonly number[] 禁止通过该引用修改数组，但不会冻结运行时对象，也不会阻止其他可变引用修改同一数组。 元素位置具有不同含义时可使用元组，例如 [orderId: string, total: number]；元素数量可变且含义相同时则应使用数组。

对象类型列出代码需要的属性及其类型。 属性名后的 ? 表示属性可以缺失；开启严格空值检查时，读取这种属性通常得到声明类型与 undefined 的联合。 readonly 属性只限制通过当前静态类型进行赋值，并不是运行时访问控制。

函数类型描述参数与返回值，例如 (amount: number) => string。 参数通常需要注解，因为仅从函数体无法可靠推断调用方可以传入什么；返回类型往往可以推断，但公共 API 上显式写出返回类型能固定契约。 返回 void 表示调用方不应使用返回结果，而 never 表示正常控制流不可能从该位置产生值。

注解、推断与字面量

初始化表达式通常已经提供足够信息。 const retries = 3 的值不会被重新赋值，编译器可以保留更精确的字面量信息；let retries = 3 需要容纳之后的其他数字，因此通常推断为 number。 这种从具体字面量走向更宽类型的过程叫作拓宽。

对象属性默认仍被视为可变。 因此，const request = { method: "GET" } 中变量绑定不可重新赋值，但 request.method 通常是 string，不是字面量类型 "GET"。 需要保持整个字面量结构时可以使用 as const，但这也会把属性和数组元素变成只读。

上下文也能参与推断。 把箭头函数传给一个已知接收 (item: LineItem) => number 的方法时，参数 item 可以从调用位置获得类型。 如果上下文缺失并且严格选项禁止隐式 any，就必须给参数写注解。

注解应表达允许的集合，而不是简单复述初始化值。 例如，初始状态为 null、稍后会变成字符串的变量，需要声明为 string | null。 一个空数组若没有足够上下文，也应通过变量类型或所在对象的类型说明将来允许放入什么元素。

联合、空值与收窄

联合类型 string | number 表示值可能属于任一成员。 在尚未确认具体成员前，只能执行所有成员共同支持的操作。 用 typeof、相等比较、in、instanceof 或可辨识字段检查后，编译器会在相应分支中得到更精确的类型。

这种根据可达路径改变变量类型的过程叫作 控制流收窄（control-flow narrowing） 。 检查必须与运行时事实一致；如果自定义判断函数返回了错误结论，编译器会相信这个契约，而 JavaScript 仍会遇到真实数据。 优先使用直接的运行时检查，并让每个分支只处理已经证明的成员。

null 和 undefined 是不同的运行时值，也各自拥有类型。 可选属性缺失时得到 undefined；某个 API 也可能用 null 明确表示没有值。 用联合类型记录实际可能出现的情况，再通过显式比较、可选链 ?. 和空值合并 ?? 处理它们。

可辨识联合让每个对象成员带有一个字面量标签。 检查标签后，载荷会一起收窄；所有分支处理完毕后，剩余类型就是 never。 把剩余值赋给 never 可以让新增状态但遗漏处理分支的错误在编译期出现。

unknown、any 与断言

unknown 表示“这里确实有一个值，但目前不知道它是什么类型”。 任何值都可以赋给 unknown，但在收窄之前不能读取任意属性、调用它或参与只接受具体类型的操作。 这正适合描述 JSON.parse 结果、消息载荷和第三方回调等不可信边界。

any 则选择退出类型检查。 对 any 的属性访问、调用和赋值会继续传播不受检查的值，使错误离开最初的边界后才暴露。 它适合受控的迁移接缝或无法建模的遗留接口，但不应作为“暂时不知道类型”的默认答案。

类型断言（type assertion） 写作 value as Target，表示开发者向编译器提供额外信息。 断言不执行转换、不检查属性，也不生成验证代码。 它只有在前置条件已经由运行时检查、平台保证或狭窄的实现不变量证明时才可靠。

示例

下面四个示例沿着一条订单数据路径前进。 它们先描述本地数据，再处理可选值和外部输入，最后用联合类型表达状态。 每段代码都由本地 tsx 执行，输出来自实际运行结果。

让推断服务于显式边界

LineItem 固定领域对象的形状，函数参数和返回值固定调用边界。 数组字面量、归约回调中的参数以及 summary 的使用方式则由上下文推断。 只读参数说明函数不需要修改调用方的数组。

items 不必重复写成 LineItem[]，因为它作为函数实参时已经接受完整检查。 命名元组元素让位置含义更容易阅读，但运行时的 summary 仍只是普通数组。 如果后续要按名称访问更多字段，对象通常比不断增长的元组清楚。

明确处理缺失值

客户可以有地址、明确没有地址，或者省略地址属性。 类型把这三种输入都写进契约，而可选链与空值合并把后两种情况统一成自提货。

type Address = {
  line1: string;
  city: string;
};

type Customer = {
  name: string;
  address?: Address | null;
};

function shippingLabel(customer: Customer): string {
  const destination = customer.address?.city ?? "pickup";
  return `${customer.name}: ${destination}`;
}

const customers: Customer[] = [
  { name: "Ada", address: { line1: "8 River Road", city: "Paris" } },
  { name: "Lin", address: null },
  { name: "Sam" },
];

for (const customer of customers) {
  console.log(shippingLabel(customer));
}

Ada: Paris
Lin: pickup
Sam: pickup

?. 在地址为 null 或 undefined 时停止属性访问，得到 undefined。 ?? 只在左侧为 null 或 undefined 时使用默认值，因此不会误把空字符串等其他假值当成缺失。 领域是否允许空城市名是另一个验证规则，不应由 ?? 暗中决定。

在 JSON 边界验证 unknown

解析 JSON 只保证文本符合 JSON 语法，并不保证结果是订单。 这个函数先把结果视为 unknown，再验证对象本身和两个必需属性。 通过检查后，新建的返回对象满足 IncomingOrder。

type IncomingOrder = {
  id: string;
  total: number;
};

function parseOrder(raw: string): IncomingOrder {
  const value: unknown = JSON.parse(raw);

  if (typeof value !== "object" || value === null) {
    throw new Error("invalid order");
  }

  const candidate = value as Record<string, unknown>;
  if (typeof candidate.id !== "string" || typeof candidate.total !== "number") {
    throw new Error("invalid order");
  }

  return { id: candidate.id, total: candidate.total };
}

for (const raw of ['{"id":"ORD-204","total":12.5}', '{"id":204,"total":"12.5"}']) {
  try {
    const order = parseOrder(raw);
    console.log(`${order.id}: ${order.total.toFixed(2)}`);
  } catch {
    console.log("invalid order");
  }
}

ORD-204: 12.50
invalid order

这里的断言只把已经证明为非空对象的值桥接到可按字符串键检查的记录类型。 每个读取出的属性仍然是 unknown，必须分别验证。 真实系统还应根据领域要求检查有限数值、取值范围和多余字段，而不是仅复制这个最小验证器。

用可辨识联合封闭状态空间

订单状态的每个标签都带有对应字段。 检查 status 后，编译器会把 state 收窄到一个成员，因此不会在失败状态上误读签收人。

type OrderState =
  | { status: "pending"; etaMinutes: number }
  | { status: "delivered"; signedBy: string }
  | { status: "failed"; reason: string };

function describeState(state: OrderState): string {
  switch (state.status) {
    case "pending":
      return `arrives in ${state.etaMinutes} minutes`;
    case "delivered":
      return `signed by ${state.signedBy}`;
    case "failed":
      return `failed: ${state.reason}`;
    default: {
      const unreachable: never = state;
      return unreachable;
    }
  }
}

const states: OrderState[] = [
  { status: "pending", etaMinutes: 12 },
  { status: "delivered", signedBy: "Mina" },
  { status: "failed", reason: "address not found" },
];

for (const state of states) console.log(describeState(state));

arrives in 12 minutes
signed by Mina
failed: address not found

如果联合新增 cancelled 成员而函数没有新增分支，默认分支中的 state 就不能赋给 never。 这个编译错误把状态变化连接到使用方。 运行时仍可能收到不合法标签，所以边界验证不能由穷尽检查替代。

陷阱

普通文本、数值和布尔值应分别使用小写的 string、number 和 boolean。 修复方法： 只在确实操作包装对象实例时使用大写类型；业务字段和函数参数一律从小写原始类型开始。

给最终变量补一个类型注解并不能验证原始数据。 修复方法： 在边界接收 unknown，检查对象、属性和值域，然后返回新建的领域对象；大型结构可使用经过审核的运行时验证器。

生成代码常用双重断言跨过明显不兼容的类型，这通常说明契约或验证缺失。 修复方法： 写出断言成立的运行时证据，把不得不用的断言限制在一个小型辅助函数中，并测试其失败路径。

这会把“缺失”和“存在但为假”混成同一种状态。 修复方法： 只想处理 null 与 undefined 时使用 ??；业务上还要拒绝空字符串时，单独写出并命名那条验证规则。

测试样例常常使用非空数组，因此生成代码容易直接读取 items[0]。 修复方法： 检查长度或读取结果是否为 undefined，并考虑启用 noUncheckedIndexedAccess；严格选项的整体配置见相关主题。

延伸阅读

• TypeScript Handbook：基础
• TypeScript Handbook：日常类型
• TypeScript Handbook：类型收窄
• TypeScript Handbook：类型兼容性