Webpack 的模块解析并不神秘，它本质上是一个文件查找过程。当代码里出现 import 或 require 时，Webpack 会从当前文件所在目录出发，尝试定位目标模块。如果写的是相对路径 ./utils，它会直接拼接目录和文件名；如果写的是 bare import，比如 import Vue from 'vue'，它会进入 node_modules 查找。而 resolve 字段就是用来修改这个查找过程的一套规则。配置得当可以少写很多层级，配置不当则可能出现解析失败或构建变慢。
接下来从几个关键选项展开：extensions 控制自动补全后缀，alias 负责路径别名，modules 决定查找目录，mainFields 指定包入口字段。
一、resolve.extensions 扩展名自动补全
在 Webpack 默认配置里，当你写 import utils from './utils' 时，它不会只查找名为 utils 的文件，而是按照 extensions 数组依次尝试补全后缀。Webpack 5 的默认值是 ['.js', '.json', '.wasm']。这意味着它会依次查找 utils.js、utils.json、utils.wasm，找到第一个存在的文件就停止。如果都没有，才会抛出解析错误。
这个数组可以自定义。例如在 Vue 或 React 项目里，开发者经常希望省略 .vue、.jsx、.ts 后缀，于是配置如下：
module.exports = {
resolve: {
extensions: ['.js', '.jsx', '.vue', '.json']
}
};注意顺序非常重要。Webpack 会从前往后匹配，如果有同名但不同后缀的文件，排在前面的后缀会优先被解析。比如同时存在 Button.js 和 Button.jsx，数组里 .js 在 .jsx 前面，那么 import Button from './Button' 会加载 Button.js，而不是 Button.jsx。因此通常建议把项目里最常用的后缀写在前面。另一个注意点是，extensions 数组太长会增加文件系统查询次数，可能轻微拖慢构建，但不建议过度精简，否则可读性会下降。
如果你希望强制书写完整后缀，可以设置 enforceExtension: true，这样 Webpack 不会再自动补全。这个选项在 Node.js 服务端代码中偶尔用到，可以避免一些隐蔽的解析歧义。
二、resolve.alias 路径别名
路径别名是日常开发中使用频率最高的配置之一。它把某个目录映射成一个简短名称，让 import 语句不再出现 ../../../../utils 这种又长又脆弱的相对路径。一个常见做法是把 src 目录映射为 @：
const path = require('path');
module.exports = {
resolve: {
alias: {
'@': path.resolve(__dirname, 'src')
}
}
};这样任何位置的组件都可以写 import request from '@/utils/request'，Webpack 会先把 @ 替换成绝对路径，再按照普通模块解析规则继续查找。相比相对路径，使用别名后代码移动位置不再需要修改引用路径，后续重构会轻松很多。
alias 也支持更精细的控制。比如可以写成对象形式精确匹配：
module.exports = {
resolve: {
alias: {
'old-module': path.resolve(__dirname, 'src/new-module'),
'utils$': path.resolve(__dirname, 'src/utils/index.js')
}
}
};这里 utils$ 末尾的美元符号表示精确匹配，只有 import utils 时才指向 index.js，而 import utils/format 仍然会按照正常路径解析，不会受到影响。这个特性适合替换单个模块入口，比直接覆盖整个目录更安全。需要注意，别名配置只影响 Webpack 打包解析，IDE 和 TypeScript 不会自动识别，如果使用 TypeScript，需要在 tsconfig.json 中同步配置 paths；使用 JavaScript 项目也可以在 jsconfig.json 中声明，否则编辑器的跳转和提示可能不准确。
三、resolve.modules 与查找目录
Webpack 在处理 bare import 时，默认会去当前目录以及祖先目录的 node_modules 中查找模块。这个行为可以通过 resolve.modules 修改。默认值是 ['node_modules']，表示只在 node_modules 中找。如果你有一些公共组件放在项目根目录的 common 文件夹中，又不想每次都写相对路径，可以把它加入查找目录：
const path = require('path');
module.exports = {
resolve: {
modules: [
path.resolve(__dirname, 'src/components'),
'node_modules'
]
}
};配置完成后，任何地方都可以直接写 import UserCard from 'UserCard'，Webpack 会先去 src/components 目录查找，找不到再进入 node_modules。这种方式适合抽取高频复用的组件或工具目录，但目录数量不宜过多，否则 Webpack 需要做更多路径探测，可能增加解析时间。
此外，resolve.modules 也支持相对路径，但不推荐在大型项目中使用相对路径写法，因为相对路径是相对于 webpack.config.js 文件所在目录解析的，一旦配置文件移动，行为就会改变。使用 path.resolve 生成绝对路径是更稳妥的做法。
四、resolve.mainFields 与第三方包入口
安装的第三方包通常通过 package.json 中的主入口字段被引用。Webpack 默认会根据 target 环境选择不同的字段排列。以 Webpack 5 为例，当 target 为 web 时，默认 mainFields 是 ['browser', 'module', 'main']；当 target 为 node 时，默认是 ['module', 'main']。这些值会直接影响打包结果。
例如某个组件库同时提供 browser 版本、ES Module 版本和 CommonJS 版本。如果配置为 ['browser', 'module', 'main']，Webpack 会优先读取 package.json 的 browser 字段，其次 module，最后才是 main。当你需要强制使用 ES Module 版本以支持 Tree Shaking 时，可以手动把 module 放到前面：
module.exports = {
resolve: {
mainFields: ['module', 'main']
}
};这种调整的前提是依赖包确实提供了 module 字段。如果某个包只有 main 字段，Webpack 会忽略不存在的字段并继续向后查找。配置 mainFields 时要结合包的实际结构，不要盲目改动，否则可能出现引入了未经编译的 ESM 代码，在浏览器中运行时才暴露出兼容性问题。
五、symlinks、fallback 与常见坑
在使用 npm link、yarn workspace 或 pnpm 时，项目里会出现软链接。默认情况下 resolve.symlinks: true 会让 Webpack 把软链接还原为真实路径，这通常能避免模块被重复打包。但如果你希望保留链接路径以便让某些插件正常工作，可以设置 symlinks: false。大多数 monorepo 项目不需要改这个值，保持默认即可。遇到模块实例不一致或样式重复的问题时，可以先检查 symlinks 是否与包管理器的链接方式冲突。
resolve.fallback 则是为了让原本只在 Node.js 环境中可用的模块在浏览器端有替代方案。例如代码里引用了 path、os 或 crypto，但打包目标是浏览器，这些 Node 内置模块并不存在，Webpack 5 不会自动 polyfill，会直接报错。此时可以配置：
module.exports = {
resolve: {
fallback: {
path: require.resolve('path-browserify'),
os: require.resolve('os-browserify/browser')
}
}
};不过 fallback 只是补丁方案。如果组件库大量依赖 Node 内置模块，可能并不适合直接跑在浏览器里，更好的做法是评估该组件是否有浏览器版本，或者在服务端处理相关逻辑。随意添加 fallback 会让打包体积增加，也容易掩盖运行时的环境差异。
最后还有 resolve.roots、resolve.restrictions 等更细粒度的选项，它们分别用于定义根目录和限制解析范围。普通业务项目不常用，但在大型工程或安全要求较高的场景里可以通过 restrictions 阻止 Webpack 去某些目录外查找模块。掌握前面几个核心选项已经能解决绝大多数模块解析问题，更多特殊配置应该在实际需要出现时再查阅官方文档。
Webpack resolve模块解析路径别名修改时间：2026-10-06 02:12:14