Node.js环境中jsconfig配置的paths路径别名解析失效是什么原因？

核心失效原因 #

• jsconfig.json仅为VSCode等编辑器提供代码提示、路径跳转支持，Node.js原生运行环境、构建工具、ESLint均不会读取该文件的paths配置，运行时Node无法解析@前缀，因此直接抛出模块找不到错误。
• 现有ESLint配置仅声明了可识别的扩展名，未配置别名映射规则，因此ESLint也无法识别@路径。

对应解决方法 #

1. 解决运行时报错（三选一即可） #

方案A：使用module-alias包（无需修改导入语法）

1. 安装依赖：

npm i module-alias

2. 在package.json中添加别名配置：

{
  "_moduleAliases": {
    "@": "./src"
  }
}

3. 在项目入口文件最顶部引入注册逻辑：

• ES Module 项目：

import 'module-alias/register.js'

• CommonJS 项目：

require('module-alias/register')

方案B：使用Node.js原生imports配置（无需额外依赖）

Node.js 16+ 版本支持原生别名配置，官方推荐用#作为别名前缀避免和npm包名冲突，在package.json中添加：

{
  "imports": {
    "#/*": "./src/*"
  }
}

使用时修改导入语句即可：

import { checkToken } from '#/util/token.js';

方案C：如果是带构建工具的项目（如Vite/Webpack/Rollup）

需要在对应构建工具的配置文件中单独添加别名，以Vite为例，在vite.config.js中配置：

import { defineConfig } from 'vite'
import path from 'path'

export default defineConfig({
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src')
    }
  }
})

2. 解决ESLint识别报错 #

1. 安装ESLint别名解析依赖：

npm i eslint-import-resolver-alias -D

2. 修改.eslintrc.cjs的settings配置：

settings: {
  'import/resolver': {
    alias: {
      map: [
        ['@', './src']
      ],
      extensions: ['.js']
    }
  },
},

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