如何搭配tsconfig-paths与ts-node使用 解决路径别名模块找不到报错

核心报错原因 #

• 路径映射规则和实际文件目录不匹配：当前baseUrl指向项目根目录，paths中@koki/*映射到根目录下的koki/*路径，但实际业务代码都存放在src目录下，模块解析时找不到对应文件。
• TypeScript 原生编译器tsc默认不会替换路径别名，即使开发环境运行正常，编译后的产物仍会保留别名引用，直接执行会报模块不存在错误。

分步解决流程 #

1. 修正tsconfig.json路径映射配置 #

你当前的项目结构可参考截图：

对应实际目录层级为：

项目根目录
├── src
│   ├── index.ts
│   └── koki.ts
├── tsconfig.json
└── package.json

修改compilerOptions中的paths配置，让别名指向src目录下的真实文件：

{
  "ts-node": {
    "transpileOnly": true,
    "require": ["tsconfig-paths/register"]
  },
  "compilerOptions": {
    // 原有其他配置保持不变
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"],
      "@koki/*": ["src/*"]
    }
  },
  "exclude": ["node_modules"],
  "include": ["./src/**/*.ts"]
}

注：如果后续你把koki相关代码放到src/koki/目录下，只需要把@koki/*的映射值改成["src/koki/*"]即可，import写法保持@koki/xxx不变。

2. 安装ts-node路径解析依赖 #

你配置中引用的tsconfig-paths/register需要手动安装到开发依赖，否则ts-node启动时无法加载路径解析逻辑：

npm install tsconfig-paths -D

安装完成后执行ts-node src/index.ts，即可正常运行代码，控制台输出计算结果3。

3. 配置编译阶段别名替换 #

解决开发环境运行问题后，还需要处理编译产物的路径替换问题，避免编译后执行报错，这里使用最通用的tsc-alias方案：

1. 安装依赖：

npm install tsc-alias -D

2. 修改package.json中的脚本命令，在tsc编译完成后自动执行路径替换：

{
  "scripts": {
    "dev": "ts-node src/index.ts",
    "build": "tsc && tsc-alias",
    "start": "node dist/index.js"
  }
}

执行npm run build后，tsc-alias会自动把dist目录下所有文件的别名引用替换为正确的相对路径，直接执行npm run start即可正常运行编译后的代码。

可选优化方案 #

如果不想额外维护tsconfig-paths配置，可以替换开发运行工具为tsx，它原生支持tsconfig的paths规则，零配置即可识别路径别名：

npm install tsx -D

将dev脚本修改为tsx src/index.ts，删除tsconfig中多余的ts-node配置块即可正常开发。

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