在 TypeScript 开发中，我们经常利用 tsconfig.json 中的 paths 属性来定义路径别名，以避免深层嵌套的相对路径（如 ../../../utils）。然而，TypeScript 编译器（tsc）仅负责类型检查和将源码转换为 JavaScript，并不会修改模块导入路径。这导致 Node.js 在运行时无法识别这些自定义别名，从而抛出"Module not found"错误。tsconfig-paths 正是为解决这一痛点而生的工具库，它让 Node.js 能够在运行时动态解析 tsconfig.json 中定义的路径映射。

核心原理

tsconfig-paths 通过挂接 Node.js 的模块加载机制（module._findPath 或加载器钩子），拦截模块路径请求。当匹配到 paths 中定义的模式时，它会自动根据 baseUrl 和映射规则计算出真实的物理路径，从而实现无缝加载。

快速集成

1. 安装依赖

# 使用 npm
npm install --save-dev tsconfig-paths

# 使用 pnpm
pnpm add -D tsconfig-paths

2. 配置 tsconfig.json

在项目根目录下确保路径映射已正确配置：

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@core/*": ["src/app/core/*"],
      "@lib/*": ["src/libraries/*"],
      "@env": ["src/environments/environment.ts"]
    }
  }
}

运行模式

命令行模式（常用）

通过 Node.js 的 -r (require) 参数预加载注册器：

# 运行编译后的 JS
node -r tsconfig-paths/register dist/index.js

# 结合 ts-node 运行 TS 源码
ts-node -r tsconfig-paths/register src/index.ts

# 指定特定的配置文件路径
TS_NODE_PROJECT=./config/tsconfig.build.json node -r tsconfig-paths/register dist/index.js

API 编程模式

如果需要在代码中动态加载或自定义逻辑，可以使用其提供的 API：

const tsConfigPaths = require("tsconfig-paths");

const configLoaderResult = tsConfigPaths.loadConfig();

if (configLoaderResult.resultType === "success") {
  const unregister = tsConfigPaths.register({
    baseUrl: configLoaderResult.absoluteBaseUrl,
    paths: configLoaderResult.paths
  });

  // 执行后续逻辑
  // ...

  // 如果需要停止拦截，调用 unregister
  // unregister();
}

常见应用场景配置

VSCode 调试配置

在 .vscode/launch.json 中集成，确保调试时路径解析正常：

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Debug App",
      "runtimeArgs": [
        "-r", "ts-node/register",
        "-r", "tsconfig-paths/register"
      ],
      "args": ["${workspaceFolder}/src/main.ts"],
      "env": {
        "TS_NODE_PROJECT": "${workspaceFolder}/tsconfig.json"
      }
    }
  ]
}

单元测试集成 (Mocha)

在测试脚本中直接引入注册器：

mocha -r ts-node/register -r tsconfig-paths/register 'test/**/*.test.ts'

高级 API 参考

函数名称	描述
loadConfig(cwd)	从指定目录加载并解析 tsconfig 配置文件。
createMatchPath(absoluteBaseUrl, paths)	创建一个同步的路径匹配函数。
createMatchPathAsync(...)	创建一个支持异步文件系统检查的匹配函数。
register(options)	全局注入 Node.js 模块系统，拦截 require 调用。

生产环境注意事项

在生产环境中，通常建议通过打包工具（如 Webpack, Rollup, esbuild）在构建阶段直接转换路径，这样可以减少运行时的开销。但在某些直接运行 Node.js 脚本或微服务架构中，tsconfig-paths 依然是保证开发与生产环境配置一致性的便捷选择。

如果发现路径映射未生效，请优先排查以下几点：

• baseUrl 是否相对于执行命令的工作目录（CWD）。
• paths 中的通配符 * 是否与导入语句完全匹配。
• 是否环境变量 TS_NODE_PROJECT 指向了错误的配置文件。