TypeScript Record 类型：Record<K, V> 用法详解与示例

Record<K, V> 是一个内置工具类型，表示键的类型为 K、所有值的类型都为 V 的对象。用 string 作键时，它描述的是一个字典；用字面量联合类型作键时，它描述的是一个必须恰好拥有这些键的对象。

// Any string key, number values
const stock: Record<string, number> = { apples: 12, pears: 0 };
stock.plums = 7;

// Exactly these three keys, each with a string value
type Lang = "en" | "de" | "fr";
const greeting: Record<Lang, string> = {
  en: "Hello",
  de: "Hallo",
  fr: "Bonjour",
};

console.log(stock);          // { apples: 12, pears: 0, plums: 7 }
console.log(greeting.de);    // Hallo

Record 只存在于类型系统中。在运行时，这两个对象都是普通的 JavaScript 对象，所以对象字面量、展开运算符、JSON.stringify 以及其他任何接受对象的地方都能用它们。

语法与定义

Record<Keys, Value>

Keys 必须是可以作为对象键的类型：string、number、symbol、字符串或数字字面量的联合类型，或者模板字面量类型。Value 可以是任意类型。TypeScript 标准库中的完整定义只有一行，是一个映射类型：

type Record<K extends keyof any, T> = {
  [P in K]: T;
};

keyof any 就是 string | number | symbol，即所有可能的键类型。[P in K]: T 为 K 的每个成员创建一个类型为 T 的属性。这就解释了下面的两种行为：像 string 这样宽泛的 K 会生成索引签名（任意键），而联合类型的 K 会为每个成员生成一个必需属性。

联合类型作键：每个键都必须存在

当键是字面量的联合类型时，Record 必须列出其中的每一个键，而且不能有别的键。这样编译器就变成了一张检查清单：

type Status = "idle" | "loading" | "success" | "error";

const label: Record<Status, string> = {
  idle: "Ready",
  loading: "Loading...",
  success: "Done",
  error: "Something went wrong",
};

const color: Record<Status, `#${string}`> = {
  idle: "#888888",
  loading: "#3b82f6",
  success: "#16a34a",
  error: "#dc2626",
};

function render(s: Status): string {
  return `${label[s]} (${color[s]})`;
}

console.log(render("success")); // Done (#16a34a)

给 Status 加上 "cancelled"，这两个对象就会编译失败，直到你为新状态补上标签和颜色。漏掉一个键，或者加上一个不在联合类型中的键，都是编译错误：

// This does not compile: one key is missing and one is not allowed
type Status = "idle" | "loading" | "success" | "error";

const label: Record<Status, string> = {
  idle: "Ready",
  loading: "Loading...",
  success: "Done",
};

const icon: Record<Status, string> = {
  idle: "o", loading: "~", success: "v", error: "x", paused: "=",
};

index.ts(4,7): error TS2741: Property 'error' is missing in type '{ idle: string; loading: string; success: string; }' but required in type 'Record<Status, string>'.
index.ts(11,54): error TS2353: Object literal may only specify known properties, and 'paused' does not exist in type 'Record<Status, string>'.

用字符串枚举作键类型也是一样：Record<Color, string> 要求枚举的每个成员都有一项。

Record<string, T> 与缺失的键

用 string 作键时，任何键都是允许的，而且 TypeScript 会把每次读取的类型都当作 T，哪怕这个键根本不存在。在运行时，缺失的键会得到 undefined：

const prices: Record<string, number> = { tea: 2.5, coffee: 3.2 };

const juice = prices["juice"]; // typed number, but undefined at runtime
console.log(juice);            // undefined
console.log(juice * 2);        // NaN, and no compile error

// Check before you use it
if ("juice" in prices) {
  console.log("juice costs", prices.juice);
} else {
  console.log("no juice"); // no juice
}

// Or put undefined in the value type so the compiler makes you check
const safePrices: Record<string, number | undefined> = { tea: 2.5 };
const maybe = safePrices["juice"]; // number | undefined
console.log(maybe ?? 0);           // 0

这是 Record 最常见的 bug。有三种处理方式：读取之前先用 in 或 Object.hasOwn 检查；把值声明为 V | undefined；或者开启编译选项 noUncheckedIndexedAccess，它会给项目中每一次索引签名读取都加上 | undefined。用联合类型作键的 Record 没有这个问题，因为每个键都保证存在。

Partial<Record<K, V>>：只需要部分键

想用联合类型作键、又不要求所有键都存在，就把 Record 包在 Partial 里。这样读取会返回 V | undefined，类型如实反映了情况：

