项目开着严格的类型检查,一个本该被拦住的类型错误却溜到了运行时才崩,排查发现是一个 any 沿着数据流一路传染、悄悄关掉了大片代码的类型保护,我对着 any 的传染性这个坑排查了大半天的复盘

这是一个让我对 TypeScript "类型安全到底靠不靠谱"重新审视的坑。它的可怕在于:我以为开了 TypeScript、开了严格模式,代码就被类型系统严严实实地保护着;可实际上,有一大片代码的类型检查,早已在我不知不觉中被一个 any 悄悄地、彻底地关闭了——它们看起来有类型、有提示,实则是"裸奔"。

事情起于一个本不该发生的运行时崩溃。一个访问对象属性的地方,访问了一个根本不存在的属性,运行时报 undefined 错误。我很困惑——TypeScript 不是应该在编译时就拦住这种错误吗?我顺着数据往回追,发现了那个"万恶之源":

// 数据来源: 一个返回 any 的地方(JSON.parse / 第三方库 / 偷懒的 as any)
const data = JSON.parse(jsonStr);   // ★ JSON.parse 返回 any!

// 然后这个 any 一路传下去:
const user = data.user;             // user 也是 any(any的属性还是any)
const profile = user.profile;       // profile 还是 any
const name = profile.fullName;      // name 还是 any
const len = name.length;            // len 是 any
processUser(profile);               // ★ 传给一个有明确类型参数的函数, 也不报错!

function processUser(u: User) {      // 期望 User 类型
    return u.nonExistentField;       // ★ 访问不存在的字段, 居然不报错!
    //                                  因为传进来的是 any, any 绕过了所有检查
}
// 整条链上, TypeScript 一个错都没报 —— 因为 any 把它们全"染"成了 any,
// 而对 any, TypeScript 【放弃了一切类型检查】!

真相让我脊背发凉。原来一切的源头,是 JSON.parse 返回的 any;而这个 any,像墨水滴进清水一样,沿着数据流一路扩散、传染:data 是 any,那 data.user 也是 any,user.profile 还是 any……整条链上的每一个变量,都被"染成"了 any。而对一个 any 类型的值,TypeScript 会彻底放弃类型检查——你可以访问它任何(不存在的)属性、调用它任何(不存在的)方法、把它传给任何类型的参数,编译器一概不报错。于是,我那一大片"看起来有 TypeScript 保护"的代码,实际上因为这个传染开来的 any,类型检查早已全线失效——它们和裸写 JavaScript 没有任何区别,bug 自然一路畅通无阻地溜到了运行时。我盯着这条被 any 染透的数据链,意识到问题的本质:我以为我在写有类型保护的 TypeScript,其实有一大块,是披着 TypeScript 外衣的、毫无保护的 JavaScript。

第一件事:看清真相——any 会传染,且对 any 类型 TS 放弃一切检查

我去深入理解了 any 这个类型在 TypeScript 里的特殊地位,才彻底明白这场"静默的类型保护沦陷"——any 是 TypeScript 类型系统里的一个"逃生舱/后门",它表示"关闭对这个值的类型检查";而它最危险的特性是"传染性":any 参与的几乎所有运算(取属性、传参、赋值)的结果,还是 any,于是它会顺着数据流不断蔓延,把沿途的类型检查一路关闭。

any 的传染性的真相

# 1. any 是什么: TypeScript 类型系统的"逃生舱"——
#    - 一个 any 类型的值, 意味着"我(开发者)放弃对它的类型检查"。
#    - 对 any, 你可以做任何操作: 访问任何属性、调用任何方法、传给任何类型,
#      TypeScript【全部不检查、不报错】。它等于在这里关掉了类型系统。

