TypeScript catch 变量为 unknown 时怎样安全处理

在开启 strict 后，下面这句代码经常会突然报错：catch (error) { console.error(error.message) }。原因不是 TypeScript 不认识 Error，而是 JavaScript 允许抛出任意值，catch 变量因此被当作 unknown。安全做法是先用运行时条件把它收窄成已知类型，再读取属性；如果遇到字符串、普通对象或 null，则走稳定的兜底摘要。

官方地址：https://www.typescriptlang.org/

先确认为什么 catch 变量变成 unknown

TypeScript 4.4 引入 useUnknownInCatchVariables 后，启用 strict 的项目会自动把未标注的 catch 变量按 unknown 处理。这个判断符合 JavaScript 的真实语义：下面三种写法都可以抛出，但它们并不都拥有 message 属性。

try {
  // 真实项目里，这里可能来自网络、解析器或第三方库。
  callRemoteService();
} catch (err) {
  // err 可能是 Error、字符串、普通对象，甚至 null。
  // 直接访问 err.message 会被 TypeScript 拒绝。
  console.error(err.message);
}

这项检查保护的是错误处理路径本身。若日志代码又因为错误形状不确定而抛出新异常，原始故障就会被覆盖，排查会更困难。先确认资产是“原始错误”和“可读摘要”，再决定哪些字段可以输出。

用 instanceof Error 处理最常见的错误对象

第一层守卫应该覆盖最常见的原生错误对象。进入 if 分支后，TypeScript 能把 err 收窄为 Error，此时访问 name、message 和可选的 stack 才有类型依据。

function errorMessage(err: unknown): string {
  // 只有确认是 Error 后，才读取它的标准字段。
  if (err instanceof Error) {
    return err.message || err.name;
  }

  // 其他类型暂时不暴露原始值，交给后续分支处理。
  return "发生了未知错误";
}

这里没有用类型断言把 err as Error 强行改名。断言只改变编译器的看法，不会改变运行时对象；当第三方代码抛出字符串时，断言后的 err.message 仍可能得到 undefined，甚至让后续逻辑再次失败。

再覆盖字符串、普通对象和 null

实际项目中，业务层可能抛出可读字符串，旧代码也可能抛出带 message 字段的普通对象。为了不把这类值误当成可信 Error，可以使用自己的类型守卫，只承认“非空对象且 message 是字符串”这一小块形状。

type MessageLike = { message: string };

function hasMessage(value: unknown): value is MessageLike {
  // 先排除 null，再确认对象和字段类型，避免访问空值属性。
  return typeof value === "object"
    && value !== null
    && "message" in value
    && typeof value.message === "string";
}

function summarizeThrownValue(err: unknown): string {
  // 原生 Error 优先保留 message，方便定位调用链。
  if (err instanceof Error) {
    return err.message || err.name;
  }

  // 只接受已确认是字符串的 message，不把任意对象拼进日志。
  if (hasMessage(err)) {
    return err.message;
  }

  // 字符串通常是业务代码直接 throw 的提示，可以保留但要限制长度。
  if (typeof err === "string") {
    return err.slice(0, 200);
  }

  // null、数字和未知对象统一使用固定摘要，保证日志调用不会再报错。
  return "发生了未知错误";
}

hasMessage 的价值不在于“猜测所有对象”，而在于把允许输出的边界写成可审阅的条件。对于来自跨窗口、序列化或不同 JavaScript realm 的错误对象，instanceof Error 可能不如结构检查稳定；两层守卫可以按项目的错误来源继续扩展。

把内部日志和用户提示分成两条路径

错误摘要适合进入日志或监控上下文，但它不一定适合直接展示给用户。网络地址、SQL 片段、文件路径和堆栈都可能包含内部信息，因此建议让 catch 块只负责记录受控字段，界面层使用固定提示或业务错误码。

async function loadProfile(): Promise {
  try {
    return await requestProfile();
  } catch (err: unknown) {
    // 日志保留可定位的摘要，不把未知对象直接 JSON.stringify。
    const summary = summarizeThrownValue(err);
    console.error("加载个人资料失败", { summary });

    // 用户只看到稳定文案，避免泄漏内部堆栈和请求细节。
    showToast("暂时无法加载资料，请稍后重试");
    return null;
  }
}

显式 any 只能作为局部兼容手段

如果某个旧库已经保证只抛出带固定字段的对象，可以在非常小的范围内写成 catch (err: any)，但这相当于主动放弃该处的保护。更稳妥的迁移顺序是：保留全局 useUnknownInCatchVariables，先封装一个摘要函数，再让少数无法改造的兼容边界独立记录原因。

常见问题

为什么不能直接把 catch 变量写成 Error？

因为 JavaScript 的 throw 没有要求值必须是 Error。把变量直接标成 Error 会掩盖字符串、普通对象和 null 等真实输入，应该先做运行时检查。

只写 err as Error 可以吗？

它只能消除当前编译错误，不能让运行时值真的变成 Error。除非边界已经有可靠的运行时保证，否则应优先使用 instanceof 或类型守卫。

关闭 useUnknownInCatchVariables 会更简单吗？

短期迁移可能更省事，但会让所有 catch 块重新获得 any 的宽松行为。通常更适合保留 strict，只在明确的旧接口兼容点局部放宽。