配置文件是 Webpack 项目的入口，也是团队协作中最容易产生冲突和混乱的地方。Webpack 5 在配置管理（Configuration Management）方面做了不少改进，既包括配置解析机制本身的增强，也提供了更灵活的配置导出方式，让开发者可以用更工程化的手段组织构建配置。本文将从配置导出形式的演进、多环境配置拆分、配置合并策略以及大型项目的配置复用四个方面，系统地讲解 Webpack 5 的配置管理实践。
一、Webpack 5 配置导出方式的演进
很多开发者只知道 webpack.config.js 可以导出一个对象，但实际上 Webpack 支持多种配置导出形式，而 Webpack 5 对这些形式的支持更加完善。第一种是最常见的对象导出，直接 module.exports = {...} 即可。第二种是函数式导出，配置文件导出一个函数，函数接收环境变量参数和命令行参数对象，返回最终的配置对象。这种方式是实现多环境配置最原生的手段。
第三种是 Promise 导出，适用于需要异步读取配置依赖的场景，比如从远程接口或加密文件中获取环境变量。第四种是多配置数组导出，一次构建产出多份产物，常用于同时构建主应用和扩展包的场景。下面用一个示例演示函数式导出的典型写法：
module.exports = (env, argv) => {
const isProd = argv.mode === 'production';
return {
mode: argv.mode,
devtool: isProd ? false : 'source-map',
output: {
filename: isProd ? '[name].[contenthash:8].js' : '[name].js',
path: path.resolve(__dirname, 'dist')
},
plugins: [
!isProd && new webpack.HotModuleReplacementPlugin()
].filter(Boolean)
};
};这个例子中，env 参数对应命令行中通过 --env 传入的变量，argv 则对应 --mode 等标准参数。函数式导出的优势在于配置的上下文信息集中在一个函数内，逻辑清晰且无需引入额外的合并工具，非常适合中小型项目。不过当配置分支过多时，单文件内的条件判断会迅速膨胀，这时就需要引入更细粒度的拆分策略。
二、多环境配置的拆分与合并实践
当项目发展到需要区分开发、测试、预发、生产等多个环境时，把所有逻辑塞进一个函数已经不够优雅了。社区的主流做法是基础配置加环境差异配置的组合模式，核心工具是 webpack-merge。它提供了智能合并能力，比如数组会自动拼接、对象会递归合并，甚至支持通过 mergeStrategy 自定义某个字段的合并行为，例如让 entry 字段采用覆盖而非合并策略。
典型的目录结构是把配置拆成 webpack.common.js、webpack.dev.js、webpack.prod.js 三个文件，再通过 npm scripts 分别组合调用。示例代码如下：
const { merge } = require('webpack-merge');
const common = require('./webpack.common.js');
module.exports = merge(common, {
mode: 'development',
devServer: {
port: 8080,
proxy: {
'/api': 'http://127.0.0.1:3000'
}
}
});这种模式的好处是职责分离：公共的 loader 规则、解析别名、插件放在 common 中，环境差异部分各自维护。需要注意的是，从 webpack-merge 5.x 版本开始，导出方式从默认导出改为了具名的 merge 导出，从 Webpack 4 迁移过来的项目如果直接升级，很容易因为引入方式错误导致合并失效，这是实际项目中高频踩坑点。
除了按环境拆分，还可以按功能维度拆分，例如把样式处理、图片资源、代码分割规则各自抽成独立模块，再在主配置中组装。这种模块化配置的思路在大型项目中能显著降低单文件的复杂度，也便于编写针对性的单元测试来验证配置的正确性。
三、利用 env 与 DefinePlugin 实现配置驱动的构建
配置管理不仅是组织配置文件，还包括如何把运行时的环境信息注入到构建流程和前端代码中。Webpack 5 支持在 --env 参数中传递复杂结构，例如 --env apiBaseUrl=https://ipipp.com --env platform=web，配合函数式导出就能在配置层面拿到结构化的环境数据。而要在业务代码中使用这些变量，则需要借助 DefinePlugin 或者更易用的 EnvironmentPlugin。
module.exports = (env) => ({
plugins: [
new webpack.DefinePlugin({
'process.env.API_BASE_URL': JSON.stringify(env.apiBaseUrl),
'process.env.BUILD_TIME': JSON.stringify(new Date().toISOString())
})
]
});这里有一个容易出错的细节：DefinePlugin 做的是纯文本替换，如果值不加 JSON.stringify，字符串会被当作 JavaScript 表达式直接插入，导致运行时报变量未定义的错误。另外，Webpack 5 推荐尽可能使用 mode 与内置的 process.env.NODE_ENV 定义，而不是重复通过 DefinePlugin 注入，避免与框架自身的 Tree Shaking 逻辑冲突。
对于变量较多的项目，可以结合 dotenv 方案，在配置文件顶部加载 .env 文件并解析成对象统一注入。这样配置信息全部收敛在环境文件中，配置文件本身只负责读取与传递，符合十二要素应用中配置与代码分离的原则，也降低了敏感信息硬编码在仓库中的风险。
四、大型项目的配置复用与 Monorepo 场景
在 Monorepo 或多项目团队中，每个应用重复维护一份几百行的 Webpack 配置显然不可持续。此时可以把配置封装成内部共享包，各应用通过少量参数定制差异。具体做法是共享包导出一个工厂函数，接收 options 对象控制入口路径、别名、代理规则等，返回完整配置。Webpack 5 对配置解析路径的处理更加宽松，允许配置中引用 monorepo 根目录的依赖而不被重复安装，这与 resolve.modules 和 pnp 支持的改进密不可分。
另一种思路是直接选用封装了配置管理的上层工具，例如 Rspack、Turbopack 或基于 Webpack 的脚手架方案，它们内置了合理的默认配置。但理解底层配置管理机制依然是必要的：当默认行为不满足需求时，能够快速定位并覆盖具体配置项，而不是被抽象层困住。建议团队在封装共享配置时保留一个 extend 入口，允许业务方通过 webpack-merge 的 mergeWithRules 深度定制 loader 规则，兼顾统一性与灵活性。
总结来看，Webpack 5 的配置管理没有提供一个全新的框架，而是通过更完善的函数式导出、更健壮的合并生态和更清晰的环境变量机制，让开发者能够用工程化思维组织配置。从单一对象到模块化配置体系，选择哪种方案取决于项目规模：小型项目用函数式导出即可，中大型项目建议采用 common 加环境配置的拆分模式，而多项目团队则值得投入成本建设共享配置包。配置管理的最终目标不是炫技，而是让构建行为可预测、可维护、可复用。
Webpack 5Configuration Management配置管理修改时间：2026-08-31 10:53:13