# 2. any 的【传染性】(最危险的特性):
#    - any 的属性, 还是 any:        data(any).user → any
#    - any 参与的运算, 结果还是 any:  any + 1 → any,  any.foo() → any
#    - any 可以赋值给任何类型(也接受任何类型):
#      const u: User = someAny;     // ✓ 不报错! any能赋给User
#    - → 一个 any, 会顺着"取属性、运算、赋值、传参"的数据流, 一路把
#      接触到的东西都"变成"any, 像病毒一样扩散。

# 3. 常见的 any 源头(它从哪进来的):
#    - JSON.parse() 返回 any
#    - 没加类型的第三方库(或 @types 缺失)
#    - 偷懒写的 as any / : any
#    - 没开 noImplicitAny 时, 没标类型的参数默认是 any(隐式any)
#    - catch (e) 的 e 旧版本是 any

# 4. 后果: 一个 any 进来, 沿数据流扩散, 让一整片代码的类型检查【静默失效】;
#    你以为有TS保护, 其实那片代码等于裸JS, bug到运行时才暴露。
#    —— 它不像编译错误那样显眼, 而是"悄悄地"让保护消失, 极其隐蔽。

# 5. 对比 unknown(any的安全替代):
#    - unknown 也能接受任何值, 但它【不传染、不能直接用】:
#      对 unknown, 你必须先【收窄类型(类型守卫/断言)】才能操作它,
#      否则 TS 报错。→ unknown 强制你"先确认类型再用", 安全。

# 核心: any是TS的逃生舱(对它放弃一切类型检查), 且有传染性(沿数据流把接触的都变成any),
#   一个any能让一大片代码的类型保护静默失效; 应极力避免any、用unknown替代、堵住any的源头。

真相大白,我幡然醒悟。原来 any 是 TypeScript 的一个"逃生舱/后门"——一个 any 类型的值,意味着"开发者放弃对它的类型检查";对 any,你可以访问任何属性、调用任何方法、传给任何类型,TS 全部不检查、不报错,等于在这里关掉了类型系统。而它最危险的是传染性:any 的属性还是 any、any 参与的运算结果还是 any、any 能赋给任何类型——于是一个 any 会顺着"取属性、运算、赋值、传参"的数据流,一路把接触到的东西都"变成"any,像病毒一样扩散。常见的 any 源头有:JSON.parse、没加类型的第三方库、偷懒的 as any/:any、没开 noImplicitAny 时的隐式 any、旧版 catch 的 e。后果是:一个 any 进来沿数据流扩散,让一整片代码的类型检查静默失效;你以为有 TS 保护,其实那片代码等于裸 JS,bug 到运行时才暴露——它不像编译错误那样显眼,而是"悄悄地"让保护消失,极其隐蔽。对比之下,unknown 是 any 的安全替代:它也能接受任何值,但不传染、不能直接用——对 unknown 必须先收窄类型才能操作,否则 TS 报错,强制你"先确认类型再用"。

第二件事:正解——用 unknown 代替 any,在边界处给类型,开严格模式堵住 any

搞懂了原理,正解就清晰了:用 unknown 代替 any(强制收窄后才能用),在数据进入系统的边界处给它真实类型,开 noImplicitAny/strict 堵住隐式 any,用 lint 禁止显式 any。

// ====== 正解一: 用 unknown 代替 any(它不传染、强制收窄) ======
const data: unknown = JSON.parse(jsonStr);   // ★ 标成 unknown, 而非任由它是 any
// const name = data.user.name;   // ❌ 编译错误! 对unknown不能直接取属性
// 必须先收窄类型才能用:
if (isUser(data)) {              // 类型守卫收窄
    const name = data.name;      // ✓ 此时 data 是 User, 安全
}

// ====== 正解二: 在"数据边界"处给真实类型(配运行时校验最佳) ======
// 用 zod 等在边界处既校验又得到类型(见"as断言"那篇):
import { z } from 'zod';
const UserSchema = z.object({ user: z.object({ profile: z.object({ fullName: z.string() }) }) });
const data = UserSchema.parse(JSON.parse(jsonStr));  // ✓ data 有了精确类型, 不是any
// → 从源头就把 any 转成了真实类型, any 无从扩散

