从 any 到 unknown：TypeScript 类型安全实战指南

1. 从 any 到 unknown：一个"什么都不能做"的类型，为什么反而更安全

大概在三年前，我接手过一个内部数据中台项目，代码里密密麻麻全是 any。当时团队的理由很充分：后端接口字段不固定，文档也跟不上，不用 any 根本没法干活。后果也很真实——一个 user.profile.age.toFixed(2) 在运行时直接炸了，因为 profile 是 null，而 TypeScript 编译器全程没有给出任何警告，因为它已经被 any 吞掉了所有类型信息。

后来我做的第一件事，就是在项目里全面引入 unknown 替代 any。很多人第一次看到 unknown 的报错会觉得莫名其妙："这个类型不是可以接收任何值吗？为什么赋值给 string 都报错？" 对，这正是 unknown 设计的核心思路——它可以接收任何值，但你在证明它是什么之前，它什么都不是。

用大白话说：any 相当于你告诉编译器"这玩意儿我不管了，别烦我"，一路绿灯，但也失去了所有保护；unknown 则是"这玩意儿我暂时不知道是啥，但我会想办法搞清楚"，在这之前编译器会拦着你不让你乱用。两者的差距，就像把一包不明粉末直接倒进嘴里，跟先送去实验室化验之后再决定是吃还是扔的区别。

适合读这篇文章的人，我默认是已经熟悉 TypeScript 基础类型、写过一阵子业务代码，但还没系统整理过 unknown 用法的同学。我会从类型系统的约束、收窄手段、实战场景、泛型配合以及生产环境踩坑这几个方面，把这类型彻底讲透。

1.1 unknown 到底限制了什么：三条硬性规则

unknown 是 TypeScript 3.0 引入的，它作为 any 的类型安全对应物存在。要理解它，先看它对人有哪些限制。我总结为三条：

限制一：不能直接对 unknown 做任何操作。 数学运算、属性访问、函数调用、字符串拼接，全部报错。

typescript复制let value: unknown;

value.toFixed(2);        // 报错：对象的类型为 "unknown"
value.name;              // 报错：对象的类型为 "unknown"
value();                 // 报错：此表达式不可调用
`${value}`;              // 报错
value + 1;               // 报错

这其实是 TypeScript 编译器在逼你先把类型"证明"出来。在类型没有被收窄之前，unknown 就像一张白纸，你不知道上面有什么，自然不敢在上面写字。

限制二：unknown 只能赋值给 any 或 unknown 本身。 这是 unknown 和 any 最本质的区别之一。

typescript复制let u: unknown = "hello";
let a: any = "world";

let str1: string = a;    // 允许，any 可以赋给任何类型
let str2: string = u;    // 报错：不能将类型 "unknown" 分配给类型 "string"
let num1: number = u;    // 报错
let u2: unknown = u;     // 允许
let a2: any = u;         // 允许

这个规则看起来是限制，实际上是安全网。any 可以飞向任何地方，unknown 则必须先降落、经过检查才能继续行动。

限制三：unknown 之间的联合类型表现特殊。 在联合类型中，unknown 会"吞掉"其他所有类型，但 any 不会吞掉 unknown。这个放到后面的进阶部分细说。

1.2 any 的三大原罪，以及 unknown 如何对症下药

我整理了一个 any 和 unknown 的对比表，方便一眼看清差异：

any 的三大问题，我做了三年 TypeScript 感觉体会特别深：

第一，类型逃逸。一个 any 值会在类型系统中迅速扩散，看起来只是一个小变量，但经过函数参数、返回值、对象属性的传递，整个调用链全部沦为"不受管束"的状态。你用 any 是因为某个字段不确定，但后果是全项目的类型检查都形同虚设。

第二，掩盖真实错误。好比你把房间里的灰尘扫到了地毯下面，表面干净了，但问题没有消失。any 让代码在编译期绝对通过，但运行期该炸的还是会炸，而且炸得毫无预兆。

第三，破坏自动补全和重构。IDE 无法为 any 提供属性提示，所以 any 把代码补全、跳转定义、全局重命名这些基础能力全部废掉了。写代码像在黑暗里摸索，效率大打折扣。

unknown 针对这三点给出的解法是：保留"接受任意值"的灵活性，但把"使用值"的门槛提高。 你必须先证明它是什么类型，才能对它做对应类型的操作，编译期保护重新上线，IDE 提示也能正常工作了。

