Webpack 中如何使用 dotenv-webpack 加载 .env 环境变量文件？

在 Webpack 打包前端应用时，环境变量常被用来区分开发、测试、生产环境，注入不同的接口地址、功能开关或第三方密钥。手动在构建脚本里拼接这些变量容易出错，而 dotenv-webpack 插件提供了一种更简洁的方式：让 Webpack 直接读取项目根目录下的 .env 文件，把里面的键值对转换成编译时全局常量。这样开发者可以在源码中通过 process.env.XXX 访问，同时保持 .env 文件不被提交到版本库。

dotenv-webpack 解决了什么问题

在 Node.js 后端项目里，dotenv 是一个广泛使用的库，它会在应用启动时读取 .env 文件并把变量写入 process.env。但前端构建流程不同，Webpack 打包出的代码运行在浏览器中，浏览器并没有 Node.js 的 process 对象，因此不能直接在浏览器代码里使用 dotenv。早期开发者往往通过 DefinePlugin 手动声明每个环境变量，或者在 package.json 的脚本里用 cross-env 设置系统环境变量，再让 Webpack 读取。这些做法在变量较多时维护成本高，而且 .env 文件无法直接复用。

dotenv-webpack 正是把 dotenv 的解析能力和 Webpack 的构建流程结合起来。它在 Webpack 编译阶段读取 .env 文件，解析出的变量会通过 DefinePlugin 注入到 bundle 中。这样源代码里的 process.env.API_URL 会被替换成字符串常量，例如“https://api.ipipp.com”，而不是在运行时才去查找。这种方式既保留了 .env 文件的集中管理优势，又避免了浏览器环境缺失 process 的问题。

另一个重要意义是，dotenv-webpack 让前端项目的环境配置可以与后端保持一致的格式，同一个 .env 文件可以被 Node 脚本、Webpack 构建、甚至 CI 工具共同读取。对于需要统一配置管理的团队来说，这减少了上下文切换和重复定义的成本。

安装与基础配置

安装 dotenv-webpack 非常简单，在已有 Webpack 项目的根目录下执行 npm 或 yarn 命令即可。它作为一个 Webpack 插件使用，不需要额外修改 entry 或 loader。安装完成后，在 webpack.config.js 中引入并实例化，放入 plugins 数组。

npm install dotenv-webpack --save-dev

接着在 Webpack 配置文件中添加插件。默认情况下，插件会读取项目根目录下的 .env 文件，如果该文件不存在则静默跳过，不会导致构建失败。下面是一个最简配置。

const Dotenv = require('dotenv-webpack');

module.exports = {
  // 其他配置省略
  plugins: [
    new Dotenv()
  ]
};

如果 .env 文件不在根目录，或者想要加载指定名称的文件，可以通过 path 参数指定路径。该参数支持相对路径和绝对路径。例如加载 .env.production 文件，可以这样设置。

const Dotenv = require('dotenv-webpack');

module.exports = {
  plugins: [
    new Dotenv({
      path: './.env.production'
    })
  ]
};

dotenv-webpack 还支持许多 dotenv 的原生选项，比如 encoding、debug 等。其中最常用的是 systemvars，它允许插件同时读取系统环境变量，当 .env 文件与系统环境变量冲突时，系统环境变量优先。这在 CI/CD 环境中尤其有用，因为敏感信息通常由 CI 系统注入而不是写在 .env 文件里。

在业务代码中读取环境变量

配置好插件后，就可以在 JavaScript 或 TypeScript 源码中直接使用 process.env.变量名 来读取值。Webpack 在打包时会把所有已注入的变量替换为对应的字符串字面量。比如在 src/config.js 中定义接口基础地址，然后在其他模块中导入使用。

// src/config.js
const config = {
  apiBaseUrl: process.env.API_BASE_URL,
  enableDebug: process.env.ENABLE_DEBUG === 'true'
};

export default config;

需要注意的是，dotenv-webpack 注入的是编译时常量，所以不能用解构赋值的方式动态获取变量名，例如 process.env['API_' + name] 是不会被替换的。必须在代码里写出完整的属性访问路径。另外，由于所有变量值都会以字符串形式存在，布尔值或数字需要手动转换，就像上面 enableDebug 的例子一样。

