Node.js 下 TypeScript 路径别名 (paths) 编译无效及 tsconfig-paths 调试排查

背景

在纯 Node.js 开发环境中，直接使用 tsc 命令编译 Node.js 项目。源码存放于 src 目录，编译输出至 bin 目录。项目代码结构如下：

• src
  • utils
    • a.ts
    • b.ts
  • config
  • …
• bin
• tsconfig.json

在深层级目录中引用 utils 或 config 下的文件时，必须编写冗长的相对路径如 '../../../../'，这不仅繁琐且易出错。对于熟悉 webpack 别名功能的开发者而言，TypeScript 作为成熟框架理应支持类似特性。经搜索，找到如下配置方法：

{
    "baseUrl": "./",                             
    "paths": {
      "@utils/*": [
        "src/utils/*"
      ],
      "@config/*": [
        "src/config/*"
      ],
    }
}

完成配置后，采用以下方式引用 a.ts 模块：

import A from '@utils/a';

此时 VSCode 编辑器已能识别该路径，按下 Ctrl 并点击路径可自动跳转至 a.ts 文件。在确认编辑器功能正常后，将所有深层级路径替换为上述写法，随后自信地执行 npm run start 命令：

运行结果令人困惑。检查 bin 目录下的编译后 JS 文件，发现 TypeScript 并未按配置优化路径，编译后的代码仍保留为 require('@utils/a') 形式：

TypeScript 编译器默认不对路径别名进行转换处理

在反复确认 tsconfig 配置无误后，再次搜索发现 typescript 本身不处理别名，需借助第三方编译工具如 babel 或 webpack 来实现。

然而，对于简单的 Node.js 项目，仅使用一种编译器即可，无需引入额外编译工具。因此，另一个解决方案（较为取巧）应运而生：

https://github.com/dividab/tsconfig-paths

另一个潜在问题

正是上述工具 tsconfig-paths。查阅其 GitHub 页面，该项目拥有约 1k 星标。阅读插件介绍可知，其设计初衷正是为了解决此问题。使用说明简洁，官方文档仅一句话：

只需通过 -r 指令添加预处理，再运行编译后的模块即可解决问题？满怀期待地执行 npm i --save 命令后，发现仍出现以下错误：

此次确认已执行预处理逻辑。为何仍不生效？查阅文档也未找到有用信息。此时多数开发者可能已放弃，但既然已投入时间，便决定深入源码调试以查明原因。

调试 tsconfig-paths 源码

配置 VSCode 调试器，添加运行参数：

 {
       "type": "pwa-node",
        "request": "launch",
        "name": "Launch Program",
        "skipFiles": [
            "<node_internals>/**"
        ],
        "runtimeArgs": [
            "-r",
            "${workspaceFolder}/node_modules/tsconfig-paths/register"
          ],
        "program": "${workspaceFolder}\\bin\\index.js"
  }

调试源码后发现，其核心功能是读取 tsconfig 文件获取 paths（别名）映射，覆写 path._resolveFilename 方法以匹配映射并解析真实模块。逻辑并不复杂。

在此处设置条件断点，定位到 utils/common 模块请求时，发现 found 变量为空……问题根源即在此。进一步追踪发现，其匹配规则无误，但在匹配后查找模块时使用的路径却是原始 tsconfig 中配置的 src 目录：

当前运行目录明明位于 bin 目录！

这显得不够智能，至少应读取 tsconfig 中的 outDir 属性。

鉴于无法修改该库代码，为适配其行为，只能修改 tsconfig 的 paths 配置如下：

{
    "baseUrl": "./",                             
    "paths": {
      "@utils/*": [
        "src/utils/*",
        "bin/utils/*"
      ],
      "@config/*": [
        "src/config/*",
        "bin/config/*"
      ],
    }
}

如此配置后，该库在拼接路径时即可正确找到模块，问题得以解决。

总结

至此，关于 TypeScript 在 Node.js 下使用别名 (paths) 无效问题的详解介绍完毕。如需了解更多相关内容，请搜索本站历史文章或继续浏览后续文章，感谢支持。