提示：如果项目中 any 已经泛滥成灾，我建议从新写的模块开始用 unknown 替代 any，不要试图一次性全部改完，后面专门有一节讲渐进式改造。

2. 收窄 unknown 的六种手段：从"它是什么"到"它就是它"

unknown 的核心矛盾在于：你要用它，就得先收窄它。TypeScript 里所有能对联合类型做收窄的手段，几乎都能用在 unknown 上，而且因为 unknown 是"全未知"，收窄的过程反而更典型。我在这里把实践中真正用到的六种手段一次讲清，每一种都会讲清楚"为什么这样能收窄"以及"收窄之后的坑"。

2.1 typeof 收窄：处理原始类型的首选

typeof 是收窄 unknown 最基础的手段，适合处理 string、number、boolean、symbol、bigint、function 等原始类型。

typescript复制function processValue(value: unknown) {
  if (typeof value === "string") {
    // 在这个分支里，value 被收窄为 string
    console.log(value.toUpperCase());
  } else if (typeof value === "number") {
    // 在这里，value 被收窄为 number
    console.log(value.toFixed(2));
  } else {
    console.log("无法处理的值");
  }
}

这里有一个很多人忽略的细节：typeof 检查对 null 的行为很特殊。typeof null === "object"，这是 JavaScript 从设计之初就存在的历史遗留问题。所以如果你写：

typescript复制function handle(value: unknown) {
  if (typeof value === "object") {
    // 这里 value 的收窄结果是 object | null
    // 注意：null 也满足 typeof === "object" 的条件
  }
}

TS 会诚实地把 value 收窄为 object | null，而不是单纯的 object。很多初学者在这里踩坑，误以为进到分支里就一定是对象，结果 null 也进来了。处理办法很简单，再加一个 value !== null 的判断，或者在分支内部先排除 null。

typeof 收窄还有一个坑：它只能区分"原始类型的大类"，不能区分具体的对象形态。比如 typeof value === "object" 时，你只知道它是个对象或 null，但不知道是数组、日期、Map 还是普通对象。这时候需要更精细的收窄手段。

2.2 instanceof 收窄：处理类实例的正确姿势

当 unknown 值大概率是某个构造函数的实例时，用 instanceof 最直接：

typescript复制function handleError(error: unknown) {
  if (error instanceof Error) {
    // 这里 error 被收窄为 Error，可以安全访问 message
    console.error(error.message);
  } else {
    console.error("未知错误", error);
  }
}

这段代码在项目里简直不要太常见，特别是 try/catch 中捕获的异常。TypeScript 4.4 之后，如果你开启了 useUnknownInCatchVariables（strict 模式下默认开启），catch 子句的变量类型就变成了 unknown，所以 error instanceof Error 就成了最家常便饭的收窄写法。

instanceof 的底层逻辑是沿着原型链查找，所以它对继承体系也能正确工作。比如 class MyError extends Error，myError instanceof Error 同样是 true，收窄为 Error 后访问 message、stack、name 都没问题。

还有一个小经验：如果项目里有自定义错误基类，我一般会先收窄到自定义基类，再收窄到具体错误子类，这样不同错误类型的处理逻辑可以分开。

2.3 in 操作符收窄：判断对象属性的利器

in 操作符在 TypeScript 中也可以用作类型守卫，它检查的是"属性是否存在于对象上"。对于 unknown 类型，先用 typeof === "object" 排除掉原始类型和 null，再用 in 来区分不同形态的对象，是非常经典的组合拳。

typescript复制type User = { name: string; age: number };
type Admin = { name: string; role: string; permissions: string[] };

function printInfo(data: unknown) {
  if (typeof data !== "object" || data === null) {
    console.log("不是对象");
    return;
  }

  if ("role" in data) {
    // 这里 data 的类型是 object & Record<"role", unknown>
    // 可以推断出它是某种具有 role 属性的对象
    console.log(data.role);
  }

  if ("age" in data) {
    // 同理，这里说明 data 上存在 age 属性
    console.log(data.age);
  }
}

in 收窄的一个局限是：它只能让你确定"属性存在"，而不能确定"属性的具体类型"。data.role 的类型是 unknown，访问可以，但要用还需要继续收窄。所以实际项目中，in 操作符通常和自定义类型守卫配合使用，先确认有某个属性，再通过守卫函数把整个对象断言成具体类型。

2.4 自定义类型守卫：收窄 unknown 的终极武器

