WebStorm 配置路径别名：jsconfig/tsconfig 终极指南

WebStorm 中处理 JavaScript 项目的路径别名

在使用 Webpack 这类构建工具时，经常会配置路径别名，来简化模块导入路径。比如，不用写一长串的 ../../../utils/foo，直接写 utils/foo 就行了。但是，这样配置完了以后，WebStorm 就懵了，它不知道 utils 到底对应哪个目录，代码提示也没了，还给你报一堆警告。这篇博客就来聊聊怎么解决这个问题。

问题根源

WebStorm 默认情况下，是根据相对路径来解析模块的。咱们配置的路径别名，是 Webpack 的配置，WebStorm 并不知道。 所以，WebStorm 找不到模块，自然就没法提供代码提示和自动完成了。

解决方案

要让 WebStorm 正确识别路径别名，有几种办法，下面一个个说。

1. 使用 jsconfig.json 或 tsconfig.json (推荐)

这种方法适用于几乎所有项目，最干净，也最推荐。

原理:

jsconfig.json (用于 JavaScript 项目) 和 tsconfig.json (用于 TypeScript 项目) 文件，是用来告诉 VS Code 和 WebStorm 这样的 IDE 怎么处理 JavaScript/TypeScript 代码的。我们可以在里面配置路径别名，告诉 IDE 这些别名对应的实际路径。

操作步骤：

1. 创建文件: 如果你的项目根目录下还没有 jsconfig.json 或者 tsconfig.json 文件，创建一个。
2. 配置别名: 在文件里添加 compilerOptions 和 paths 字段。

jsconfig.json 示例:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "utils/*": ["src/utils/*"],
      "components/*": ["src/components/*"]
      // 更多的别名...
    }
  },
  "exclude": ["node_modules"]
}

tsconfig.json 示例:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "utils/*": ["src/utils/*"],
      "components/*": ["src/components/*"]
       // 更多的别名...
    },
    // 其他 TypeScript 配置...
  },
  "exclude": ["node_modules"]
}

• baseUrl: 基准目录。一般设为 "."，表示项目根目录。
• paths: 路径别名配置。
  • "utils/*": 别名。* 是通配符，表示 utils/ 后面的任何路径。
  • ["src/utils/*"]: 别名对应的实际路径。注意，这里的路径是相对于 baseUrl 的。

3. 重启WebStorm: 大部分情况，配置改完以后，需要重启Webstorm.

进阶技巧:

如果你用了 TypeScript, 并且设置了 "allowJs": true，你也可以把配置写在一个 jsconfig.json文件里。

2. 将目录标记为 Resource Root (资源根目录)

这个办法很简单，适合别名比较少的情况。

原理:

WebStorm 里可以把目录标记为 "Resource Root"。这样，WebStorm 就会把这个目录当作一个根目录，在解析模块路径时，会从这个目录开始找。

操作步骤:

1. 右键点击目录: 在 WebStorm 的项目视图里，找到别名对应的实际目录，右键点击。
2. 选择 "Mark Directory as" -> "Resource Root": 在弹出的菜单里，选择 "Mark Directory as"，然后选择 "Resource Root"。

搞定！WebStorm 应该就能正确识别以这个目录为根目录的模块路径了。

缺点：

如果你的别名很多，或者项目结构经常变，这个方法就不太方便了，得手动一个个标记。

3. 使用 Webpack 配置文件 (不太推荐，但对老项目可能有用)

WebStorm 可以直接读取 Webpack 的配置文件，来获取路径别名信息。这个方法对一些老的项目，或者不想额外创建 jsconfig.json / tsconfig.json 文件的项目，可能会有用。

原理:

WebStorm 内置了对 Webpack 配置文件的支持。如果它发现你的项目里有 webpack.config.js 文件（或者你指定了其他配置文件），它会尝试读取里面的 resolve.alias 配置。

操作步骤:

