dotenvx

dotenvx CLI

dotenvx 是一个安全的 dotenv 工具，由 dotenv 的创建者开发。它提供加密环境变量、跨平台的 run 注入和多环境支持。

主要功能：

• dotenvx run — 将环境变量注入任意命令和任意语言
• dotenvx encrypt — 使用公钥密码学（secp256k1）加密 .env 文件
• dotenvx set / get — 管理单个环境变量
• dotenvx decrypt — 将 .env 文件解密回明文
• 通过 -f 标志和 DOTENV_PRIVATE_KEY_* 命名约定支持多环境

安装

# npm (local to project)
npm install @dotenvx/dotenvx --save

# global installs
curl -sfS https://dotenvx.sh | sh       # curl
brew install dotenvx/brew/dotenvx        # brew
winget install dotenvx                   # windows
docker run -it --rm -v $(pwd):/app dotenv/dotenvx help  # docker

对于 Node.js，也可以作为库使用：

require('@dotenvx/dotenvx').config()
// or: import '@dotenvx/dotenvx/config'

---

核心命令

dotenvx run

将 .env 文件中的环境变量注入任意进程。这是主要命令。

dotenvx run -- <command>

标志：

标志	描述
-f <file>	指定环境文件。可重复使用。默认值：.env
--env KEY=value	设置内联环境变量
--overload	后面的文件/值覆盖前面的文件/值（默认采用第一个值）
--strict	发生任何错误时以代码 1 退出（文件缺失、解密失败）
--ignore=ERROR_CODE	忽略特定错误（例如 MISSING_ENV_FILE）
--convention=nextjs|flow	使用 Next.js 或 dotenv-flow 约定加载文件
-fk <path>	指定 .env.keys 文件的路径（适用于 monorepo）
--quiet	除错误外，抑制所有输出
--verbose	详细日志记录
--debug	调试级别日志记录
--log-level=<level>	设置日志级别：error, warn, info, verbose, debug, silly

示例：

# Basic usage
dotenvx run -- node index.js

# Specific env file
dotenvx run -f .env.production -- node index.js

# Multiple env files (first file's values win by default)
dotenvx run -f .env.local -f .env -- node index.js

# Override: last file wins
dotenvx run -f .env.local -f .env --overload -- node index.js

# Inline env var (overrides file values)
dotenvx run --env HELLO=String -f .env -- node index.js

# Any language works
dotenvx run -- python3 app.py
dotenvx run -- ruby index.rb
dotenvx run -- go run main.go
dotenvx run -- cargo run
dotenvx run -- php artisan serve
dotenvx run -- next dev

# Shell expansion (use subshell to prevent premature expansion)
dotenvx run --env="HELLO=World" -- sh -c 'echo Hello $HELLO'

# Strict mode for CI
dotenvx run -f .env.ci --strict -- node build.js

优先级规则：

• 默认情况下，Shell 中已设置的环境变量优先于 .env 文件中的值
• 使用多个 -f 文件时，第一个文件中的值优先（dotenv 的历史行为）
• --overload 会反转此规则：后面的文件覆盖前面的文件
• --env 标志的值优先于文件中的值

变量展开和插值：

dotenvx 支持在 .env 文件中使用 ${VAR} 展开、默认值、备用值和命令替换：

# Variable expansion
USERNAME="admin"
DATABASE_URL="postgres://${USERNAME}@localhost/mydb"

# Default values (use fallback if unset/empty)
DB_HOST=${DB_HOST:-localhost}
DB_PORT=${DB_PORT:-5432}

# Alternate values (use alternate if variable IS set)
DEBUG_MODE=${NODE_ENV:+false}

# Command substitution
WHOAMI="$(whoami)"

支持多行值——用双引号括起来：

CERT="-----BEGIN CERTIFICATE-----
MIIB...
-----END CERTIFICATE-----"

重要提示：dotenvx 不具备的功能

请勿臆造以下功能——它们并不存在：