自定义类型守卫函数（value is T）是 unknown 收窄中最灵活、最强大的工具。它的本质是把"类型检查逻辑"封装成一个函数，不仅复用性好，而且可以把复杂的运行时校验包装成类型安全的断言。

举个实际例子。我要判断一个 unknown 值是不是合法的用户对象：

typescript复制interface User {
  id: number;
  name: string;
  email: string;
}

function isUser(value: unknown): value is User {
  if (typeof value !== "object" || value === null) {
    return false;
  }

  const obj = value as Record<string, unknown>;

  return (
    typeof obj.id === "number" &&
    typeof obj.name === "string" &&
    typeof obj.email === "string"
  );
}

// 使用
function processUser(data: unknown) {
  if (isUser(data)) {
    // 收窄为 User，可以安全访问所有属性
    console.log(data.id, data.name, data.email);
  } else {
    console.log("数据格式不正确");
  }
}

这里有个关键细节：函数内部的 value as Record<string, unknown> 是为了绕过 unknown 无法访问属性的限制，把对象变成"可以用索引访问的形式"。这是一种在类型守卫内部很常见的技巧——你知道你正在做运行时验证，所以在这个函数体内部使用断言是合理且安全的。

类型守卫还有一个好处：它是可组合的。你可以把多个细粒度的守卫函数拼成一个大的守卫函数，层层验证，每个环节都有明确的职责。在解析复杂的嵌套 JSON 时，这种方式特别管用。

注意：自定义类型守卫要当心"撒谎"的情况。如果函数返回 true，但运行时值其实不满足 T 的结构，类型系统就会被欺骗，后续代码会踩坑。所以写守卫函数时，校验逻辑要足够严格，宁可保守，不能激进。

2.5 判等收窄：最容易被忽略的收窄方式

很多人不知道，单纯的 === 和 !== 比较也能收窄 unknown。当 unknown 与一个具体的 null、undefined 或者字面量值比较时，TypeScript 能从中推断出信息。

typescript复制function handle(value: unknown) {
  if (value === null) {
    // 这里 value 是 null
    return;
  }

  if (value === undefined) {
    // 这里 value 是 undefined
    return;
  }

  // 经过上面两个判断，value 已经被排除了 null 和 undefined
  // 可以放心使用
}

function handleString(value: unknown) {
  if (value === "success") {
    // 这里 value 会被收窄为字面量类型 "success"
    console.log("操作成功");
  }
}

判等收窄在排空时非常有用。特别是当你处理一个可能是 string | null | undefined | number 的 unknown 时，先排除 null 和 undefined，再排除 "特殊值"，剩下的类型面板就会越来越小，最终露出真实身份。

2.6 断言 as：最后的手段，也是最容易被滥用的手段

as 断言（类型断言）是收窄 unknown 的另一个途径，但它是一把双刃剑。

typescript复制let value: unknown = "这是一个字符串";

// 使用断言
const len = (value as string).length;

// 或者更简洁的写法
const len2 = (value as string).length;

as 的工作原理是：你告诉编译器"我知道它是什么，信我"。编译器默认相信你，不会做任何运行时验证。所以如果 value 实际上不是字符串，上面的代码在运行时会得到 undefined.length 的 TypeError。

我的建议是：

• 尽量用类型守卫和 typeof、instanceof 等收窄手段，而不是断言。 因为这些是"经过运行时验证之后才做出的类型判断"，更安全。
• 在不得不用断言时，配合运行时校验一起用。 比如先用 typeof 检查，再 as 断言，双保险。
• 断言只在很小的范围内使用。 如果一个 unknown 值经过一系列操作，你可以确定它的类型，但 TypeScript 推导不出来，这时用 as 是合理的。

还有一点特别重要：绝对不要用双重断言，也就是 as unknown as string 这种写法。这等于强制让编译器忽略所有类型信息，完全绕过了类型检查，和用 any 没什么区别了。如果代码里出现这种模式，通常是设计上出了问题，应该回头重新想想类型架构。

3. 实战演练：用 unknown 构建一个"零 any"的安全 JSON 解析器

前面讲了很多理论层面的东西，这一节我结合自己的项目经历，把 unknown 放进一个真实的场景里：解析不确定结构的 JSON 数据。

3.1 问题根源：JSON.parse 返回的是 any

JSON.parse 的 TypeScript 类型签名是这样的：

