TypeScript any 和 unknown 的区别及用法

any 和 unknown 都能接受任何值。区别在于之后你能对这个值做什么：any 允许你做任何事，什么都不检查；而 unknown 在你证明这个值是什么之前，几乎什么都不让你做。

let a: any = "hello";
let u: unknown = "hello";

console.log(a.toUpperCase()); // HELLO: any allows every operation

// @ts-expect-error: 'u' is of type 'unknown'.
u.toUpperCase();

if (typeof u === "string") {
  console.log(u.toUpperCase()); // HELLO: u is a string inside this block
}

去掉 @ts-expect-error 那一行，u.toUpperCase() 就是编译错误 TS18046。typeof 检查把 u 收窄为 string，在那个代码块里，所有字符串方法都可以使用。

any 与 unknown 一览

用类型论的说法，unknown 是顶层类型（top type）：任何类型都可以赋给它，而它只能赋给 unknown 和 any。any 则是一个逃生口，两个方向都能赋值，除了 never 之外可以赋给任何类型。

any 会关闭类型检查

类型为 any 的值会被无条件信任。编译器接受拼写错误、错误的类型和不存在的属性，这些错误要到运行时才会暴露。

const user: any = { name: "Ada" };

const total: number = user.name; // compiles: any is assignable to number
console.log(typeof total);       // string

const city = user.adress;        // typo, still compiles
console.log(city);               // undefined

try {
  console.log(user.address.city); // compiles, throws at runtime
} catch (e) {
  console.log((e as Error).message);
}

输出说明了问题所在：一个标注为 number 的变量里装着字符串，最后一行抛出 Cannot read properties of undefined (reading 'city')。any 还会扩散。user.name 是 any，所以由它计算出的任何值也都是 any，一个没有类型的值可以在远离它进入代码的地方关闭类型检查。

unknown 要求你先检查

对于 unknown，在代码收窄这个值之前，编译器拒绝一切操作。收窄用的是普通的 JavaScript 检查，在每个分支里，值都具有被检查过的类型。

function describe(value: unknown): string {
  if (typeof value === "string") return `string of length ${value.length}`;
  if (typeof value === "number") return `number ${value.toFixed(2)}`;
  if (Array.isArray(value)) return `array of ${value.length}`;
  if (value instanceof Date) return `date ${value.toISOString()}`;
  if (value === null) return "null";
  if (typeof value === "object" && "id" in value) return `object with id ${String(value.id)}`;
  return typeof value;
}

console.log(describe("hi"));                               // string of length 2
console.log(describe(3.14159));                            // number 3.14
console.log(describe([1, 2, 3]));                          // array of 3
console.log(describe(new Date("2024-03-15T10:30:00Z")));   // date 2024-03-15T10:30:00.000Z
console.log(describe({ id: 7 }));                          // object with id 7
console.log(describe(undefined));                          // undefined

value === null 检查必须放在对象检查之前，因为 typeof null 是 "object"。经过 "id" in value 之后，TypeScript 知道这个对象有一个 id 属性，类型为 unknown，因为没有任何信息说明它装的是什么。String() 把它显式转换成文本；如果要把它当数字用，你得先用 typeof 检查它。

你也可以用断言 value as string 跳过检查，编译器会接受。但这只是一个承诺，背后没有任何运行时检查，所以最好使用真正的检查；参见类型断言。

用 unknown 校验 JSON

JSON.parse 被声明为返回 any，所以它的结果会悄悄关闭类型检查。把结果标注为 unknown，再写一个类型守卫，在其余代码信任它之前先检查它的结构。

interface Settings {
  theme: string;
  fontSize: number;
}

function isSettings(v: unknown): v is Settings {
  return (
    typeof v === "object" && v !== null &&
    "theme" in v && typeof v.theme === "string" &&
    "fontSize" in v && typeof v.fontSize === "number"
  );
}

const inputs = ['{"theme":"dark","fontSize":14}', '{"theme":"dark"}'];

for (const text of inputs) {
  const data: unknown = JSON.parse(text);
  if (isSettings(data)) {
    console.log(`${data.theme} at ${data.fontSize}px`);
  } else {
    console.log("invalid settings:", text);
  }
}

第一个输入打印 dark at 14px，第二个因为缺少 fontSize 而被拒绝。如果用 any，第二个输入就会作为一个 fontSize 为 undefined 的 Settings 一路传下去。对于大型结构，校验库能完成同样的工作，还能帮你推导出类型。

noImplicitAny

any 不只来自有人手写。一个既没有注解、也没有上下文可供推断的参数同样会是 any。noImplicitAny 选项（strict 会开启它）会把这种情况报告为错误：

// This does not compile: x has no type
function double(x) {
  return x * 2;
}

console.log(double(4));

index.ts(2,17): error TS7006: Parameter 'x' implicitly has an 'any' type.

解决办法是加上注解：function double(x: number)。显式写 x: any 也能通过编译，而这正是目的所在：any 在代码中保持可见，可以被搜索和审查。

any 仍然会悄悄混进来的地方

即使在 strict 下，下面这些情况也会产生 any，而你的代码里根本没出现这个词：

在 strict 下，catch 变量是 unknown，因为被抛出的可以是任何东西，不只是 Error 对象。读取 e.message 之前，先用 e instanceof Error 收窄它。

什么时候可以用 any

any 并没有被禁止，但每一处 any 都是编译器不再保护的地方。合理的用法有：

• 迁移 JavaScript 代码库时，用 any 标记还没加类型的部分。
• 类型系统难以表达的代码，保持很小的范围，并藏在一个有类型的函数签名后面。
• 故意传入错误数据的测试代码。

其他所有情况，unknown 都能覆盖同样的“我不知道这个类型”的场景，同时保留检查。很多团队用 @typescript-eslint/no-explicit-any 这条 lint 规则来强制执行这一点。一个相关的类型 Record<string, unknown> 是表示“值未知的某个对象”的常用写法。