• ❌ dotenvx keys — 请改用 dotenvx keypair
• ❌ dotenvx status — 不存在此命令
• ❌ dotenvx rotate — 如需轮换，请使用 dotenvx set 更新值，或先解密 → 删除 .env.keys → 再重新加密
• ❌ --env-name 标志 — 不存在
• ❌ .env.vault 文件 — dotenvx 会原地加密，而不是加密到单独的保险库文件
• ❌ DOTENVX_PRIVATE_KEY — 正确的环境变量是 DOTENV_PRIVATE_KEY（中间没有 X）
• ❌ pip install dotenvx — 没有 Python 包；dotenvx 是一个可封装任意语言的 CLI 工具
• ❌ dotenvx.load_dotenv() — 没有 Python API；请在 CLI 层使用 dotenvx run -- python app.py

---

dotenvx encrypt

原地加密 .env 文件。生成 DOTENV_PUBLIC_KEY（添加到 .env 文件中）和 DOTENV_PRIVATE_KEY（保存到 .env.keys）。

dotenvx encrypt                     # encrypts .env
dotenvx encrypt -f .env.production  # encrypts specific file
dotenvx encrypt --stdout            # output to stdout instead of in-place

加密后：

• .env 包含加密后的值和 DOTENV_PUBLIC_KEY
• .env.keys 包含 DOTENV_PRIVATE_KEY（请妥善保管，切勿提交）
• 加密后的 .env 可以安全地提交到版本控制中

dotenvx decrypt

将加密的 .env 文件解密回明文。

dotenvx decrypt                     # decrypts .env
dotenvx decrypt -f .env.production  # decrypts specific file
dotenvx decrypt --stdout            # output to stdout

需要能够获取私钥（通过 .env.keys 文件或 DOTENV_PRIVATE_KEY* 环境变量）。

dotenvx set

在 .env 文件中设置单个环境变量。文件不存在时会创建。如果文件已加密，会自动重新加密。

dotenvx set KEY value                       # set in .env
dotenvx set KEY value -f .env.production    # set in specific file
dotenvx set KEY "multi word value"          # quoted values
dotenvx set KEY value -fk .env.keys -f apps/app1/.env  # monorepo

dotenvx get

获取单个环境变量的值。

dotenvx get HELLO                          # from .env
dotenvx get HELLO -f .env.production       # from specific file
dotenvx get HELLO --env HELLO=Override     # from --env string
dotenvx get HELLO --overload               # with overload semantics
dotenvx get HELLO --strict                 # exit 1 if key missing
dotenvx get HELLO --convention=nextjs      # with convention
dotenvx get HELLO -fk .env.keys -f app/.env  # monorepo

以 JSON 格式获取全部变量：

dotenvx get                    # all vars from .env as JSON
dotenvx get -f .env.production # all vars from specific file
dotenvx get --all              # include DOTENV_PUBLIC_KEY
dotenvx get --format shell     # output as KEY=value lines

dotenvx keypair

输出加密 .env 文件的公钥/私钥对。

dotenvx keypair                              # all keypairs as JSON
dotenvx keypair DOTENV_PRIVATE_KEY           # just the private key
dotenvx keypair -f .env.production           # for specific file
dotenvx keypair DOTENV_PRIVATE_KEY_PRODUCTION -f .env.production

---

加密工作流

初始设置

# 1. Create your .env
echo "DATABASE_URL=postgres://localhost/mydb" > .env
echo "API_KEY=sk-secret123" >> .env

# 2. Encrypt it
dotenvx encrypt
# ✔ encrypted (.env)
# Creates .env.keys with your private key

# 3. Commit .env (encrypted, safe), do NOT commit .env.keys
echo ".env.keys" >> .gitignore
git add .env .gitignore
git commit -m "add encrypted env"

多环境加密

每个环境都有自己的密钥对。命名约定会自动应用：

# Encrypt each environment
dotenvx encrypt -f .env.production
dotenvx encrypt -f .env.staging
dotenvx encrypt -f .env.ci

# Each creates a corresponding private key in .env.keys:
# DOTENV_PRIVATE_KEY_PRODUCTION="..."
# DOTENV_PRIVATE_KEY_STAGING="..."
# DOTENV_PRIVATE_KEY_CI="..."

运行时解密

设置相应的 DOTENV_PRIVATE_KEY_* 环境变量，dotenvx run 会自动解密：

