Dotenv 配置

webpackjsorg-main配置参考

Dotenv 配置

dotenv 选项允许 webpack 从 .env 文件中加载内置的环境变量。

boolean object

启用并配置内置的 Dotenv 插件，以从 .env 文件加载环境变量。

webpack.config.js

js 复制代码

export default {
  // ...
  dotenv: true,
};

将 dotenv 设置为 true 将使用默认选项启用该插件。如需自定义配置，可以传入一个选项对象：

js 复制代码

export default {
  // ...
  dotenv: {
    prefix: "WEBPACK_",
    dir: true,
    template: [".env", ".env.local", ".env.[mode]", ".env.[mode].local"],
  },
};

选项

`prefix`

string string[]

默认值： 'WEBPACK_'

仅暴露以指定前缀开头的环境变量。这可以防止意外暴露敏感变量。

webpack.config.js

js 复制代码

export default {
  // ...
  dotenv: {
    prefix: "APP_", // 仅暴露 APP_* 变量
  },
};

多个前缀：

js 复制代码

export default {
  // ...
  dotenv: {
    prefix: ["APP_", "CONFIG_"], // 同时暴露 APP_* 和 CONFIG_* 变量
  },
};

T> 出于安全原因，不允许使用空字符串 '' 作为前缀，因为它会暴露所有环境变量。

`dir`

boolean string

默认值： true

加载 .env 文件的目录。

true - 从项目根目录（context）加载
false - 禁用 .env 文件加载
string - 相对于项目根目录的路径或绝对路径

webpack.config.js

js 复制代码

export default {
  // ...
  dotenv: {
    dir: "./config", // 从 ./config 目录加载
  },
};

禁用加载：

js 复制代码

export default {
  // ...
  dotenv: {
    dir: false, // 仅使用 process.env 变量
  },
};

`template`

string[]

默认值： ['.env', '.env.local', '.env.[mode]', '.env.[mode].local']

.env 文件名的模板模式。使用 [mode] 作为 webpack 模式（例如 development、production）的占位符。

文件按指定顺序加载，后面的文件会覆盖前面的文件。

webpack.config.js

js 复制代码

export default {
  // ...
  mode: "production",
  dotenv: {
    template: [".env", ".env.production"], // 仅加载这两个文件
  },
};

自定义模式：

js 复制代码

export default {
  // ...
  dotenv: {
    template: [
      ".env",
      ".env.local",
      ".env.[mode]",
      ".env.[mode].local",
      ".env.override", // 始终最后加载
    ],
  },
};

T> [mode] 占位符将替换为当前 webpack 模式。例如，在 production 模式下，.env.[mode] 将变为 .env.production。

文件优先级

环境文件按顺序加载，后面的文件具有更高的优先级：

.env - 在所有模式下加载
.env.local - 在所有模式下加载，被 git 忽略（约定）
.env.[mode] - 仅在指定模式下加载（例如 .env.production）
.env.[mode].local - 仅在指定模式下加载，被 git 忽略

后面文件中的变量会覆盖前面文件中的变量。此外，已经在 process.env 中设置的变量具有最高优先级。

变量展开

环境变量会使用 dotenv-expand 语法自动展开：

.env

bash 复制代码

WEBPACK_API_BASE=https://api.example.com
WEBPACK_API_URL=${WEBPACK_API_BASE}/v1
WEBPACK_PORT=${WEBPACK_PORT:-3000}  # 使用 process.env 中的 WEBPACK_PORT，或默认使用 3000

在代码中：

js 复制代码

console.log(process.env.WEBPACK_API_URL); // "https://api.example.com/v1"
console.log(process.env.WEBPACK_PORT); // 如果设置了 process.env.WEBPACK_PORT 则为其值，否则为 "3000"

T> 在展开过程中，你可以引用 process.env 中的任何变量（例如 ${PORT}），但只有具有指定前缀（例如 WEBPACK_）的变量才会在你的最终打包产物中暴露。在上面的示例中，${WEBPACK_PORT:-3000} 引用的是 process.env 中的 WEBPACK_PORT（如果存在）。

展开行为示例：

bash 复制代码

# .env 文件
WEBPACK_API_URL=${API_BASE:-https://default.com}/api

bash 复制代码

# 使用环境变量运行
API_BASE=https://custom.com npm run build

结果：process.env.WEBPACK_API_URL 将为 "https://custom.com/api"，因为在展开过程中使用了 process.env 中的 API_BASE，即使 API_BASE 本身不会在打包产物中暴露（它没有 WEBPACK_ 前缀）。

使用示例

基本用法

在项目根目录创建 .env 文件：

.env

bash 复制代码

WEBPACK_API_URL=https://api.example.com
WEBPACK_FEATURE_FLAG=true
SECRET_KEY=should-not-be-exposed  # 不会被暴露（没有 WEBPACK_ 前缀）

webpack.config.js

js 复制代码

export default {
  // ...
  dotenv: true, // 使用默认前缀 "WEBPACK_"
};

在应用程序中：

js 复制代码

console.log(process.env.WEBPACK_API_URL); // "https://api.example.com"
console.log(process.env.WEBPACK_FEATURE_FLAG); // "true"
console.log(process.env.SECRET_KEY); // undefined（未暴露）

按模式配置

创建特定模式的文件：

.env

bash 复制代码

WEBPACK_API_URL=https://api.example.com
WEBPACK_DEBUG=false

.env.production

bash 复制代码

WEBPACK_API_URL=https://prod-api.example.com
WEBPACK_DEBUG=false

.env.development

bash 复制代码

WEBPACK_API_URL=https://dev-api.example.com
WEBPACK_DEBUG=true

使用 --mode production 构建时，WEBPACK_API_URL 将为 "https://prod-api.example.com"。

多个前缀

暴露具有不同前缀的变量：

.env

bash 复制代码

APP_NAME=MyApp
APP_VERSION=1.0.0
CONFIG_TIMEOUT=5000
CONFIG_RETRY=3
PRIVATE_KEY=secret  # 不会被暴露

webpack.config.js

js 复制代码

export default {
  // ...
  dotenv: {
    prefix: ["APP_", "CONFIG_"],
  },
};

自定义目录和模板

从自定义位置加载环境文件并使用自定义命名：

webpack.config.js

js 复制代码

export default {
  // ...
  dotenv: {
    dir: "./environments",
    template: [".env.base", ".env.[mode]"],
  },
};

这将加载：

./environments/.env.base
./environments/.env.production（在 production 模式下）

安全注意事项

W> 切勿将敏感数据提交到版本控制！

使用 .gitignore 排除 .env.local 和 .env.[mode].local 文件
仅暴露具有特定前缀的环境变量
切勿使用空字符串 '' 作为前缀
考虑为不同环境使用不同的 .env 文件
将生产环境密钥存储在部署平台的环境变量中

.gitignore

bash 复制代码

# local env files
.env.local
.env.*.local

帮助我们改进文档

发现翻译问题或内容错误？请告诉我们。