TypeScript readonly：只读属性、Readonly<T> 与只读数组

readonly 标记的属性只能在对象创建时设置一次，之后不能再重新赋值。Readonly<T> 把它应用到一个类型的每个属性上，readonly T[] 则对数组做同样的事：

interface Point {
  readonly x: number;
  readonly y: number;
}

const origin: Point = { x: 0, y: 0 };
// @ts-expect-error: Cannot assign to 'x' because it is a read-only property
origin.x = 5;

const config: Readonly<{ host: string; port: number }> = { host: "localhost", port: 8080 };
const ports: readonly number[] = [80, 443];

console.log(config.host, ports.length); // localhost 2
console.log(origin);                    // { x: 5, y: 0 }

最后一行展示了关于 readonly 最重要的事实：它由编译器检查，而不是在运行时强制执行。这次赋值是编译错误（这里用 @ts-expect-error 屏蔽了），但生成的 JavaScript 仍然执行了它。如果去掉屏蔽，文件就无法编译，而这正是 readonly 发挥作用的地方。

只读属性

在接口、类型字面量或类中，把 readonly 写在属性名前面。这个属性可以初始化，但不能重新赋值：

class Invoice {
  readonly id: string;
  readonly createdAt = "2024-03-15";
  total = 0;

  constructor(id: string) {
    this.id = id; // allowed: the constructor may initialize readonly fields
  }

  add(amount: number) {
    this.total += amount; // fine: total is not readonly
    // this.id = "x" would be error TS2540: Cannot assign to 'id' because it is a read-only property.
  }
}

const inv = new Invoice("INV-7");
inv.add(19.5);
console.log(inv); // Invoice { id: 'INV-7', createdAt: '2024-03-15', total: 19.5 }

在类中，readonly 字段只能在声明处或构造函数中赋值，其他地方都不行。最简短的写法是参数属性 constructor(readonly id: string) {}，它一步完成字段的声明和赋值。类页面 介绍了字段和构造函数的一般用法。

Readonly<T>：一次处理所有属性

Readonly<T> 是一个工具类型，把 T 的每个属性都标记为 readonly。对于你会到处传递但不应修改的值（例如应用状态），它很有用：

interface State {
  user: string;
  cart: string[];
  total: number;
}

function addItem(state: Readonly<State>, item: string, price: number): State {
  // state.total += price would be error TS2540
  return { ...state, cart: [...state.cart, item], total: state.total + price };
}

const s0: State = { user: "ada", cart: [], total: 0 };
const s1 = addItem(s0, "book", 12);
const s2 = addItem(s1, "pen", 2);

console.log(s0.cart, s2); // [] { user: 'ada', cart: [ 'book', 'pen' ], total: 14 }

函数签名告诉读者，addItem 返回一个新状态，而不是修改旧状态，编译器也会让函数遵守这一点。Readonly<T> 的定义是映射类型 { readonly [P in keyof T]: T[P] }。

只读数组：readonly T[] 与 ReadonlyArray<T>

readonly number[] 和 ReadonlyArray<number> 是同一个类型。它们去掉了所有会修改数组的方法（push、pop、shift、splice、sort、reverse、fill 等），并禁止按索引赋值。不修改数组的方法仍然保留，并返回普通数组：

const scores: readonly number[] = [42, 7, 19];

const doubled = scores.map((s) => s * 2);        // number[] (a new, mutable array)
const sorted = [...scores].sort((a, b) => a - b); // copy first, then sort the copy
const top = scores.slice(0, 2);

// @ts-expect-error: Property 'push' does not exist on type 'readonly number[]'
scores.push(1);

console.log(doubled, sorted, top); // [ 84, 14, 38 ] [ 7, 19, 42 ] [ 42, 7 ]
console.log(scores);               // [ 42, 7, 19, 1 ]  (push ran: types are erased)

把参数类型写成 readonly T[]，就是向调用方承诺你不会修改他们的数组。反过来则是大家容易卡住的地方：只读数组不能传给接受普通 T[] 的函数，因为那个函数可能会修改它。

// This does not compile: a readonly array cannot go where a mutable one is expected
function sum(values: number[]): number {
  return values.reduce((a, b) => a + b, 0);
}

