编译TypeScript后出现Cannot find module '@utils'错误求助

核心问题是：TypeScript的路径别名（如@utils）仅在编译阶段被TS识别，编译后的JS文件仍保留@utils标识，但Node.js默认无法解析这类别名，导致找不到模块。以下是具体排查和解决步骤：

1. 验证tsconfig.json的路径配置 #

先确认tsconfig.json里的baseUrl和paths是否正确映射了@utils：

{
  "compilerOptions": {
    "baseUrl": "./src", // 指向源码根目录
    "paths": {
      "@utils/*": ["utils/*"] // @utils对应src/utils下的文件
    },
    // 其他编译配置...
  }
}

确保baseUrl和paths的路径与你的项目文件结构完全匹配，比如src/utils文件夹确实存在。

2. 让Node.js能识别路径别名 #

有两种常用方案解决编译后别名无法解析的问题：

方案一：用tsconfig-paths动态解析 #

• 安装依赖：

  npm install tsconfig-paths --save-dev
  

• 修改package.json的启动脚本，启动时加载tsconfig-paths：

  "scripts": {
    "start:prod": "node -r tsconfig-paths/register dist/server.js"
  }
  

  这样Node.js启动时会自动根据tsconfig的路径配置解析@utils。

方案二：用tsc-alias编译时替换别名 #

• 安装依赖：

  npm install tsc-alias --save-dev
  

• 修改编译脚本，在TS编译完成后替换别名：

  "scripts": {
    "build": "tsc && tsc-alias"
  }
  

  执行npm run build后，dist目录下的JS文件里的@utils会被替换成实际的相对路径，Node.js可以直接识别。

3. 检查文件结构与导入路径 #

确认src/utils目录存在，且你在app.ts/server.ts里的导入语句（如import { xxx } from '@utils/xxx'）对应的文件确实存在于src/utils/xxx.ts。

4. 清理缓存重新编译 #

• 删除旧的dist目录：

  # Mac/Linux
  rm -rf dist
  
  # Windows
  rd /s /q dist
  

• 重新编译并启动：

  npm run build
  npm run start:prod
  

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