typescript复制JSON.parse(text: string): any;

也就是说，任何 JSON 字符串解析出来的结果类型都是 any。这在类型层面等于全盘放弃了检查。数据里有 name、有 age，但 age 到底是什么？name 又一定存在吗？编译器完全不关心。

于是项目里就经常出现这种代码：

typescript复制const data = JSON.parse(response);
console.log(data.user.name); // 编译通过，但如果 user 不存在，运行时直接报错

问题的本质是：JSON.parse 的结果天然是"未知的"，它本来就应该是一个 unknown，只是 TypeScript 的官方类型定义为了兼容历史代码，最终给成了 any。所以我们要做的就是自己包一层，把边界从 any 改成 unknown。

3.2 手写一个安全解析器

我的目标很简单：写一个 parseJSON 函数，它接受一个字符串，返回 unknown，并且在解析失败时返回 null 而不是抛异常。解析成功后，调用方再通过类型守卫一层一层收窄，拿到真正需要的数据。

typescript复制function parseJSON(text: string): unknown {
  try {
    return JSON.parse(text);
  } catch {
    return null;
  }
}

// 使用示例
const result = parseJSON(responseText);

if (typeof result === "object" && result !== null) {
  const obj = result as Record<string, unknown>;
  
  if (typeof obj.name === "string" && typeof obj.age === "number") {
    console.log(obj.name.toUpperCase());
    console.log(obj.age.toFixed(2));
  } else {
    console.log("数据结构不符合预期");
  }
} else {
  console.log("解析结果不是对象");
}

这个版本已经比直接 JSON.parse 安全多了。解析失败不会抛出未捕获的异常，得到的对象不会隐式为 any，所有字段访问之前都要经过守卫检查。

但这样写还是有点啰嗦。实际项目中，我会更进一步，封装一个通用的"验证对象字段"的工具函数，减少重复劳动：

typescript复制function isRecord(value: unknown): value is Record<string, unknown> {
  return typeof value === "object" && value !== null;
}

function isString(value: unknown): value is string {
  return typeof value === "string";
}

function isNumber(value: unknown): value is number {
  return typeof value === "number" && !Number.isNaN(value);
}

有了这几个基础守卫，业务代码可以写得更清爽：

typescript复制const result = parseJSON(responseText);

if (!isRecord(result)) {
  throw new Error("响应格式错误");
}

if (isString(result.name) && isNumber(result.age)) {
  // result.name 和 result.age 都是安全的
}

这里每写一步，类型都在收窄，编译器的检查能力全程在线。你可以直接复制这套模式到自己项目里，作为处理未知 JSON 数据的标配。

3.3 更进一步：用 unknown + 运行时校验构建类型安全的 API 响应处理

现在很多团队用 zod、io-ts 这类运行时校验库，它们做的事情本质上和 unknown 收窄是一样的：先承认数据是"未知的"，再通过一组 schema 校验和断言，让数据变得"已知"。unknown 是这一切的地基。

就算你不用这些库，只在内部项目里手写守卫函数，unknown 也是绕不开的起点。因为任何运行时校验库的 parse 方法输入参数类型都是 unknown，输出才是具体类型。

举一个用 zod 的示例（如果你没用过 zod，跳过这段也不影响理解）：

typescript复制import { z } from "zod";

const UserSchema = z.object({
  id: z.number(),
  name: z.string(),
  email: z.string().email(),
});

const result = UserSchema.parse(parseJSON(responseText));
// 此时 result 已经被推断为 { id: number; name: string; email: string }

这套模式之所以流行，核心原因就是：它把"数据来自外部，不可信"这件事当成默认前提，先收窄成 unknown，再通过 schema 恢复类型安全。 而直接 JSON.parse + as User 的旧写法，在遇到脏数据时，类型系统完全不会给你任何帮助。

4. 进阶：unknown 在泛型、联合类型与条件类型中的特殊表现

unknown 不只是用来收窄的，它在类型系统更深层的位置也有独特的行为。这一节讲几个进阶场景，理解了它们，你才算真正懂 unknown。

4.1 unknown 与联合类型：谁吞噬谁？

先看几个类型运算的结果：

typescript复制type T1 = unknown | string;       // unknown
type T2 = unknown | number;       // unknown
type T3 = unknown | any;          // any
type T4 = unknown | never;        // unknown

