如何让Visual Studio Code识别TypeScript路径别名？调试报错求助

问题场景 #

我在项目中配置了TypeScript路径别名，tsconfig.json配置如下：

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "esnext",
    "moduleResolution": "bundler",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "declaration": true,
    "baseUrl": ".",
    "paths": {
      "@controllers/*": ["src/controllers/*"],
      "@websocket/*": ["src/websocket/*"]
    },
    "lib": ["DOM", "ES2021.String"],
    "sourceMap": true
  },
  "include": ["src/**/*"],
  "files": ["src/app.ts"],
  "ts-node": {
    "require": ["tsconfig-paths/register"]
  },
  "plugins": [{ "transform": "typescript-transform-paths" }]
}

导入语句使用别名：

import { initialize } from "@websocket/entry/init.js";

构建脚本配置为：

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

但启动VS Code（版本1.97.2）调试时，出现模块找不到错误：

/Users/xiaoqiangjiang/.nvm/versions/node/v16.14.2/bin/node -r tsconfig-paths/register ./dist/app.js --inspect
Uncaught Error Error [ERR_MODULE_NOT_FOUND]: Cannot find package '@websocket/entry' imported from /Users/xiaoqiangjiang/source/reddwarf/backend/texhub-broadcast/dist/app.js
    at __node_internal_captureLargerStackTrace (<node_internals>/internal/errors:464:5)
    at NodeError (<node_internals>/internal/errors:371:5)
    at packageResolve (<node_internals>/internal/modules/esm/resolve:932:9)
    at moduleResolve (<node_internals>/internal/modules/esm/resolve:978:18)
    at defaultResolve (<node_internals>/internal/modules/esm/resolve:1080:11)
    at resolve (<node_internals>/internal/modules/esm/loader:530:30)
    at getModuleJob (<node_internals>/internal/modules/esm/loader:251:18)
    at <anonymous> (<node_internals>/internal/modules/esm/module_job:79:40)
    at link (<node_internals>/internal/modules/esm/module_job:78:36)
    --- async function ---
    at runMainESM (<node_internals>/internal/modules/run_main:51:21)
    at executeUserEntryPoint (<node_internals>/internal/modules/run_main:74:5)
    at <anonymous> (<node_internals>/internal/main/run_main_module:17:47)
errors:464
Process exited with code 1

尝试修改launch.json添加ts-node和tsconfig-paths注册、切换runtimeExecutable为ts-node等操作后，问题仍未解决。

解决步骤 #

1. 修复ES模块与tsconfig-paths的兼容性 #

当前配置中module设为esnext，属于ES模块，但默认的tsconfig-paths/register是针对CommonJS模块的，需要调整：

• 在项目根目录的package.json中添加"type": "module"
• 将tsconfig-paths的注册路径改为ES模块版本：tsconfig-paths/esm/register

2. 调整launch.json（调试编译产物） #

如果调试编译后的dist/app.js，确保tsc-alias已完成路径替换，同时更新launch.json配置：

{
  "type": "node",
  "request": "launch",
  "name": "local debug",
  "program": "${workspaceFolder}/dist/app.js",
  "runtimeArgs": [
    "-r",
    "${workspaceFolder}/node_modules/tsconfig-paths/esm/register"
  ],
  "sourceMaps": true,
  "cwd": "${workspaceFolder}",
  "env": {
    "NODE_ENV": "development"
  },
  "outFiles": ["${workspaceFolder}/dist/**/*.js"]
}

3. 验证tsc-alias的替换效果 #

检查dist目录下的编译后JS文件，确认导入语句中的别名是否被替换为相对路径。例如@websocket/entry/init.js应被替换为./websocket/entry/init.js（根据文件层级调整）。如果未替换：

• 更新tsc-alias到最新版本
• 确认tsconfig.json中plugins的typescript-transform-paths配置生效，或尝试在build命令中添加参数：tsc --project tsconfig.json && tsc-alias -p tsconfig.json

4. 直接调试TS源码（使用ts-node-esm） #

若想跳过编译直接调试TS文件，需使用支持ES模块的ts-node版本，调整launch.json：

{
  "type": "node",
  "request": "launch",
  "name": "local debug",
  "runtimeExecutable": "${workspaceFolder}/node_modules/.bin/ts-node-esm",
  "program": "${workspaceFolder}/src/app.ts",
  "runtimeArgs": [
    "-r",
    "${workspaceFolder}/node_modules/tsconfig-paths/register/esm"
  ],
  "sourceMaps": true,
  "cwd": "${workspaceFolder}",
  "env": {
    "NODE_ENV": "development",
    "TS_NODE_PROJECT": "${workspaceFolder}/tsconfig.json"
  }
}

5. 升级Node.js版本 #

当前使用的Node.js v16.14.2对ES模块的支持存在局限性，建议升级到v18及以上版本，能更好地兼容ES模块和路径别名的处理逻辑。

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