// ====== 正解三: 开启严格模式, 堵住"隐式 any" ======
// tsconfig.json:
//   "noImplicitAny": true   // 没标类型、TS又推不出的, 报错(逼你标类型), strict里已含
//   "strict": true          // 一揽子严格选项, 强烈建议开
// → 让"不知不觉产生的隐式any"无处遁形

// ====== 正解四: 用 ESLint 禁止/警告显式 any ======
// @typescript-eslint/no-explicit-any: 禁止代码里写 : any / as any
// → 从团队规范层面, 把"显式any"也堵住; 实在要用时显式 disable 并写注释说明

// ====== 正解五: 给第三方库补类型 ======
// 安装 @types/xxx; 没有的话写 .d.ts 声明文件给它加类型, 别让它的返回值是any。

// ====== 实在要"逃生"时, 把 any 的影响"圈"在最小范围 ======
// 万不得已用any时, 立刻把它转成确定类型, 别让它流出去:
const raw = legacyApi() as any;
const result: Result = normalize(raw);   // 在这一处消化掉any, 之后都是Result类型
// → any 只存在于这一行, 不传染到后面

// 核心: 用unknown替代any(强制收窄)、在数据边界处用zod等给真实类型、开strict/noImplicitAny堵隐式any、
//   用eslint禁显式any、给第三方补类型; 万一要用any就把它圈在最小范围立刻转成确定类型, 别让它扩散。

修复的核心,是"用 unknown 代替 any、在边界处给类型、开严格模式堵 any"。正解一:用 unknown 代替 any——把 JSON.parse 的结果标成 unknown 而非任由它是 any;对 unknown 不能直接取属性,必须先用类型守卫收窄才能用,从而不会传染、强制你确认类型。正解二:在数据边界给真实类型——用 zod 在边界处既校验又得到精确类型,从源头把 any 转成真实类型、无从扩散。正解三:开严格模式——noImplicitAny/strict 堵住"隐式 any"。正解四:ESLint 禁止显式 any——no-explicit-any 从规范层面堵住 :any/as any。正解五:给第三方库补类型(@types/.d.ts)。万一要逃生:把 any 的影响圈在最小范围——用了 any 就立刻转成确定类型(const result: Result = normalize(raw)),别让它流出去传染。归根结底:用 unknown 替代 any、边界处给真实类型、开 strict 堵隐式 any、eslint 禁显式 any、给第三方补类型;万一要用就圈在最小范围立刻转成确定类型。

第三件事:类型安全相关的其他常见漏洞

排查后我把"以为有类型安全、其实漏了"的其他常见情况也系统梳理了一遍。

类型安全的其他常见漏洞

# 1. any 传染(本文): 类型检查静默失效。→ unknown/严格模式/堵源头。

# 2. as 类型断言: 强行断言, 骗过编译器(见"as"那篇)。→ 少用as, 用运行时校验。

# 3. 隐式any: 没开noImplicitAny时, 没标类型默认any。→ 开strict。

# 4. 外部数据没校验: API/JSON的类型只是"声明", 运行时未必符合。→ zod校验。

# 5. 非空断言 !: foo!.bar 强行说"它不是null", 错了运行时崩。→ 谨慎用, 先判空。

# 6. 结构化类型混用: 结构相同语义不同的类型互换(见"结构化类型"那篇)。→ 品牌类型。

# 7. 类型与运行时脱节: 类型是编译期的, 运行时被擦除; 类型对≠运行时数据对。

# 8. @ts-ignore / @ts-expect-error 滥用: 直接让TS对某行闭嘴。→ 慎用。

# 共同根源: TypeScript的类型检查, 提供了很多"逃生舱/后门"(any、as、!、@ts-ignore),
#   它们是为灵活性而留的, 但每用一个, 就在类型安全的防线上开了一个洞; 洞开多了, 防线就名存实亡。