unknown 在联合类型中表现得像"最大集合"，所以除了 any 和 never，任何类型和 unknown 联合，结果都是 unknown。原因很好理解：联合类型表示"可能是其中之一"，而 unknown 表示"可能是任何值"，已经涵盖了所有可能性，但 any 特殊，因为 any 本身就兼容一切，它们两个兜在一起变成了怪异的 any。

这个知识有什么实际用途？在写泛型工具类型时，如果你要构造一个"必须能接受任意值"的类型，用 unknown 而不是 any，在某些场景下联合之后的行为会更可控。反过来，如果你看到某个工具类型返回了 unknown，它实际上是在表达"无法从这个输入中确定更具体的类型"。

4.2 unknown 与交叉类型：交集的特殊情况

交叉类型（&）和联合类型相反，它表示"同时满足所有约束"。

typescript复制type T1 = unknown & string;       // string
type T2 = unknown & number;       // number
type T3 = unknown & { name: string }; // { name: string }

交叉类型中，unknown 表现得像"最小集合"，它像一个空操作符，不改变交集结果。这从集合论上也非常自然：一个未知集合与某个具体集合的交集，自然就是那个具体集合。

实际应用：当你用泛型约束时，T & unknown 基本等价于 T，所以 unknown 常常作为泛型默认类型出现在"如果有更具体的类型就用更具体的，没有就用 unknown"的场景里。

4.3 条件类型中的 unknown：extends 判断的方向

在条件类型里，unknown extends T 这个判断的结果非常有趣。因为 unknown 是"最大集合"，所以 unknown extends T 只有在 T 是 unknown 或 any 时才为 true（any 也满足因为 any 特殊）。这可以用来判断一个泛型参数是否"完全未知"。

typescript复制type IsUnknown<T> = unknown extends T
  ? [T] extends [null]
    ? false
    : true
  : false;

type Test1 = IsUnknown<unknown>;   // true
type Test2 = IsUnknown<string>;    // false
type Test3 = IsUnknown<never>;     // false

注意这里我用了 [T] extends [null] 的写法来避免 never 被特殊情况吞噬。unknown extends never 为 false，但为了防止 never 在条件类型中的分发行为干扰判断，我把 T 包进了元组。这是条件类型里的一个经典技巧。

这个 IsUnknown 工具类型有什么用？你在写一些底层库、对泛型参数做分类处理时，需要判断"用户传进来的到底是不是未知值"，这时它就能派上用场。

4.4 unknown 作为泛型默认值的优势

泛型参数经常会有一个默认类型。最常见的做法是 T = unknown，这比 T = any 要安全得多。

typescript复制function identity<T = unknown>(value: T): T {
  return value;
}

// 调用时不传泛型参数，T 就是 unknown
const result = identity("hello"); // 这里实际是 string 推导，因为参数给了字符串

为什么说 unknown 比 any 好？因为如果默认是 any，调用方忘记传入泛型参数时，函数内部的 value 就变成了 any，所有操作都失去检查；而默认是 unknown 时，value 虽然是 any 推导出来的，但如果你需要操作 value，编译器会要求先收窄。

更常见的一个模式是"先给一个未知值，后续通过回调或映射把它转换为具体类型"：

typescript复制function parseData<T = unknown>(
  raw: unknown,
  parser: (data: any) => T
): T {
  return parser(raw);
}

const user = parseData(rawData, (data) => {
  // 这里你可以自己控制如何解析 data
  return { id: String(data.id), name: String(data.name) };
});

在这个模式里，T = unknown 保证了在使用方没有指定类型时，返回值的类型不会被悄悄放宽成 any，而是保持"未知"，逼着使用方显式处理。

5. 生产环境踩坑记录：那些官方文档里不会写的细节

纸上谈兵说了这么多，真正到了生产环境，unknown 还有一些边角细节非常容易踩坑。这里我把自己在项目中实际遇到的问题整理成了几个典型案例，每个都是"血泪教训"换来的。

5.1 坑一：JSON.stringify 对 unknown 的序列化结果，不是你想象中的"原样保留"

JSON.stringify 的 TypeScript 类型签名接受 any，所以把 unknown 类型传给它不会报错：

typescript复制function toJSON(value: unknown): string {
  return JSON.stringify(value);
}

但 JSON.stringify 对 undefined、function、symbol 这几个特殊值，会直接返回 undefined（注意不是字符串 "undefined"），而且如果对象内部包含循环引用，会抛出 TypeError。所以"把 unknown 序列化成 JSON 字符串"这一步，看起来简单，实际上有一堆边界情况。