type Lang = "en" | "de" | "fr" | "ja";

// Translations are optional per language, but only these languages are allowed
const title: Partial<Record<Lang, string>> = {
  en: "Settings",
  de: "Einstellungen",
};

function translate(lang: Lang): string {
  return title[lang] ?? title.en ?? "(missing)";
}

console.log(translate("de")); // Einstellungen
console.log(translate("ja")); // Settings

// Required "en", optional others
type Labels = Record<"en", string> & Partial<Record<Exclude<Lang, "en">, string>>;
const save: Labels = { en: "Save", fr: "Enregistrer" };
console.log(save); // { en: 'Save', fr: 'Enregistrer' }

拼错的键（比如 jp）仍然会报错，这正是它比 Record<string, string> 强的地方。

遍历 Record

Object.keys、Object.values 和 Object.entries 都能用。要注意的是键的类型：Object.keys 返回 string[]，Object.entries 返回 [string, V][]，永远不会是你的键联合类型：

type Plan = "free" | "pro" | "team";
const seats: Record<Plan, number> = { free: 1, pro: 1, team: 10 };

for (const [plan, n] of Object.entries(seats)) {
  console.log(plan, n); // plan is string, n is number
}
// free 1
// pro 1
// team 10

// When you need the union type, cast the keys
const plans = Object.keys(seats) as Plan[];
const total = plans.reduce((sum, p) => sum + seats[p], 0);
console.log(total); // 12

// for...in gives string keys too
for (const key in seats) {
  console.log(key.toUpperCase()); // FREE, PRO, TEAM on separate lines
}

TypeScript 故意把键保留为 string：对象在运行时拥有的属性可能比它的类型列出的更多，所以一般来说承诺返回 Plan[] 是不安全的。对于像 seats 这样由字面量创建的对象，这个断言是安全的。

用数据构建 Record

Record 通常是对数组做分组或建立索引的结果。从一个带 Record 类型的空对象开始，再往里填数据：

interface Book {
  id: string;
  title: string;
  genre: "fiction" | "science" | "history";
}

const books: Book[] = [
  { id: "b1", title: "Dune", genre: "fiction" },
  { id: "b2", title: "Cosmos", genre: "science" },
  { id: "b3", title: "Emma", genre: "fiction" },
];

// Index by id
const byId: Record<string, Book> = {};
for (const b of books) byId[b.id] = b;

// Group by genre (every genre present, even if empty)
const byGenre: Record<Book["genre"], string[]> = { fiction: [], science: [], history: [] };
for (const b of books) byGenre[b.genre].push(b.title);

console.log(byId.b2.title); // Cosmos
console.log(byGenre);       // { fiction: [ 'Dune', 'Emma' ], science: [ 'Cosmos' ], history: [] }

// Object.fromEntries gives { [k: string]: V }, which fits Record<string, V>
const titles: Record<string, string> = Object.fromEntries(books.map((b) => [b.id, b.title]));
console.log(titles); // { b1: 'Dune', b2: 'Cosmos', b3: 'Emma' }

Book["genre"] 复用了接口中的联合类型作为键类型，所以给 Book 新增一个类别后，byGenre 就会要求补上对应的一项。

Record<string, unknown> 与接口

Record<string, unknown> 常用来表示“某个键为字符串的对象”。它接受对象字面量和用 type 别名声明类型的值，但会拒绝接口：

// This does not compile: interfaces have no implicit index signature
interface User {
  name: string;
}

function logFields(obj: Record<string, unknown>) {
  console.log(Object.keys(obj));
}

const user: User = { name: "Ada" };
logFields(user);

index.ts(11,11): error TS2345: Argument of type 'User' is not assignable to parameter of type 'Record<string, unknown>'.
  Index signature for type 'string' is missing in type 'User'.

接口可以通过声明合并来扩展，所以 TypeScript 不会假定它符合索引签名；类型别名无法重新打开，所以 type User = { name: string } 能通过检查。常见的修复方法有：改为接受 object（照样可以对它调用 Object.keys）、把函数写成泛型（<T extends object>(obj: T)），或者用 type 声明 User（interface 与 type 一文介绍了两者的其他区别）。

Record、索引签名与 Map 对比

只要键的集合是已知的，就选用联合类型作键的 Record：它是唯一能检查每个键都存在的方案。对于不固定的字符串键，Record<string, V> 和索引签名可以互换，很多代码库为了可读性更喜欢用 Record。当键会在运行时增删、键不是字符串，或者你需要直接拿到大小和插入顺序时，就用 Map。