tsconfig.json配置的TypeScript路径别名不生效，ts-node提示找不到模块

问题核心原因 #

TypeScript的paths配置仅用于编译阶段的类型校验和编辑器路径解析提示，不会修改编译后生成的JS代码中的实际导入路径，而ts-node默认没有集成路径别名的运行时解析能力，所以会出现找不到模块的报错。

解决方法 #

方案1：使用tsconfig-paths适配ts-node运行时（最常用） #

• 第一步：安装开发依赖

npm install -D tsconfig-paths

• 第二步：修改package.json中的启动命令，添加路径注册钩子

{
  "scripts": {
    "tsnode": "ts-node -r tsconfig-paths/register index.ts"
  }
}

修改后重新启动即可正常识别别名。

方案2：编译阶段直接替换路径（适合打包后直接运行的场景） #

如果需要tsc编译后的JS文件直接可运行，不需要额外依赖，可以使用路径转换插件在编译时直接把别名替换为相对路径：

• 第一步：安装开发依赖

npm install -D ttypescript typescript-transform-paths

• 第二步：在tsconfig.json的compilerOptions中添加插件配置

{
  "compilerOptions": {
    // 原有配置保留
    "plugins": [
      { "transform": "typescript-transform-paths" }
    ]
  }
}

• 第三步：编译时使用ttsc代替原生tsc命令即可。

其他配套配置注意事项 #

• 如果项目中使用Jest做单元测试，需要在jest.config.json中添加别名映射：

{
  "moduleNameMapper": {
    "^@app/(.*)$": "<rootDir>/$1",
    "^@api/(.*)$": "<rootDir>/api/$1",
    "^@database/(.*)$": "<rootDir>/database/$1",
    "^@dbOperations$": "<rootDir>/database/dbOperations/index.ts"
  }
}

• 确认tsconfig.json中添加了include配置，覆盖所有业务代码文件：

{
  "include": ["**/*.ts"],
  "exclude": ["node_modules"]
}

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