dotenv 常用命令
dotenv 用于从 .env 文件中加载环境变量到 process.env，是管理项目配置和敏感信息的常用方式。
💡 process.env 是 Node.js 中的全局对象，存储了当前运行环境的所有环境变量。通过
process.env.变量名可以读取环境变量值，常用于区分开发/生产环境、存储 API 地址、数据库密码等配置信息。
安装
bash
# 安装
npm install dotenv使用方式
在 Node.js 项目中使用
js
// 在入口文件最顶部引入
require('dotenv').config()
// 或 ES Module 方式
import 'dotenv/config'
// 使用环境变量
console.log(process.env.API_URL)
console.log(process.env.DB_PASSWORD).env 文件格式
bash
# .env
API_URL=https://api.example.com
DB_HOST=localhost
DB_PORT=5432
DB_PASSWORD=my-secret-password
APP_NAME=My App⚠️
.env文件中不要加空格，KEY = value可能导致解析问题，应写成KEY=value。
多环境配置
bash
# .env（默认）
API_URL=https://api.example.com
# .env.development
API_URL=http://localhost:3000
# .env.production
API_URL=https://api.example.com根据环境加载不同文件：
js
import dotenv from 'dotenv'
import path from 'path'
dotenv.config({
path: path.resolve(process.cwd(), `.env.${process.env.NODE_ENV}`)
})Vite / Webpack 项目
Vite 内置了 dotenv 支持，无需手动安装 dotenv。Webpack 项目通过 DefinePlugin 注入环境变量。
📖 前端项目环境变量的完整用法（文件命名、内置变量、类型声明、CI/CD 配置等）见 环境变量管理
环境变量优先级
- 命令行设置的环境变量（最高优先级）
.env.local文件（本地覆盖，不提交 Git）.env.[mode].local文件（特定模式的本地覆盖）.env.[mode]文件（特定模式）.env文件（默认）
bash
# 加载顺序示例（production 模式）
.env → 基础配置
.env.production → production 模式配置
.env.local → 本地覆盖（不提交 Git）
.env.production.local → production 模式的本地覆盖安全注意事项
.gitignore 配置
bash
# .gitignore
.env
.env.local
.env.*.local⚠️ 永远不要将包含敏感信息的
.env文件提交到 Git。
环境变量分类
| 类型 | 示例 | 是否提交 Git |
|---|---|---|
| 公开配置 | VITE_APP_TITLE | ✅ 可以 |
| 开发配置 | VITE_API_URL=http://localhost:3000 | ✅ 可以 |
| 敏感信息 | DB_PASSWORD, SECRET_KEY | ❌ 不要 |
常见问题
环境变量不生效
bash
# 确保在入口文件最顶部加载
require('dotenv').config() // 必须在使用前调用
# 检查 .env 文件路径
# 默认从项目根目录加载.env.local 不生效
bash
# 确认文件名正确
.env.local ✅
.env.local.js ❌ 不支持
.env.local.json ❌ 不支持
# 确认没有多余空格
API_URL=https://api.example.com ✅
API_URL = https://api.example.com ❌ 可能解析失败类型声明（TypeScript）
创建 env.d.ts 文件：
ts
/// <reference types="vite/client" />
interface ImportMetaEnv {
readonly VITE_API_URL: string
readonly VITE_APP_TITLE: string
}
interface ImportMeta {
readonly env: ImportMetaEnv
}dotenvx（官方推荐）
dotenv 官方推荐使用 dotenvx 作为增强工具，支持：
变量扩展
bash
# .env
USERNAME="username"
DATABASE_URL="postgres://${USERNAME}@localhost/my_database"bash
dotenvx run -- node index.js
# DATABASE_URL = postgres://username@localhost/my_database加密 .env 文件
bash
# 加密
dotenvx set HELLO Production -f .env.production
# 运行时自动解密
DOTENV_PRIVATE_KEY_PRODUCTION="<key>" dotenvx run -- node index.js多环境管理
bash
# 加载指定环境文件
dotenvx run -f=.env.production -- node index.js
# 加载多个文件
dotenvx run -f=.env.local -f=.env -- node index.js命令替换
bash
# .env
DATABASE_URL="postgres://$(whoami)@localhost/my_database"💡 dotenvx 解决了 dotenv 不支持的变量扩展、加密、命令替换等高级场景。