我的建议是永远不要直接 JSON.stringify(unknownValue) 后就拿去用，最好先显式处理边界：

typescript复制function safeStringify(value: unknown): string {
  try {
    const result = JSON.stringify(value);
    if (typeof result === "undefined") {
      return "null";
    }
    return result;
  } catch {
    return "null";
  }
}

这里 typeof result === "undefined" 判断的是 JSON.stringify 返回的原始 undefined，它只在序列化 undefined、函数、Symbol 时会出现。把它变成 "null" 之后，调用方就能安全地把结果当作 JSON 字符串处理了。

5.2 坑二：catch 子句中的 unknown 与 Error 的继承链

TypeScript 4.4 之后，严格模式下 catch 变量默认是 unknown，这本来是好事，但带来一个非常常见的报错：

typescript复制try {
  someRiskyOperation();
} catch (error) {
  // 直接访问 message 会报错
  console.log(error.message); // 报错：error 的类型是 unknown
}

最直接的解决办法就是 error instanceof Error，前面已经提过。但在实际项目中，我发现很多第三方库抛出的错误并不是 Error 的实例——有的抛字符串，有的抛对象，有的抛 { code: 500, message: "xxx" } 这种结构。所以 instanceof Error 并不能覆盖所有情况。

我实践中通常这样处理：

typescript复制try {
  someRiskyOperation();
} catch (error) {
  if (error instanceof Error) {
    console.log(`标准错误：${error.message}`);
  } else if (typeof error === "string") {
    console.log(`字符串错误：${error}`);
  } else if (error && typeof error === "object" && "message" in error) {
    // 注意：error 可能是 null，所以要先判空
    const msg = (error as { message: unknown }).message;
    console.log(`对象错误：${String(msg)}`);
  } else {
    console.log("未知错误");
  }
}

这一套下来基本能覆盖绝大多数异常来源，不会漏掉信息。我把它封装成一个 getErrorMessage 函数放在项目工具库里，全项目统一用，减少重复代码。

5.3 坑三：unknown 与第三方库的类型冲突

有些第三方库的类型定义里，函数的入参类型是 any 而不是 unknown。当你把一个 unknown 类型的值传给它时，TypeScript 会直接报错，因为 unknown 不能赋值给 any 以外的类型。

但实际上，unknown 赋值给入参类型为 any 的函数是允许的，问题出在库的类型定义声明方式上。比如某些库声明了 function paint(options: Record<string, any>): void;，你传一个 unknown 就会报错。但如果你先断言成 Record<string, unknown>，再传给 Record<string, any>，又会因为 unknown 与 any 的兼容性在某些情况下报奇怪的错误。

这类问题最稳妥的解法是：在调用第三方库的边界处，做一次显式收窄，而不是用 as any 强制绕过。比如：

typescript复制function callThirdParty(raw: unknown): void {
  if (typeof raw !== "object" || raw === null) {
    throw new Error("参数必须是对象");
  }

  // 到这里，raw 已经是 object，且非 null
  // 但第三库的类型是 Record<string, any>
  // 此时用断言是合理的，因为我们已经做了运行时验证
  thirdPartyLib.paint(raw as Record<string, any>);
}

有人说这不还是用了 any 吗？是，但区别在于：你是在一个"已验证边界"处做了一次尽量小范围的类型妥协，而不是让 any 在整个项目里自由流通。 边界内的代码仍然保持严格的类型检查。

提示：遇到第三方库类型和 unknown 打架时，先冷静找"谁在阻止类型流动"，通常问题出在库的设计上，而不是你的代码。必要时给库提 PR 或自己写类型包装，但不要轻易用 as any 大杀器。

5.4 坑四：unknown 不适用于所有场景

unknown 好归好，但它不是银弹。有些场景下它反而会增加不必要的复杂度。

最典型的是内部函数之间的数据传递。如果一层一层的函数签名都是 unknown，那么每一层调用都要做收窄，代码会变得极其啰嗦。正确的做法是：在系统的"边界处"使用 unknown（API 入口、文件读取、事件处理等），一旦数据进入系统内部，就应该尽快收窄成具体类型，让核心业务代码在类型安全的环境下运行。

另一个场景是性能敏感的热路径。多写几个运行时守卫函数虽然通常不会有明显的性能问题，但如果一个函数被调用几百万次，每次都有大段的 typeof 校验，基准测试下是能看到差异的。正确思路是尽量把校验提前，减少在高频调用路径上的运行时类型检查。

