Webpack 配置函数如何根据 env 返回不同配置？

Webpack 的配置文件通常导出一个对象，但函数形式能带来更灵活的分支控制。构建命令可以通过 --env 参数传入环境标识，配置函数接收这些标识后，在生成配置对象之前做判断。这样开发环境、测试环境、生产环境可以共用一份入口，最后由函数决定输出什么。

需要特别说明的是，这里说的 env 并非 process.env。webpack-cli 会解析 --env 参数，并把它转换成普通对象后传给配置函数。比如执行 npx webpack --env production 时，函数收到的第一个参数就是 { production: true }。这个机制不依赖 Node 环境变量，因此同一份配置在 Windows、macOS、Linux 上都有一致表现。

一、函数式配置与 env 参数从哪里来

配置导出函数有两种常见形态：一种只接收 env 一个参数，另一种同时接收 env 和 argv。argv 是 webpack-cli 传入的第二个参数，包含 mode 等命令行选项。多数多环境场景只需要使用 env，node 环境变量仍然通过 process.env 读取，两者可以并行使用。

函数式配置的基本写法并不复杂。以 CommonJS 为例，只需要把 module.exports 从对象改成函数，并在函数体内返回配置对象即可。下面的例子根据 env.production 切换 mode 和 devtool，这是最小可用版本。

const path = require('path');

module.exports = function(env, argv) {
  const isProd = env && env.production;
  return {
    mode: isProd ? 'production' : 'development',
    entry: './src/index.js',
    output: {
      filename: isProd ? '[name].[contenthash:8].js' : '[name].js',
      path: path.resolve(__dirname, 'dist')
    },
    devtool: isProd ? false : 'eval-cheap-module-source-map'
  };
};

这个例子中，如果命令行没有携带 --env production，isProd 为 undefined，最终走开发分支。开发分支保留 eval-cheap-module-source-map 是为了让报错信息能快速定位到源文件，生产分支关闭 source map 则避免暴露源代码。实际项目可以根据安全策略改成 hidden-source-map 或 nosources-source-map。

二、用 env 控制开发与生产的核心差异

mode 只是基础，真正区分两个环境的还有插件、loader 和优化配置。开发环境习惯用 style-loader 把 CSS 注入页面以便热更新，生产环境则通常用 MiniCssExtractPlugin 把 CSS 抽成独立文件，方便浏览器缓存。函数式配置可以用一个 isProd 变量统一管理这些差异，避免在某一个配置项上漏改。

const HtmlWebpackPlugin = require('html-webpack-plugin');
const MiniCssExtractPlugin = require('mini-css-extract-plugin');

module.exports = function(env) {
  const isProd = env.production;
  const plugins = [new HtmlWebpackPlugin({ template: './src/index.html' })];
  if (isProd) {
    plugins.push(new MiniCssExtractPlugin({ filename: 'css/[name].[contenthash:8].css' }));
  }
  return {
    mode: isProd ? 'production' : 'development',
    module: {
      rules: [
        {
          test: /\.css$/,
          use: [
            isProd ? MiniCssExtractPlugin.loader : 'style-loader',
            'css-loader'
          ]
        }
      ]
    },
    plugins: plugins
  };
};

在生产配置中，输出文件名里加入 contenthash 是常见的缓存策略。只要文件内容不变，哈希就不变，浏览器可以继续使用本地缓存；一旦内容改变，哈希变化，新的请求 URL 会强制刷新资源。开发环境不需要哈希，因为开发服务器通常关闭缓存，文件名保持简洁更利于排查。

三、结合 webpack-merge 拆分配置的高级写法

当项目变大后，把所有逻辑都塞进一个配置函数会让文件越来越难读。更推荐的做法是拆成 base、dev、prod 三份配置，再用 webpack-merge 合并。函数的作用变成根据 env 返回拼装结果。base 配置里放入口、输出、解析规则和公共 loader，dev 配置只写开发服务器和 source map，prod 配置只写压缩、哈希和提取 CSS。

const { merge } = require('webpack-merge');
const baseConfig = require('./webpack.base.js');
const devConfig = require('./webpack.dev.js');
const prodConfig = require('./webpack.prod.js');

module.exports = function(env) {
  if (env.production) {
    return merge(baseConfig, prodConfig);
  }
  return merge(baseConfig, devConfig);
};

merge 的规则是浅层对象会直接覆盖，数组和嵌套对象会做合并，但具体行为可以通过 webpack-merge 的定制函数调整。比如 plugins 数组默认是拼接而不是覆盖，所以 base 和 prod 中定义的插件都会保留。这种拆分方式的好处是每个文件职责单一，新增测试环境时只需增加一份 test 配置，再在函数里加一个分支即可。

如果环境不止生产与开发两种，可以使用更明确的环境名称，例如 --env environment=staging，然后读取 env.environment。避免把所有布尔标识堆积成 env.production && env.staging 这样的脆弱判断。环境名称配合对象映射，可以让分支逻辑更清晰。

四、常见误区和调试建议

第一个误区是把 env 当成安全边界。--env 传参本身就是明文，可能出现在 shell 历史或 CI 日志中。API 密钥、数据库密码等敏感信息不应通过 --env 传入，更适合用 CI 平台的加密环境变量或 Node 的 process.env 配合 dotenv 注入。

第二个误区是在配置函数中执行昂贵操作。配置函数在每次构建时都会被调用，像读取大文件、扫描目录、请求远程配置这类操作会让冷启动时间明显增加。如果一定要读取动态配置，可以把结果缓存在模块级变量中，避免重复计算。

调试参数问题的最直接方式是在函数开头打印 env 和 argv。配置函数只会在 Webpack 启动阶段执行一次，console.log 不会干扰编译结果。执行 npx webpack --env production --env appVersion=3.1.0 后，确认输出是否为 { production: true, appVersion: '3.1.0' }，可以快速判断解析是否符合预期。

函数式配置是 Webpack 多环境管理中最灵活的方式之一。它不要求你放弃拆分文件，反而可以和 webpack-merge 组合使用。把握好 env 的来源、避免在函数里做高成本操作、把敏感信息交给真正的环境变量，这套模式就能稳定支撑中大型前端工程。

Webpack配置函数env多环境配置修改时间：2026-10-03 17:48:16