配置拆分与工程化模板
约 708 字大约 2 分钟
2026-02-11
当 Webpack 配置超过一百行后，最大的风险通常不是“写不出来”，而是“改不动”。
配置拆分的意义在于：
- 把环境共性与差异拆开，减少误改。
- 让团队成员快速定位配置归属。
- 为后续性能优化和发布流程留出空间。
为什么要拆成 common/dev/prod
单文件配置常见问题：
if (isProd)到处散落，可读性差。- 开发/生产选项交叉污染。
- 新成员无法快速判断改动影响面。
拆分后职责更清晰：
| 文件 | 负责内容 | 不应该放什么 |
|---|---|---|
webpack.common.cjs | 入口、基础规则、公共插件 | 端口、压缩、重型调试选项 |
webpack.dev.cjs | devServer、快速 Source Map、HMR | 生产压缩和长期缓存策略 |
webpack.prod.cjs | 压缩、拆包、缓存、发布策略 | 本地代理、开发端口 |
三份配置的职责边界
先安装合并工具
webpack-merge 解决的是“组合配置而不是复制粘贴配置”。
pnpm add -D webpack-merge完整工程化模板
下面这份模板强调“通用基础 + 环境差异”。看代码前先注意：
common只放稳定公共项。dev/prod只加差异，不重复。
build/webpack.common.cjs
const path = require('node:path');
const HtmlWebpackPlugin = require('html-webpack-plugin');
module.exports = {
entry: './src/main.js',
output: {
path: path.resolve(__dirname, '../dist'),
filename: 'js/[name].[contenthash:8].js',
chunkFilename: 'js/[name].[contenthash:8].chunk.js',
clean: true,
},
resolve: {
extensions: ['.js', '.ts', '.json'],
alias: {
'@': path.resolve(__dirname, '../src'),
},
},
module: {
rules: [
{
test: /\.m?js$/,
exclude: /node_modules/,
use: 'babel-loader',
},
],
},
plugins: [
new HtmlWebpackPlugin({
template: './public/index.html',
}),
],
};build/webpack.dev.cjs
const { merge } = require('webpack-merge');
const common = require('./webpack.common.cjs');
module.exports = merge(common, {
mode: 'development',
devtool: 'eval-cheap-module-source-map',
devServer: {
port: 9527,
open: true,
hot: true,
historyApiFallback: true,
},
});build/webpack.prod.cjs
const { merge } = require('webpack-merge');
const common = require('./webpack.common.cjs');
const TerserPlugin = require('terser-webpack-plugin');
const CssMinimizerPlugin = require('css-minimizer-webpack-plugin');
module.exports = merge(common, {
mode: 'production',
devtool: 'hidden-source-map',
optimization: {
moduleIds: 'deterministic',
chunkIds: 'deterministic',
runtimeChunk: 'single',
splitChunks: {
chunks: 'all',
},
minimizer: [new TerserPlugin(), new CssMinimizerPlugin()],
},
});然后在脚本里固定入口，避免“每个人跑的配置都不一样”：
{
"scripts": {
"dev": "webpack serve -c build/webpack.dev.cjs",
"build": "webpack -c build/webpack.prod.cjs"
}
}合并策略的注意点
merge(a, b) 里 b 会覆盖 a 同名字段。
这意味着：
- 顺序写反，配置结果就会反过来。
- 数组字段（如 plugins/rules）要确认是追加还是替换。
使用注意事项
建议
- 先定义好“配置边界”再写文件。
- 公共规则尽量收口到
common。 - 环境变量读取与注入流程标准化。
常见错误
- 在
common写入开发端口等环境特有配置。 merge顺序错误导致配置被意外覆盖。- 生产环境沿用开发 Source Map 策略。
最佳实践
- 把配置拆分当成“可维护性工程”，不是文件数量工程。
- 每次新增插件时明确它属于哪个环境。
- 在 CI 中明确 dev/build 两条独立校验链路。