# 核心: 类型安全是"程度"问题, 不是"有/无"——any/as/!/@ts-ignore 这些逃生舱每用一个就漏一个洞;
#   要尽量少开洞、用unknown+运行时校验+严格模式, 让类型保护真正严密而非名存实亡。

排查让我把类型安全的其他漏洞也梳理清了。一、any 传染(本文)。二、as 类型断言(强行骗编译器)。三、隐式 any(没开 noImplicitAny)。四、外部数据没校验(类型只是声明,运行时未必符合,用 zod)。五、非空断言 !(强行说不是 null,错了运行时崩)。六、结构化类型混用(品牌类型)。七、类型与运行时脱节(类型编译期擦除)。八、@ts-ignore 滥用。它们的共同根源是:TypeScript 的类型检查提供了很多"逃生舱/后门"(any、as、!、@ts-ignore),它们是为灵活性而留的,但每用一个就在类型安全的防线上开一个洞;洞开多了,防线就名存实亡。核心是:类型安全是"程度"问题不是"有/无"——这些逃生舱每用一个就漏一个洞;要尽量少开洞、用 unknown+运行时校验+严格模式,让类型保护真正严密。下面这张图,是这次 any 传染的成因与解法:

第四件事:any vs unknown 对照表

这次踩坑后,我把 any 和 unknown 的区别整理成一张表,需要"接受任意类型"时对照选。

这张表把 any 和 unknown 的取舍钉死了。核心是:any 和 unknown 都"能接受任意值",但本质相反——any 是"放弃检查、可随便用、会传染"(危险),unknown 是"保留检查、用前必须先收窄、不传染"(安全);当你需要"接收一个类型不确定的值"时,几乎总该用 unknown 而非 any。它给我的最大启发是:面对"类型不确定"这个现实需求,有两种截然不同的应对哲学:any 的哲学是"那就不管它的类型了,随便用,出事算我倒霉"(放任);unknown 的哲学是"它类型不确定,所以我暂时不让你用它,直到你明确地确认了它到底是什么类型"(审慎)。这其实体现了一个深刻的设计取向:对待"不确定/未知",更安全、更负责任的做法,不是"假装它确定、随便处理"(any),而是"承认它不确定、并强制在使用前先消除这个不确定性(收窄/校验)"(unknown);unknown 的设计,本质上是把"处理未知"这件事,从"开发者可选的自觉",变成了"类型系统强制的纪律"。这让我把"用 unknown 而非 any"上升为一种原则:当你不得不接收一个类型不确定的值时,选择那个"逼你先确认再用"的工具(unknown),而不是那个"放任你不确认就用"的工具(any);让"安全"成为强制的默认,而不是依赖自觉。用"强制确认"的 unknown 替代"放任不管"的 any——是写出真正类型安全的 TypeScript 的一个关键原则。

第五件事:为什么 any 的存在本身是一种"必要的妥协"

这次也让我理解了 any 为何存在、以及该怎么看待它。

这张表道出了 any 的"定位"。核心是:any 的存在是一种"必要的妥协"——TypeScript 要兼容海量已有的、无类型的 JavaScript,要支持从 JS 渐进迁移到 TS,就必须提供一个"暂时不管类型"的逃生舱(any);它不是设计失误,而是务实的取舍;但这个逃生舱有代价(每个 any 都是类型安全的一个洞且会传染),所以正确的态度是把它当"临时的、有借条的"应急出口,用了要尽快"还"(转成确定类型)。它给我的启发是:一个优秀的工具/系统,常常需要在"理想的严格"和"现实的灵活"之间做妥协——它会提供一些"打破自己规则的后门"(any 之于类型系统、unsafe 之于内存安全、reflection 之于封装),以应对现实世界的复杂和过渡需求;这些后门是必要的,但用它们就是在"借用未来的债"——暂时绕过了规则带来的麻烦,却欠下了"失去规则保护"的债,迟早要还(以 bug 或重构的形式)。这让我对待这类"后门"有了清醒的态度:理解它们存在的合理性(不一味排斥),但使用时心怀警惕、明确这是在欠债、并尽量把债圈小、尽早还清;一个健康的代码库,不是"从不用后门"(有时不得不用),而是"用得克制、用得自觉、欠的债都记着并尽快还"。把 any 这类"逃生舱"当作"要还的债"来审慎使用——是这个 any 传染坑,教给我的、关于"如何对待工具的后门"的成熟态度。