第二个场景我实际遇到过。之前优化过一个日志解析模块，每条日志进来都要做十几次 typeof 判断，一小时内处理几亿条日志时，CPU 占用因此多了好几个百分点。最后我们把"判断日志格式"从热循环里抽出来，缓存在内存里，只对第一次出现的格式做全量检查，之后就跳过检查直接处理，性能就正常了。

这些经验说明了一件事：unknown 是工具，不是目的。在边界处用它兜底，在内部尽快收窄到具体类型，才是正确的工程姿势。

6. 团队落地指南：把 unknown 从"个人偏好"变成"团队规范"

最后聊聊怎么让一个团队从"any 佛系写代码"过渡到"unknown 优先"。我在多个项目里推动过这个转型，有一些成功经验可以分享。

6.1 用 ESLint 规则强制约束 any

改动习惯，先从编译器和规则层面动手最有效。我推荐配置这样几条 ESLint 规则：

json复制{
  "extends": [
    "eslint:recommended",
    "plugin:@typescript-eslint/recommended-requiring-type-checking"
  ],
  "rules": {
    "@typescript-eslint/no-explicit-any": "warn",
    "@typescript-eslint/no-unsafe-assignment": "warn",
    "@typescript-eslint/no-unsafe-member-access": "warn",
    "@typescript-eslint/no-unsafe-call": "warn",
    "@typescript-eslint/no-unsafe-return": "warn",
    "@typescript-eslint/no-unsafe-argument": "warn"
  }
}

这些规则的作用是：一旦代码里出现 any 相关的赋值、访问、调用、返回，立刻在 IDE 里给出黄色波浪线。不要一开始就设成 error，否则团队成员会抱怨"没法干活"然后集体反对。先 warn，让大家逐渐意识到问题，再慢慢收紧。

注意，@typescript-eslint/recommended-requiring-type-checking 需要项目启用了类型检查，配置起来稍微麻烦一点，但为了这些 no-unsafe-* 规则是值得的。

6.2 渐进式改造策略：先做新代码，再清老代码

我总结了一套三步走的方案，亲测有效：

第一步：新代码零 any。 从某个时间点开始，所有新增代码不允许出现 any，用 unknown 或者其他具体类型替代。这一步最容易执行，只要在 code review 时盯着即可。

第二步：高风险模块优先迁移。 把那些解析外部输入、处理通信边界、涉及用户数据的模块挑出来，优先把 any 替换成 unknown，因为它们是运行时最容易炸的地方。

第三步：存量代码逐步清扫。 利用 IDE 的全局搜索找出所有 any，按文件、模块分批处理。这一阶段最耗时，所以可以把 ESLint 的规则从 warn 升级为 error 来推动处理。

这套方案的核心是"先把水坝建好，再排库里的积水"。如果一开始就试图把全部存量代码一次性改完，很可能会因为工作量太大而中途放弃，反而什么都没改。

6.3 unknown 代表的类型思维转变

最后说点虚的，但我觉得这才是最关键的。

unknown 不只是多了一个类型关键字，它背后是一种工程态度的转变：承认"我们不知道的东西"，然后想办法把"不知道"变成"知道"。 这种思维放在现在的前端/Node 生态里特别重要，因为我们的代码越来越频繁地与外部世界交互：第三方 API、用户输入、配置文件、远程数据、微服务的响应……

每一次交互，都是一次信任边界。在信任边界上，我们应该默认使用 unknown，而不是默认使用 any。any 意味着"无条件信任"，unknown 意味着"先验证再信任"。对于银行转账、订单状态、用户权限这类数据，先验证再信任才是成熟工程师的做事方式。

我在实际项目中还有一个体会：unknown 会让代码 review 的质量上一个台阶。以前大家看到 any 就跳过，反正编译器都不管，review 的人也不管。现在代码里出现 unknown，就一定会有人问："这里是干什么的？为什么类型是未知的？要不要收窄成具体类型？"这种讨论本身，就是对代码质量的一种投资。

如果你正在经历"满屏 any"到"逐渐类型安全"的转型期，我想说的是：这个过程会有点痛，初期你会发现代码量变多了、要写的守卫函数变多了，但这些"多余"的代码，恰恰是运行时不出 Bug 的原因。坚持下来，值得。