与直接使用 DefinePlugin 相比，dotenv-webpack 的替换逻辑更加透明：它会为 .env 文件中的每个键生成 process.env.键名 的定义，不需要在 Webpack 配置里逐个列出变量。但要注意，只有 .env 文件中存在的变量才会被注入，如果代码里访问了未定义的变量名，可能会在编译后留下原样的 process.env.XXX，然后在浏览器运行时抛错。可以通过设置 defaults 参数或使用 systemvars 来避免此类问题。

多环境配置与安全实践

真实项目通常需要针对开发、测试、生产环境使用不同的 .env 文件。可以通过 Webpack 的 mode 或自定义环境变量来选择加载哪个文件。例如在 package.json 中通过 cross-env 设置 NODE_ENV，然后在 webpack.config.js 中根据 NODE_ENV 动态指定 path。

const Dotenv = require('dotenv-webpack');
const path = require('path');

module.exports = function(env, argv) {
  const envFile = argv.mode === 'production' ? '.env.production' : '.env.development';
  return {
    plugins: [
      new Dotenv({
        path: path.resolve(__dirname, envFile)
      })
    ]
  };
};

安全方面，.env 文件通常包含敏感信息，如 API 密钥、数据库连接串等，因此必须加入 .gitignore，避免提交到版本库。推荐做法是维护一个 .env.example 文件，列出所有需要的变量名和示例值，让新成员可以复制并填写真实值。对于不需要暴露给客户端的变量，应该只在构建阶段使用，不要将所有 .env 变量都注入到前端 bundle 中。虽然 dotenv-webpack 默认会注入所有变量，但可以通过配置 prefix 参数只注入以特定前缀开头的变量，例如只注入 VUE_APP_ 或 REACT_APP_ 开头的变量，从而减少泄露风险。

另一个常见实践是利用 systemvars: true 让 CI 系统注入生产环境密钥，而 .env 文件只存放非敏感的开发配置。这样即使在日志或错误输出中打印了 process.env，也不会泄露真正的生产密钥。此外，dotenv-webpack 不会处理 .env.local 等特殊文件的优先级，如果需要，可以自行在配置中按顺序合并多个文件，或者使用 dotenv 的 override 选项来控制覆盖行为。

常见问题与替代方案

使用 dotenv-webpack 时，一个典型问题是变量没有生效，通常原因有两个：一是 .env 文件路径不正确，插件没有找到文件；二是变量名书写不一致，比如 .env 中写 API_URL，代码里写 api_url。环境变量名区分大小写，必须完全匹配。另一个坑是缓存问题，修改 .env 文件后需要重新启动 Webpack dev server 或重新构建，因为插件只在编译阶段读取一次。

如果不想引入额外插件，也可以直接使用 dotenv 配合 DefinePlugin 实现类似效果。具体做法是在 webpack.config.js 顶部调用 dotenv.config() 解析 .env 文件，然后把解析结果传给 DefinePlugin。这种方式更加手动，但灵活性更高。例如下面的代码展示了如何将 .env 变量转换成 DefinePlugin 需要的格式。

const webpack = require('webpack');
const dotenv = require('dotenv');

const env = dotenv.config().parsed;
const envKeys = Object.keys(env).reduce(function(prev, key) {
  prev['process.env.' + key] = JSON.stringify(env[key]);
  return prev;
}, {});

module.exports = {
  plugins: [
    new webpack.DefinePlugin(envKeys)
  ]
};

dotenv-webpack 本质上是这种方案的封装，额外处理了 systemvars、路径解析、默认值等细节。对于大型项目或需要快速上手的团队，使用 dotenv-webpack 可以减少配置出错的可能。但如果你需要更细粒度的控制，比如自定义变量替换逻辑或只注入白名单变量，手动组合 dotenv 和 DefinePlugin 仍然是一个值得掌握的技能。

最后，dotenv-webpack 目前主要服务于 Webpack 生态，如果你使用 Vite、Rollup 或 esbuild，它们有各自的环境变量处理机制。理解其底层原理后，迁移到其他构建工具时也能快速上手。

dotenv-webpackWebpack环境变量修改时间：2026-09-19 18:24:09