【问题】Webstorm不识别路径别名(resolve.alias)，报错：coding assistance will ignore

问题现象

使用Webstorm开发前端Vite/Webpack项目时，IDE无法识别 @ 等文件路径别名。按照百度搜索最多的方法，单独配置了alias.config.js文件后，IDE的Event log里面报错：

12:09	Webpack
Can't analyze alias.config.js: coding assistance will ignore module resolution rules in this file.
  Possible reasons: this file is not a valid webpack configuration file or its format is not currently supported by the IDE.

问题产生环境

• Webstorm 2021.2.2

• 使用Vite构建的项目，项目更目录生成了vite.config.js，且配置文件中包含: resolve.alias配置

• 在Webstorm的设置中(Settings | Languages & Frameworks | JavaScript | Webpack) 开启了自动或者手动配置，手动配置时文件指向根目录下的 alias.config.js

可能原因和解法

Webstorm不识别路径别名(alias)的问题，很常见，受IDE版本影响，原因也有很多。

百度搜索常见的问题解决方案基本都是根目录下配置一个alias.config.js之类的文件，然后在IDE的设置中手动指定，但很多时候不生效。

深层次原因分析

1.首先，研究官方文档：

https://www.jetbrains.com/help/idea/using-webpack.html#edit_webpack_configuration_file 时，会看到官方的一个说明：

WebStorm provides coding assistance in a webpack configuration file only if its name contains the webpack character string and webpack is listed in package.json.

意思是说，上面说的这个配置文件名字中必须包含"webpack"字样，且在同目录的package.json文件中，必须依赖webpack这个包，这样IDE才能识别到该配置文件。

此外，当IDE设置中开启的是Automatically时，官方也列出了有效识别的配置文件名称列表：

webpack.config.js/webpack.config.ts

webpack.base.conf.js/webpack.base.conf.ts

webpack.dev.conf.js/webpack.dev.conf.ts

webpack.prod.conf.js/webpack.prod.conf.ts

webpack.base.config.js/webpack.base.config.ts

webpack.dev.config.js/webpack.dev.config.ts

webpack.prod.config.js/webpack.prod.config.ts

webpack.babel.js/webpack.babel.ts

虽然官方也说了，手动指定(Manually)配置文件时，可以用不同的名称，但还是保持统一，不容易出错。

2.其次，分析IDE的日志

当我指定了“正确”的配置文件之后，IDE的Event log里可能出现这样一段错误日志：

12:09	Webpack
Can't analyze alias.config.js: coding assistance will ignore module resolution rules in this file.
  Possible reasons: this file is not a valid webpack configuration file or its format is not currently supported by the IDE.

这意味着，IDE读到了配置文件，但是确无法解析配置文件的内容，最终导致配置依旧无法生效，依旧无法识别alias。

按照官方文档的提示，点击Help | Show Log In Explorer，打开IDE日志目录，然后查看最近的一个日志文件，拉到文件最末尾几行，寻找报错的日志信息，发现了这样一段：

webpack.config.js is treated as an ES module file as it is a .js file whose nearest parent package.json contains "type": "module" which declares all .js files in that package scope as ES modules.
Instead either rename webpack.config.js to end in .cjs, change the requiring code to use dynamic import() which is available in all CommonJS modules, or change "type": "module" to "type": "commonjs" in D:\work\project\ds-front-2024\tests\sharing-component\package.json to treat all .js files as CommonJS (using .mjs for all ES modules instead).

    at [eval]:36:14
    at Script.runInThisContext (node:vm:122:12)
    at Object.runInThisContext (node:vm:298:38)
    at [eval]-wrapper:6:24 {
  code: 'ERR_REQUIRE_ESM'
}

有点前端基础的大概能很快看明白，这错误是说webpack.config.js的文件内容格式用的CommonJS风格，而最近的package.json文件里使用了type:module配置，要求项目使用es风格语法，两者不一致才导致了解析报错。

错误信息里，还给出了解决方法：

• 将配置文件重命名为webpack.config.cjs

• 或者，配置文件里使用import/export等语法替换require/module.exports等语法

最终解决

• 修改项目的package.json文件：

{
  "type":"commonjs"
}

• 在项目根目录新建文件：webpack.config.cjs，命名和文件后缀都不要改，文件内容：

// webpack.config.cjs
const nodePath = require('node:path')

module.exports = {
  resolve: {
    alias: {
      '@': nodePath.resolve(__dirname, './src'),
      '@@': nodePath.resolve(__dirname)
    }
  }
}

• 在IDE的设置中开启Webpack，自动或者手动指定均可。

设置路径：Settings | Languages & Frameworks | JavaScript | Webpack

• 最后一个容易忽略的问题：IDE的设置读取是有缓存的，最好重启一下IDE