第六件事:遇到"类型不确定"时,我现在的判断习惯

现在每当我遇到一个"类型不确定/任意类型"的值,我都会按这张图先想清楚:

这张图的精髓,是"类型不确定的值用 unknown+边界校验,绝不放任 any 扩散"。外部数据标 unknown 并在边界用 zod 校验出真实类型、第三方补 @types、想写 any 时停下改用 unknown 或真实类型;实在绕不开必须用 any 就圈在最小范围立刻转成确定类型,并开 strict/noImplicitAny + eslint 禁 explicit-any。这套习惯,让我面对不确定类型时,从"图省事用 any 放任"变成了"用 unknown 逼自己确认、在边界给真实类型"——核心始终是:any 会传染让类型保护静默失效,用 unknown 替代、边界给类型、严格模式堵 any。

我立下的几条规矩

这场"any 传染让类型保护沦陷"的事故,换来了我写 TypeScript 时,刻进骨子里的几条铁律:

1. any 会传染。一个 any 沿数据流扩散,关掉一大片代码的类型检查。
2. 对 any,TS 放弃一切检查。它等于在那里关掉了类型系统。
3. 用 unknown 代替 any。unknown 不传染、强制收窄后才能用。
4. 在数据边界给真实类型。用 zod 等把外部数据校验成精确类型。
5. 开 strict/noImplicitAny。堵住隐式 any。
6. eslint 禁止显式 any。从规范层面堵 :any/as any。
7. 万一要用 any,圈在最小范围立刻转确定类型。别让它流出去传染。

附:一段亲眼对比 any 传染与 unknown 拦截的实验

口说无凭。下面这段代码,把"any 放任传染"和"unknown 强制拦截"并排对比,你能亲眼看到它们的天壤之别:

interface User { id: number; name: string; }

// ====== 1. any: 放任一切, 错误溜到运行时 ======
function withAny(jsonStr: string) {
    const data: any = JSON.parse(jsonStr);   // any
    const name: string = data.user.profile.fullName;  // ✓ 编译通过(any随便取)
    const n: number = data.foo.bar.baz;                // ✓ 编译通过(any随便取)!
    callWithUser(data);                                // ✓ 编译通过(any能传给任何参数)!
    return name.toUpperCase();                         // 运行时可能崩(name其实undefined)
}
function callWithUser(u: User) { return u.name.length; }
// → 上面一个编译错误都没有, 但全是隐患: 访问不存在的字段、传错类型, 全靠运行时碰运气

// ====== 2. unknown: 强制你确认, 错误在编译期被拦 ======
function withUnknown(jsonStr: string) {
    const data: unknown = JSON.parse(jsonStr);  // unknown
    // const name = data.user.name;   // ❌ 编译错误: 'data' is of type 'unknown'
    // callWithUser(data);            // ❌ 编译错误: unknown 不能赋给 User
    // ↑ TS 强制你: 必须先收窄/校验, 才能用!

    // 必须先用类型守卫确认:
    if (isUser(data)) {
        return data.name.toUpperCase();   // ✓ 此时 data 是 User, 安全
    }
    throw new Error("数据不是合法的User");
}
function isUser(x: unknown): x is User {
    return typeof x === 'object' && x !== null
        && typeof (x as any).id === 'number'
        && typeof (x as any).name === 'string';
}

// 核心: 同一个JSON.parse, 标成any则一路放行(错误溜到运行时), 标成unknown则TS处处拦截、
//   逼你先确认类型才能用——亲眼对比, any的危险和unknown的安全一目了然。