const prices: readonly number[] = [3, 4, 5];
console.log(sum(prices));

index.ts(7,17): error TS4104: The type 'readonly number[]' is 'readonly' and cannot be assigned to the mutable type 'number[]'.

修复方法是把 sum 改为接受 readonly number[]，因为它并不修改任何东西。只读取数组的函数都应该接受只读类型，这样两种数组它都能接受。如果函数不归你管，就传一个副本：sum([...prices])。

ReadonlyMap 与 ReadonlySet

Map 和 Set 也有只读版本。ReadonlyMap<K, V> 有 get、has、size、forEach 和各种迭代器，但没有 set、delete 或 clear；ReadonlySet<T> 没有 add、delete 或 clear：

const prices: ReadonlyMap<string, number> = new Map([
  ["tea", 2.5],
  ["coffee", 3.2],
]);
const admins: ReadonlySet<string> = new Set(["ada"]);

console.log(prices.get("tea"), prices.size, admins.has("ada")); // 2.5 2 true

// @ts-expect-error: Property 'set' does not exist on type 'ReadonlyMap<string, number>'
prices.set("juice", 4);

类常常在内部保存一个私有的可变 Map，再通过类型为 ReadonlyMap 的 getter 对外暴露，这样外部代码可以读取数据，却不能通过这个引用修改它。

readonly 是浅层的

readonly 和 Readonly<T> 只保护属性本身，而不保护它指向的对象或数组：

interface Team {
  readonly name: string;
  readonly members: string[];
  readonly lead: { name: string };
}

const team: Readonly<Team> = { name: "Core", members: ["ada"], lead: { name: "ada" } };

team.members.push("linus"); // allowed: the array itself is not readonly
team.lead.name = "linus";   // allowed: only the lead property is readonly
// team.members = [] would be error TS2540

console.log(team); // { name: 'Core', members: [ 'ada', 'linus' ], lead: { name: 'linus' } }

type DeepReadonly<T> = T extends (...args: any[]) => unknown ? T
  : T extends object ? { readonly [K in keyof T]: DeepReadonly<T[K]> }
  : T;

const frozenTeam: DeepReadonly<Team> = team;
// @ts-expect-error: Property 'push' does not exist on type 'readonly string[]'
frozenTeam.members.push("grace");

DeepReadonly<T> 会把自己应用到每一个嵌套的对象类型上；而对数组类型做映射会得到只读数组，所以 members 变成了 readonly string[]。这仍然只是类型层面的承诺，而不是运行时的保护。

只在编译时生效：通过另一个引用修改

只读类型控制的是某一个引用能做什么。指向同一对象、但类型中没有 readonly 的另一个引用可以修改它，而且 TypeScript 甚至允许把只读类型赋给可变类型：

interface Settings {
  readonly theme: string;
}

const settings: Settings = { theme: "dark" };
const mutable: { theme: string } = settings; // allowed, no error
mutable.theme = "light";

console.log(settings.theme); // light

// Runtime protection needs Object.freeze
const locked = Object.freeze({ theme: "dark" }); // typed Readonly<{ theme: "dark" }>
try {
  (locked as { theme: string }).theme = "light";
} catch (e) {
  console.log((e as Error).name); // TypeError
}
console.log(locked.theme); // dark

mutable = settings 这次赋值能编译通过，因为 TypeScript 在检查两个对象类型是否兼容时，不考虑 readonly 属性；TypeScript 手册明确说明了这一点，并指出只读属性因此可能通过别名被修改。只读数组则不同：上面的 TS4104 错误正是这项检查。Object.freeze 能真正在运行时阻止修改：生成的代码在严格模式下运行，而在严格模式下写入被冻结的属性会抛出 TypeError。和 readonly 一样，Object.freeze 也是浅层的。

readonly、const、as const 与 Object.freeze

对字面量使用 as const，会让每一层的每个属性都变成 readonly，并保留字面量类型，这通常是得到深层只读值最简单的方法：

const theme = { mode: "dark", sizes: [12, 14] } as const;
// { readonly mode: "dark"; readonly sizes: readonly [12, 14] }

const 和 readonly 回答的是不同的问题：const 阻止名字指向别处，readonly 阻止属性被修改。const 对象的属性仍然可以重新赋值，除非它们是 readonly。