TypeScript 解析策略之痛：一个类型错误引起的“惨案”

2023-12-20 19:44:14

在软件开发中，我们经常会遇到需要引用外部模块的情况。而在 TypeScript 中，模块的解析策略决定了如何查找和加载这些外部模块。如果模块解析策略配置不当，则可能会导致代码编译错误、运行时错误，甚至难以维护的代码库。

本文将结合一个真实的案例，深入探讨 TypeScript 的模块解析策略，并提供实用的解决方案。

案例背景

在引用公司的某个埋点包以后，发现vscode一直找不对它正确的类型定义，同样tsc编译的时候，也提示该包的定义文件上没有xx事件。于是开始排查：

项目node_modules结构如下：

├── buried-sdk
│   └── src
│       └── type.d.ts
└── node_modules
    ├── buried-sdk
    │   └── dist
    │       └── index.d.ts

项目tsconfig.json文件配置：

{
    "compilerOptions": {
        "module": "commonjs",
        "moduleResolution": "node",
        "baseUrl": "./",
        "paths": {
            "buried-sdk": [
                "node_modules/buried-sdk/dist"
            ]
        }
    }
}

问题分析

从上面的配置可以看出，我们已经明确指定了 buried-sdk 包的路径别名为 "node_modules/buried-sdk/dist"，但是我们尝试在 src 代码中使用 buried-sdk 的时候，依然找不到它的类型定义。这表明我们的模块解析策略出现了问题。

经过进一步调查发现，当我们尝试使用 buried-sdk 包的时候，TypeScript 首先会按照 baseUrl 配置的值 "./"，从项目根目录开始查找。然而，buried-sdk 包的实际路径是 "node_modules/buried-sdk/dist"，这显然与 baseUrl 的配置不一致。

解决办法

为了解决这个问题，我们需要调整 TypeScript 的模块解析策略，使其能够正确地查找 buried-sdk 包的类型定义。

一种方法是将 baseUrl 配置为 "node_modules"，这样 TypeScript 就会从 node_modules 目录开始查找 buried-sdk 包。然而，这种方法可能会导致其他模块的路径解析出现问题。

另一种方法是使用路径别名。我们可以将 buried-sdk 包的路径别名 "buried-sdk" 配置为 "node_modules/buried-sdk/dist"，这样 TypeScript 就可以直接从指定路径查找 buried-sdk 包的类型定义。

修改后的 tsconfig.json 配置如下：

{
    "compilerOptions": {
        "module": "commonjs",
        "moduleResolution": "node",
        "baseUrl": "./",
        "paths": {
            "buried-sdk": [
                "node_modules/buried-sdk/dist"
            ]
        }
    }
}