这段对比实验,是我这次踩坑后写下的"any/unknown 对照镜"。它把同一个 JSON.parse 的结果,分别标成 any 和 unknown,让你亲眼看到两条截然不同的命运:标成 any 的那个函数,访问不存在的字段(data.foo.bar.baz)、把它传给类型不符的参数(callWithUser(data))——TypeScript 一个错都不报,所有隐患全都畅通无阻地放行到运行时;而标成 unknown 的那个函数,你什么都还没干,光是想取个属性、想传个参,TypeScript 就立刻在编译期报错,逼着你必须先用类型守卫确认它到底是不是 User,才允许你用。这一正一反的对比,把"any 是放任的危险、unknown 是强制的安全"这个抽象的道理,变成了你能在编辑器里亲眼看到的红线(或没有红线)。这正是我想用这段代码,留给每个写 TypeScript 的人的核心方法:当你想真正理解两个相似但关键不同的概念(any vs unknown、== vs ===、let vs const)的区别时,最好的方式是把它们放在完全相同的场景下,写成并排的两段代码,然后观察它们表现出的不同(一个报错一个不报、一个崩一个不崩)。因为"区别"这个东西,在抽象的文字描述里("any 不检查、unknown 强制收窄")常常显得模糊、记不牢;而当你在同一个场景里亲眼看到它们一个放行、一个拦截的具体差异时,这个区别就会以一种鲜明、深刻、难忘的方式刻进你的认知。用"同场景并排对比"把相似概念的关键区别"逼显"出来——这份习惯,是我理解一切"看起来差不多、实则大不同"的概念时,最有效的法门。

写在最后

回头看,这场由"一个 any 的传染"引发的、类型保护静默沦陷的事故,真正教给我的,远不止"用 unknown 代替 any"这一个技巧。它让我对"安全/保护是一种需要持续维护的状态,而非一劳永逸的开关",有了一次深刻的体会。我栽跟头,根源是我对"类型安全"有一种"非黑即白、一劳永逸"的错觉:我以为"用了 TypeScript、开了严格模式",就等于给整个项目一次性地、永久地加上了类型保护的金钟罩,从此可以高枕无忧。我没有意识到,类型安全不是一个"开了就永远有"的全局开关,而是一种需要在每一处代码、持续地去维护和守护的"状态";它可以被一个不经意的 any(以及 as、!、@ts-ignore)在局部悄悄地撕开一个口子,而这个口子还会顺着数据流扩散,让保护的失效范围远超那一个点。这让我领悟到一个深刻的认知:很多"安全/保护/质量"的属性,都不是"有或无"的二元状态,而是"程度"的、且需要持续维护的;它们容易被局部的疏忽所破坏,且破坏往往是静默扩散的——一个 any 撕开类型安全、一个未校验的输入撕开安全防线、一处未测的代码撕开质量保障;而这些破坏,因为不报错、不显眼,会悄悄地积累,直到某天以故障的形式集中爆发。这其实是一个关于"守护系统健康"的普遍道理:一个系统的"健康/安全/质量",更像是需要持续打理的花园,而非一次建成的堡垒——它会因为一处处微小的、不起眼的疏忽(一个 any、一个跳过的校验、一个忽略的告警)而慢慢地、静默地侵蚀;守护它,需要的不是"一次性地建好防护",而是"持续地警惕每一个会撕开口子的疏忽、并及时堵上"。把类型安全(乃至一切系统健康属性)当成"需要持续守护、警惕静默侵蚀"的状态而非一劳永逸的开关——这,是我用一次 any 传染的事故,换来的、关于 TypeScript、也关于如何长期守护系统健康的、最朴素也最深刻的领悟。如果这篇复盘,能让你下次手痒想写 any 时,先停一下、改成 unknown 或写出真实类型,那我对着那条被 any 染透的数据链排查的这大半天,就值了。

—— 别看了 · 2026