VSCode调试TypeScript时模块解析失败：找不到@common模块

迁移目录结构后，VSCode调试启动失败，报错Process exited with code 1，Uncaught Error Error: Cannot find module '@common'。编译时tsc能成功解析@common模块，但转译后的JS文件中仍保留require("@common")语句，Node.js运行时无法识别该别名。

相关配置 #

tsconfig.json #

{"compilerOptions": {"target": "ESNext","module": "commonjs","outDir": "./dist","esModuleInterop": true,"skipLibCheck": true,"resolveJsonModule": true,"forceConsistentCasingInFileNames": true,"baseUrl": "./src","paths": {"@common": ["common"],"@common/*": ["common/*"]},"allowJs": false,"strict": true,"noImplicitAny": true,"strictNullChecks": true,"noImplicitThis": true,"alwaysStrict": true,"sourceMap": true},"include": ["./src"],"exclude": ["node_modules"]}

VSCode调试配置（launch.json） #

{"version": "0.2.0","configurations": [{"type": "node","request": "launch","name": "module-a Debug","program": "${workspaceFolder}/src/module-a/index.ts","preLaunchTask": "tsc: build - tsconfig.json","outFiles": ["${workspaceFolder}/dist/module-a/**/*.js","${workspaceFolder}/dist/common/**/*.js"],"cwd":"${workspaceFolder}","envFile": "${workspaceFolder}/.env"}]}

tsc编译跟踪日志 #

Module name '@common', matched pattern '@common'.
Trying substitution 'common', candidate module location: 'common'.
Loading module as file / folder, candidate module location 'project/src/common', target file types: TypeScript, Declaration.
File 'project/src/common.ts' does not exist.
File 'project/src/common.tsx' does not exist.
File 'project/src/common.d.ts' does not exist.
File 'project/src/common/package.json' does not exist according to earlier cached lookups.
File 'project/src/common/index.ts' exists - use it as a name resolution result.
======== Module name '@common' was successfully resolved to 'project/src/common/index.ts'. ========

package.json #

{"name": "proj","version": "1.0.0","description": "proj","main": "src/index.ts","scripts": {"start": "node src/index.ts","test": "npm run test:unit && npm run test:integration","test:unit": "jest --config jest.config.js","test:integration": "jest --config jest.integration.config.js","lint": "eslint .","lint:fix": "eslint . --fix"},"dependencies": {"chevrotain": "^10.5.0","commander": "^11.0.0","dotenv": "^16.3.1","fs-extra": "^11.1.1","js-yaml": "^4.1.0","kysely": "^0.26.1","lodash": "^4.17.21","pg": "^8.11.1","sql-formatter": "^12.2.4","winston": "^3.10.0"},"devDependencies": {"@types/commander": "^2.12.2","@types/fs-extra": "^11.0.1","@types/js-yaml": "^4.0.5","@types/lodash": "^4.14.195","@types/node": "^20.5.0","@types/pg": "^8.10.2","@types/winston": "^2.4.4","eslint": "^7.32.0","nodemon": "^3.0.1","prettier": "^2.3.2","ts-node": "^10.9.1","tsconfig-paths": "^4.2.0","typescript": "^5.1.6"}}

核心原因：TypeScript的paths仅为编译时别名解析规则，编译器不会将@common这类别名替换为实际相对路径，转译后的JS文件仍保留原别名，而Node.js运行时无法识别该别名。

方案1：调试时用ts-node加载别名 #

修改VSCode的launch.json，直接用ts-node运行并启用tsconfig-paths处理别名，无需提前编译：

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "module-a Debug",
      "runtimeArgs": ["-r", "ts-node/register", "-r", "tsconfig-paths/register"],
      "args": ["${workspaceFolder}/src/module-a/index.ts"],
      "cwd": "${workspaceFolder}",
      "envFile": "${workspaceFolder}/.env",
      "skipFiles": ["<node_internals>/**"]
    }
  ]
}

调试启动时，tsconfig-paths会自动将@common映射到实际路径，Node.js可正常解析模块。

方案2：编译时替换别名（适合调试编译后的JS文件） #

如果坚持先编译再调试，需借助tsc-alias工具在编译后替换JS文件中的别名：

1. 安装依赖：

npm install tsc-alias --save-dev

2. 修改package.json的编译脚本，在tsc编译后执行别名替换：

"scripts": {
  "build": "tsc && tsc-alias",
  // 保留其他原有脚本
}

3. 修改VSCode的preLaunchTask，指向新的build脚本（或直接配置任务执行npm run build）。
   编译完成后，JS文件中的require("@common")会被替换为require("../common")这类实际相对路径，Node.js运行时可正确识别。

额外检查：确认tsconfig的outDir配置正确，编译后的文件结构与src目录一致，确保common模块被编译到dist/common目录下，避免路径错位。

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