VSCode配置jsconfig.json路径别名后Node报模块找不到错误如何解决

jsconfig.json 中的 paths 路径别名配置仅为编辑器提供智能感知、路径补全的依据，Node.js 原生运行时不会读取该配置做路径解析，因此会出现VSCode补全正常、运行时直接抛出ERR_MODULE_NOT_FOUND模块找不到错误的现象。

根据项目使用的模块规范、是否有构建流程，可选择以下任意一种方案：

方案1：ESM自定义Loader（适用于Node原生ESM项目） #

• 安装依赖：

npm install @node-loader/alias

• 在项目根目录新建alias.config.js配置别名映射：

export default {
  aliases: {
    '@': process.cwd()
  }
}

• 启动代码时追加Loader参数：

node --loader @node-loader/alias main.js

方案2：module-alias包（适用于CommonJS规范项目） #

• 安装依赖：

npm install module-alias

• 在项目入口文件的最顶部添加注册代码：

require('module-alias/register')

• 在package.json中追加别名配置：

{
  "_moduleAliases": {
    "@": "."
  }
}

直接正常启动项目即可识别别名。

方案3：构建工具转译路径（适用于有编译/打包流程的项目） #

如果项目使用Webpack、Vite、Babel、TypeScript等工具链，直接在对应工具的配置中添加相同的别名规则即可，工具会在编译阶段将@/xxx格式的别名路径替换为Node可识别的相对/绝对路径：

• Webpack：在webpack.config.js的resolve.alias字段配置@映射到项目根目录
• Vite：在vite.config.js的resolve.alias字段配置相同映射
• Babel：安装babel-plugin-module-resolver插件，在Babel配置文件中声明别名规则
• TypeScript：搭配tsconfig-paths包在运行时注册路径映射，或编译时开启路径转换

方案4：Node原生Import Maps（无依赖实验性方案） #

Node.js 16及以上版本原生支持Import Maps特性，无需安装额外依赖：

• 在项目根目录新建import-map.json声明映射：

{
  "imports": {
    "@/*": "./*"
  }
}

• 启动时追加参数指定Import Map文件：

node --experimental-import-maps ./import-map.json main.js

注意：该特性目前仍处于实验阶段，不建议在生产环境使用

内容的提问来源于stack exchange，提问作者Jonas Möller