# The private key suffix matches the file suffix
DOTENV_PRIVATE_KEY="key"                  dotenvx run -- node app.js          # decrypts .env
DOTENV_PRIVATE_KEY_PRODUCTION="key"       dotenvx run -- node app.js          # decrypts .env.production
DOTENV_PRIVATE_KEY_CI="key"               dotenvx run -- node app.js          # decrypts .env.ci

# Combine multiple
DOTENV_PRIVATE_KEY="k1" DOTENV_PRIVATE_KEY_PRODUCTION="k2" dotenvx run -- node app.js

# Comma-separated keys for monorepos (same environment, different apps)
DOTENV_PRIVATE_KEY_CI="key1,key2" dotenvx run -f app1/.env.ci -f app2/.env.ci -- node app.js

CI/CD 集成

# GitHub Actions example
name: deploy
on: [push]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: curl -fsS https://dotenvx.sh/install.sh | sh
      - run: dotenvx run -- node build.js
        env:
          DOTENV_PRIVATE_KEY_PRODUCTION: ${{ secrets.DOTENV_PRIVATE_KEY_PRODUCTION }}

---

约定

--convention=nextjs

按 Next.js 优先级顺序加载文件：

1. .env.$(NODE_ENV).local
2. .env.local
3. .env.$(NODE_ENV)
4. .env

dotenvx run --convention=nextjs -- next dev

--convention=flow

按 dotenv-flow 优先级顺序加载文件。使用 DOTENV_ENV 或 NODE_ENV：

DOTENV_ENV=development dotenvx run --convention=flow -- node app.js

---

Monorepo 支持

使用 -fk 指定共享的 .env.keys 路径：

# Set values for different apps
dotenvx set HELLO app1 -fk .env.keys -f apps/app1/.env
dotenvx set HELLO app2 -fk .env.keys -f apps/app2/.env

# Run with shared keys
dotenvx run -fk .env.keys -f apps/app1/.env -- node apps/app1/index.js

# Get values
dotenvx get HELLO -fk .env.keys -f apps/app1/.env

---

Docker

FROM node:latest
RUN curl -fsS https://dotenvx.sh/install.sh | sh
COPY . .
CMD ["dotenvx", "run", "--", "node", "index.js"]

或者直接运行：

docker run -it --rm -v $(pwd):/app dotenv/dotenvx run -- node index.js

---

常见模式

向加密文件添加新密钥：

dotenvx set NEW_SECRET "value" -f .env.production
# Automatically re-encrypts

轮换一个值：

dotenvx set API_KEY "new-key-value" -f .env.production

查看解密后的值，但不运行命令：

dotenvx get -f .env.production           # needs private key available
dotenvx get API_KEY -f .env.production   # single value

将现有的明文 .env 转换为加密文件：

dotenvx encrypt -f .env.production
# Done. Commit the encrypted .env.production, store .env.keys privately.

在脚本中禁止 dotenvx 输出：

dotenvx run --quiet -- ./my-script.sh

在 CI 中遇到缺失或损坏的环境变量时失败：

dotenvx run -f .env.ci --strict -- npm test

---

Gitignore 建议

# Never commit private keys
.env.keys

# Encrypted .env files ARE safe to commit
# !.env
# !.env.production
# !.env.staging

故障排除

• MISSING_ENV_FILE — 指定的 .env 文件不存在。请创建该文件，或使用 --ignore=MISSING_ENV_FILE。
• MISSING_KEY — 请求的密钥不在 .env 文件中。
• 解密失败 — 请确保已设置正确的 DOTENV_PRIVATE_KEY_*。后缀必须与文件后缀一致（例如，.env.production 对应 _PRODUCTION）。
• Deno + encrypt — 不要使用 deno run npm:@dotenvx/dotenvx encrypt。Deno 的密码算法支持不完整。请改为将 dotenvx 安装为二进制文件。
• Shell 提前展开 $VARS — 使用子 Shell：dotenvx run -- sh -c 'echo $MY_VAR'

---

扩展命令（dotenvx ext）

用于管理 dotenvx 工作流的实用命令：

dotenvx ext genexample                  # generate .env.example from .env
dotenvx ext genexample -f .env.production  # from specific file
dotenvx ext gitignore                   # append .env.keys to .gitignore
dotenvx ext ls                          # list all .env files in project
dotenvx ext ls -f .env.production       # check specific file
dotenvx ext settings                    # view current dotenvx settings