在VSCode中使用带根路径变量的require的问题及解决办法

我之前也碰到过一模一样的困扰！用全局变量__root存项目根路径确实能避免写一堆繁琐的相对路径，但VSCode的Intellisense（背后依赖TypeScript语言服务）对这种动态拼接的路径天生不友好，以下是几个亲测有效的解决方案，还有我自己的实践经验：

方案1：用TypeScript/JS路径别名（最推荐） #

这是我现在一直在用的方案，配置一次就能让VSCode完美识别，运行时也能正常工作。

针对JavaScript项目： #

1. 在项目根目录创建jsconfig.json，添加路径别名配置：

   {
     "compilerOptions": {
       "baseUrl": "./",
       "paths": {
         "@parsers/*": ["parsers/*"],
         "@utils/*": ["utils/*"]
         // 可以根据自己的目录结构添加更多别名
       }
     },
     "exclude": ["node_modules"]
   }
   

2. 安装module-alias包来让Node.js运行时识别这些别名：

   npm install module-alias --save
   

3. 在项目入口文件（比如app.js）最顶部添加：

   require('module-alias/register')
   

4. 最后在package.json里添加别名映射：

   "_moduleAliases": {
     "@parsers": "./parsers",
     "@utils": "./utils"
   }
   

之后你就可以直接写const Parser = require('@parsers/Parser')，VSCode的Intellisense会立刻识别到类型，运行时也不会报错。

针对TypeScript项目： #

1. 在tsconfig.json的compilerOptions里添加：

   {
     "baseUrl": "./",
     "paths": {
       "@parsers/*": ["src/parsers/*"],
       "@utils/*": ["src/utils/*"]
     }
   }
   

2. 如果用ts-node运行，不需要额外配置；如果用webpack打包，在webpack.config.js的resolve.alias里同步配置别名即可。

方案2：给全局变量__root添加类型声明 #

这个方案能让VSCode识别__root的类型，但没法解决路径解析的问题，适合临时救急或者不想改太多代码的场景：

1. 在项目根目录创建一个globals.d.ts文件（如果是JS项目，VSCode也会识别这个文件）：

   declare const __root: string;
   

2. 如果你想让VSCode识别具体模块的类型，可以给require语句加JSDoc注释：

   /** @type {import('./parsers/Parser')} */
   const Parser = require(__root + '/parsers/Parser')
   

不过这种方式需要每个require都加注释，比较繁琐，适合小项目或者局部文件。

方案3：利用Node.js的NODE_PATH环境变量 #

这个方案不需要改代码，但依赖环境变量配置：

1. 启动项目时设置NODE_PATH为项目根目录：
   • Linux/macOS：export NODE_PATH=. && node app.js
   • Windows（cmd）：set NODE_PATH=. && node app.js
2. 在VSCode的设置里，添加javascript.preferences.importModuleSpecifier为non-relative，或者在jsconfig.json里设置baseUrl: "./"，这样VSCode会把根目录当成模块查找目录，你可以直接写const Parser = require('parsers/Parser')，Intellisense就能识别了。

不过这个方案的缺点是NODE_PATH在Node.js官方文档里被标记为不推荐使用，而且团队协作时需要每个人都配置环境变量，容易出问题。

我的实践经验 #

我最推荐方案1的路径别名，因为它既能让VSCode的Intellisense完美工作，又能统一项目的模块导入风格，团队协作时也不需要额外配置环境变量。

如果是小型项目或者临时项目，方案2的JSDoc注释可以快速解决类型提示问题；方案3适合老项目迁移，但不建议长期使用。

另外要注意，如果你用的是ES模块（import/export），配置思路是一样的，只是运行时的工具换成esm或者webpack的resolve配置即可。

内容的提问来源于stack exchange，提问作者Lukas Ignatavičius