TypeScript旧项目出现‘unknown类型无法赋值’错误的排查与解决

问题概述 #

我有一个多年前可正常运行的TypeScript项目，期间升级了系统环境，近期重新构建时频繁遇到如下类型错误：

"Type 'unknown' is not assignable to type '$some_type$'"

我知道可以通过类型断言修正赋值语句，但想明确报错的根本原因，以及是否存在无需修改业务代码、仅通过配置就能解决的方案。

当前tsconfig.json配置 #

{
    "compilerOptions": {
        "target": "es6",
        "module": "amd",
        "allowJs": true,
        "moduleResolution": "node", 
        "outDir": "out", 
        "sourceMap": true, 
        "baseUrl": "./src", 
        "strict": false,
        "strictNullChecks": false,
        "noImplicitAny": false,
        "typeRoots": [
            "./node_modules/@types"
        ],
        "paths": { 
            "%COMMON/*": [ 
                "../../common/*" 
            ]
        }
    },
    "include": [ 
        "src/**/*"
    ],
    "exclude": [ 
        "node_modules", 
        "**/*.spec.ts"
    ],
    "lib": [ 
        "es2016",
        "dom",
        "es5"
    ]
}

报错示例 #

原本可正常运行的代码：

let texName: string = obj["texture"];

现在必须添加类型断言才能通过编译：

let texName: string = <string>obj["texture"];

其中obj是类型为Object的参数，示例类定义如下：

export class LeafNode  {
    protected meshName: string;
    protected material: Material;
    protected textureName: string;
    protected numIndicesToDraw: number;
    protected textureMatrix: mat4;
    protected eps: number = 0.000001;

    /* 其他方法 */
}

报错原因 #

核心原因是TypeScript版本升级后，对Object类型的索引访问返回值类型的处理逻辑发生了变化：

• 旧版本TypeScript中，访问Object类型的属性时，即使没有明确的索引签名，编译器会宽松地推断返回值为any类型；在你当前noImplicitAny: false的配置下，any可以直接赋值给任意类型，因此不会报错。
• 新版本TypeScript（尤其是4.x及以后版本）对类型检查的严谨性提升，访问Object类型的属性时，由于Object内置接口没有定义索引签名，编译器会将返回值推断为unknown类型。unknown是TypeScript中最严格的类型之一，不能直接赋值给string、number等具体类型，因此触发了赋值错误。

无需修改业务代码的解决方案 #

• 方案1：添加全局类型扩展（推荐）
  在项目的src目录下创建一个global.d.ts文件，扩展Object接口的索引签名，让编译器将Object类型的属性访问推断为any：

declare global {
  interface Object {
    [key: string]: any;
  }
}

export {};

这个文件会被TypeScript自动识别，无需修改任何业务代码即可恢复旧版本的类型推断行为。

• 方案2：降级TypeScript版本
  如果你的项目对新版本TypeScript的特性没有依赖，可以将TypeScript版本降级到与项目最初开发时一致的版本（比如3.x系列），这样编译器会回到旧的类型推断逻辑。

• 方案3：调整tsconfig配置（有限生效）
  尝试添加以下配置到compilerOptions中，抑制相关类型检查错误：

"suppressImplicitAnyIndexErrors": true

该配置会抑制当访问无索引签名对象的属性时产生的隐式any类型错误，但仅在编译器推断为any时生效；如果编译器已经推断为unknown，此配置可能无法解决问题，因此仅作为备选方案。

内容的提问来源于stack exchange，提问作者echelon