mcpField
D
dotenvx

dotenvx

github.com/mizchi安全41662 次安装2 周前更新
代码仓库

关于 dotenvx

dotenvx 是用于加载和加密 .env 文件的语言与框架无关工具，帮助开发者管理本地及生产环境变量。

主要功能

  1. 01从 .env 文件加载变量
  2. 02加密和解密环境文件
  3. 03按优先级合并多个文件
  4. 04为不同环境配置密钥

适用场景

  1. 01使用本地覆盖项运行开发命令
  2. 02为发布加载生产环境变量
  3. 03在项目中保存加密环境文件

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/mizchi/skills --skill dotenvx

安装后在 Claude Code 中输入/dotenvx确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

README.md
SKILL-ja.md
assets/
.env.example
env.example
gh_action_example.yaml

详细介绍

dotenvx 技能

dotenvx 是一款用于加载和加密 .env 文件的环境变量管理工具。与语言和框架无关。

安装

# curl (recommended)
curl -sfS https://dotenvx.sh | sh

# brew
brew install dotenvx/brew/dotenvx

# npm
npm install @dotenvx/dotenvx --save

基本命令

# Load environment variables and run a command
dotenvx run -- node index.js

# Specify a particular .env file
dotenvx run -f .env.production -- npm start

# Load multiple files (later ones take precedence)
dotenvx run -f .env -f .env.local -- npm start

# Get an environment variable
dotenvx get DATABASE_URL

# Display all environment variables
dotenvx get

加密

# Encrypt .env (generates DOTENV_PUBLIC_KEY, DOTENV_PRIVATE_KEY)
dotenvx encrypt

# Encrypt a specific file
dotenvx encrypt -f .env.production

# Decrypt
dotenvx decrypt

# Run an encrypted file (requires DOTENV_PRIVATE_KEY)
dotenvx run -- node index.js
加密原理
  • 运行 dotenvx encrypt 会生成一对公钥和私钥
  • DOTENV_PUBLIC_KEY：存储在 .env 文件中（用于加密）
  • DOTENV_PRIVATE_KEY：在本地环境或 CI 中设置（用于解密）
  • 按环境区分：通过 DOTENV_PRIVATE_KEY_PRODUCTION 自动检测

选项

选项说明
-f, --env-file指定 .env 文件
--overload使用后续文件覆盖
--quiet不显示输出
--verbose显示详细输出
--debug显示调试信息

管理多个环境

.env                 # Shared settings
.env.local           # Local overrides (gitignore)
.env.production      # Production
.env.development     # Development

# Run in production
dotenvx run -f .env.production -- npm start

# Development + local overrides
dotenvx run -f .env.development -f .env.local -- npm run dev

轮换密钥

当怀疑私钥已泄露或定期轮换时，请按此流程操作。截至 2026/04，dotenvx 尚无专用的 dotenvx rotate 命令，因此需要明确执行解密 → 使用新密钥加密。

顺序至关重要：先将 CI 密钥更新为新密钥，再合并新的密文。如果顺序相反，生产环境将尝试用旧密钥解密新密文，从而导致故障。

# 1. Working branch + stash old key
git switch -c chore/rotate-prod-dotenv-key
set +o history
OLD_PRIV="$DOTENV_PRIVATE_KEY_PRODUCTION"

# 2. Decrypt with the old key (back to plaintext)
DOTENV_PRIVATE_KEY_PRODUCTION="$OLD_PRIV" dotenvx decrypt -f .env.production

# 3. Remove the existing PUBLIC_KEY, then re-encrypt (a new key pair is generated)
sed -i.bak '/^DOTENV_PUBLIC_KEY_PRODUCTION=/d' .env.production
dotenvx encrypt -f .env.production
NEW_PRIV=$(dotenvx get DOTENV_PRIVATE_KEY_PRODUCTION -f .env.keys)

# 4. Update CI secret to the new key (before the merge)
gh secret set DOTENV_PRIVATE_KEY_PRODUCTION --body "$NEW_PRIV" --env production

# 5. Commit + merge + deploy the new ciphertext
git add .env.production && git commit -m "chore: rotate production dotenv key"
git push && gh pr create --fill && gh pr merge --squash --auto

# 6. Cleanup
unset OLD_PRIV; set -o history
rm .env.production.bak

发生泄露时的其他步骤：

  • Git 历史记录中残留的旧密文仍可使用旧密钥解密。仅轮换密钥并不足够
  • 加密值本身（数据库密码、API 密钥等）也必须同时重新签发
  • 如需从历史记录中彻底移除，请使用 git filter-repo，但强制推送影响很大，操作时务必谨慎

避免停机：也可以采用蓝绿方式，暂时同时保留 DOTENV_PRIVATE_KEY_PRODUCTION 和 DOTENV_PRIVATE_KEY_PRODUCTION_NEW，成功部署后再移除旧密钥。

GitHub Actions

通过 curl 安装。完整示例请参见 assets/gh_action_example.yaml。

steps:
  - uses: actions/checkout@v7

  - name: Install dotenvx
    run: curl -sfS https://dotenvx.sh | sh

  - name: Run tests
    env:
      DOTENV_PRIVATE_KEY: ${{ secrets.DOTENV_PRIVATE_KEY }}
    run: dotenvx run -- npm test

参考资料

评论

支持 Markdown