1. 确保你的 Webpack 配置文件里有 resolve.alias 配置:

   // webpack.config.js
   const path = require('path');
   
   module.exports = {
     // ...其他配置...
     resolve: {
       alias: {
         utils: path.resolve(__dirname, 'src/utils/'),
         components: path.resolve(__dirname, 'src/components/'),
         // 更多的别名...
       },
     },
   };
   

2. 告诉 WebStorm Webpack 配置文件的位置 (如果不是默认位置):

   • 打开 WebStorm 的设置 (Preferences on macOS / Settings on Windows/Linux)。
   • 找到 Languages & Frameworks -> JavaScript -> Webpack。
   • 选择 "Manually"。
   • 在 "Webpack configuration file" 栏里，选择你的 Webpack 配置文件的路径。

3. 重启 WebStorm

缺点：

• WebStorm 对 Webpack 配置文件的支持，可能没有 jsconfig.json / tsconfig.json 那么好。有些复杂的 Webpack 配置，WebStorm 可能解析不了。
• 如果你的 Webpack 配置是动态生成的 (比如根据环境变量生成不同的配置)，WebStorm 可能没法正确识别。

4. ESlint 相关配置 (如果你用 ESLint)

这个不算直接解决 WebStorm 的问题，但是如果你用了 ESLint，并且开启了 import/no-unresolved 规则，ESLint 也会报找不到模块的错误。要解决这个问题，需要配置 ESLint 的 resolver。

原理：

ESLint 本身不知道怎么解析路径别名。你需要安装一个 resolver 插件，比如 eslint-import-resolver-webpack 或者 eslint-import-resolver-alias，然后在 ESLint 的配置文件里告诉它怎么解析。

操作步骤 (以 eslint-import-resolver-alias 为例):

1. 安装插件:

   npm install eslint-import-resolver-alias --save-dev
   # 或者
   yarn add eslint-import-resolver-alias -D
   

2. 配置 ESLint: 在你的 .eslintrc.js (或者其他 ESLint 配置文件) 里，添加 settings 和 import/resolver：

   // .eslintrc.js
   module.exports = {
     // ...其他 ESLint 配置...
      settings: {
       'import/resolver': {
         alias: {
           map: [
             ['utils', './src/utils'],
             ['components', './src/components'],
             // ...更多别名...
           ],
           extensions: ['.js', '.jsx', '.json'] // 可选，默认值包含这些
         }
       }
     },
       rules:{
         'import/no-unresolved': 'error', //打开校验
       }
   
   };
   

直接把alias 里面的 map 内容设置为与前面其他配置保持一致即可.

注意, 记得打开规则 import/no-unresolved, 这样 ESLint 才能检查路径。

3. 重启 WebStorm 或者相关服务 比如你的代码实时校验工具。

5. d.ts文件声明 (适合三方库)

如果是使用了第三方的库, 你可能希望给这个库写类型定义(d.ts), 来获得更好的类型检查。 如果这个库恰好用了路径别名， 可以在.d.ts里面增加路径别名：
操作步骤:

1. 创建 .d.ts 文件， 如./typings/some-lib.d.ts

2. 声明 module

declare module 'config'{
    export const value1:string;
    export const value2:number;
}

3. 在tsconfig.json 的compilerOptions 添加配置

 "compilerOptions": {
    "typeRoots" : ["./typings"]
  }

这样你在使用import {value1} from 'config' 就可以有自动补全了。

进阶:

如果你使用了 jsdoc 生成 API 文档。也可以使用@module tag 进行声明，也有利于jsdoc 更好的识别路径。

安全建议

使用别名本身没有太多的安全问题, 但有一点要注意的是, 尽量避免把 node_modules 里的内容通过别名暴露出来。 这么做的风险就是外部可以直接引用node_modules里的私有文件，可能会引入一些不稳定的依赖关系。

小结

这几种方法，各有优劣。最推荐的还是用 jsconfig.json 或者 tsconfig.json，最规范，也最不容易出问题。选哪种，看你自己的项目情况和个人喜好。搞定路径别名，WebStorm 用起来就更顺手了！