env-manager

环境变量管理器（env-manager）

为现代 Web 应用提供全面的环境变量校验、安全扫描和管理功能。

概述

env-manager 技能为本地开发、CI/CD 流水线和部署平台提供系统化的环境变量管理，防止变量缺失、密钥泄露和框架特定配置错误等常见问题。

主要功能：

• 框架感知校验：支持 Next.js、Vite、React、Node.js、Flask
• 安全优先：绝不记录密钥，可检测泄露的凭据
• 平台集成：适用于 Vercel、Railway、Heroku 和 CI/CD
• 快速：0.025 秒内校验 1000 个变量（比 2 秒的目标快 80 倍）
• 零依赖：纯 Python，可在任何环境中运行

为什么使用 env-manager？

可解决的常见问题：

• “在我的机器上能运行，但在生产环境不行”（缺少环境变量）
• 意外在客户端代码中暴露 API 密钥（NEXT_PUBLIC_ 中包含密钥）
• 部署时缺少必需变量
• 团队成员之间的 .env 文件不一致
• 没有必需环境变量的文档
• 密钥泄露导致的安全漏洞

快速开始

安装

无需安装！env-manager 是 Claude MPM 中内置的技能。

要求：

• Python 3.7+
• 无外部依赖

5 分钟快速开始

# 1. Validate your .env file
python3 scripts/validate_env.py .env

# 2. Check for framework-specific issues (Next.js example)
python3 scripts/validate_env.py .env --framework nextjs

# 3. Compare with .env.example to find missing vars
python3 scripts/validate_env.py .env --compare-with .env.example

# 4. Generate .env.example for documentation
python3 scripts/validate_env.py .env --generate-example .env.example

# 5. Get JSON output for CI/CD integration
python3 scripts/validate_env.py .env --json

就这么简单！现在，环境变量已通过专业方式完成校验。

使用示例

基本校验

检查 .env 文件的结构问题：

python3 scripts/validate_env.py .env

检查内容：

• key=value 格式是否有效
• 是否存在重复键
• 命名规范是否正确（UPPERCASE_WITH_UNDERSCORES）
• 是否存在空值（除非明确允许）
• 含空格的值是否使用了正确的引号

输出示例：

✅ Validation successful!
   - 15 variables validated
   - 0 errors
   - 0 warnings

框架特定校验

Next.js

校验 Next.js 环境变量：

python3 scripts/validate_env.py .env.local --framework nextjs

Next.js 特定检查：

• NEXT_PUBLIC_* 变量会暴露给客户端（检测到密钥时会发出警告）
• .env.local、.env.production、.env 的层级关系
• 检测客户端变量中的密钥

示例：

# .env.local
NEXT_PUBLIC_API_URL=https://api.example.com
NEXT_PUBLIC_API_KEY=secret123  # ⚠️  WARNING: Secret in client-exposed variable!
DATABASE_URL=postgresql://...   # ✅ Server-side only

Vite

python3 scripts/validate_env.py .env --framework vite

Vite 特定检查：

• VITE_* 变量会暴露给客户端
• 检测到 VITE_ 前缀变量中包含密钥时会发出警告

React（Create React App）

python3 scripts/validate_env.py .env --framework react

React 特定检查：

• REACT_APP_* 变量会暴露给客户端
• 检测到 REACT_APP_ 前缀变量中包含密钥时会发出警告

Node.js/Express

python3 scripts/validate_env.py .env --framework nodejs

Node.js 特定检查：

• 常见的 NODE_ENV、PORT、DATABASE_URL 模式
• Node.js 标准规范

Flask/Python

python3 scripts/validate_env.py .env --framework flask

Flask 特定检查：

• FLASK_APP、FLASK_ENV 变量
• SQLAlchemy DATABASE_URL 格式

与 .env.example 比较

确保 .env 包含所有必需变量：

python3 scripts/validate_env.py .env --compare-with .env.example

检查内容：

• .env.example 中的所有变量都存在于 .env 中
• .env 中没有额外的未记录变量

输出示例：

❌ Missing variables:
   - DATABASE_URL (required in .env.example)
   - STRIPE_SECRET_KEY (required in .env.example)

⚠️  Extra variables not in .env.example:
   - DEBUG_MODE (consider adding to .env.example)

适用场景：

• 帮助新团队成员入门
• CI/CD 校验
• 部署前检查

生成 .env.example

为环境变量生成文档：

python3 scripts/validate_env.py .env --generate-example .env.example

功能：

• 读取 .env 文件
• 清理密钥值（替换为占位符）
• 使用安全的默认值生成 .env.example

示例：

# Input: .env
DATABASE_URL=postgresql://user:pass@localhost/db  # pragma: allowlist secret
STRIPE_SECRET_KEY=sk_live_abc123xyz
NEXT_PUBLIC_API_URL=https://api.example.com

# Output: .env.example
DATABASE_URL=postgresql://user:password@localhost/dbname  # pragma: allowlist secret
STRIPE_SECRET_KEY=your_stripe_secret_key_here
NEXT_PUBLIC_API_URL=https://api.example.com

**安全说明：**env-manager 可检测常见密钥模式，并将其替换为安全的占位符。

CI/CD 集成

获取适用于自动化工作流的机器可读 JSON 输出：

python3 scripts/validate_env.py .env.example --strict --json

JSON 输出格式：

{
  "valid": true,
  "errors": [],
  "warnings": [],
  "stats": {
    "total_vars": 15,
    "errors": 0,
    "warnings": 0
  }
}

退出代码：

• 0：校验通过
• 1：发现校验错误
• 2：缺少必需文件
• 3：发现警告（仅限 --strict 模式）

GitHub Actions 示例：

name: Validate Environment Variables

on: [push, pull_request]

jobs:
  validate-env:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Validate .env.example
        run: |
          python3 scripts/validate_env.py .env.example --strict --json
        working-directory: ./path/to/skill

      - name: Check for framework-specific issues
        run: |
          python3 scripts/validate_env.py .env.example --framework nextjs --json
        working-directory: ./path/to/skill

严格模式

将警告视为错误（适用于 CI/CD）：

python3 scripts/validate_env.py .env --strict

使用场景：

• 部署前验证
• CI/CD 流水线
• 发布门禁
• 强制执行团队标准

安静模式

仅显示错误，隐藏警告：

python3 scripts/validate_env.py .env --quiet

使用场景：

• 已经审查过警告
• 只关注错误的自动化脚本
• 警告会造成干扰的嘈杂环境

支持的框架

框架	前缀	暴露给客户端	备注
Next.js	NEXT_PUBLIC_*	是	自动暴露在浏览器中
Vite	VITE_*	是	打包到客户端代码中
React (CRA)	REACT_APP_*	是	嵌入生产构建中
Node.js	N/A	否	仅限服务端
Flask	N/A	否	仅限服务端

**安全警告：**切勿在暴露给客户端的变量（NEXT_PUBLIC_、VITE_、REACT_APP_）中放入密钥。如果 env-manager 检测到常见的密钥模式，会发出警告。

CLI 参考

命令结构

python3 scripts/validate_env.py <file> [options]

选项

选项	说明	示例
--compare-with FILE	与 .env.example 比较	--compare-with .env.example
--framework {nextjs|vite|react|nodejs|flask|generic}	框架专属验证	--framework nextjs
--strict	将警告视为错误	--strict
--json	用于自动化的 JSON 输出	--json
--quiet	仅显示错误	--quiet
--generate-example OUTPUT	生成 .env.example	--generate-example .env.example

退出代码

代码	含义	情况
0	成功	无错误（除非启用 --strict，否则允许有警告）
1	验证错误	结构问题、重复项等
2	文件未找到	指定的 .env 文件不存在
3	严格模式下存在警告	存在警告且已启用 --strict

常见使用场景

场景 1：新开发者入职

# New developer clones repo
git clone <repo>
cd <project>

# Copy example and fill in values
cp .env.example .env
# Edit .env with actual values...

# Validate setup
python3 scripts/validate_env.py .env --compare-with .env.example

# If missing variables, fix them
# Validation passes ✅

场景 2：部署前检查

# Before deploying to Vercel/Railway/Heroku
python3 scripts/validate_env.py .env.production --framework nextjs --strict

# Fix any errors
# Deploy with confidence ✅

场景 3：安全审计

# Check for accidentally exposed secrets
python3 scripts/validate_env.py .env.local --framework nextjs

# Look for warnings like:
# ⚠️  NEXT_PUBLIC_STRIPE_SECRET: Contains potential secret in client-exposed variable

场景 4：团队文档

# After adding new environment variable
echo "NEW_API_KEY=abc123" >> .env

# Regenerate .env.example
python3 scripts/validate_env.py .env --generate-example .env.example

# Commit updated .env.example
git add .env.example
git commit -m "docs: add NEW_API_KEY to environment variables"

场景 5：CI/CD 质量门禁

# In your CI pipeline
- name: Validate environment configuration
  run: |
    python3 scripts/validate_env.py .env.example --strict --json > validation.json

    # Fail pipeline if validation fails
    if [ $? -ne 0 ]; then
      cat validation.json
      exit 1
    fi

性能

env-manager 专为速度而设计：

基准测试：

• 验证 1000 个变量仅需 0.025s
• 比 2s 的目标快 80 倍
• 零外部依赖
• 内存占用极低

优势：

• 开发期间快速获得反馈
• 不会拖慢 CI/CD
• 可在资源受限的环境中运行

安全说明

关键安全功能：

1. **绝不记录密钥：**env-manager 绝不会在输出中显示实际密钥值
2. **检测客户端暴露：**当密钥位于 NEXT_PUBLIC_、VITE_、REACT_APP_ 变量中时发出警告
3. **密钥清理：**生成 .env.example 时，将密钥替换为安全的占位符
4. **无网络请求：**所有验证均在本地进行，数据不会离开你的计算机

**已通过安全审计：**此技能已接受安全审查。详情请参阅 references/security.md。

最佳实践：

• 切勿提交包含密钥的 .env 文件
• 始终使用 .env.example 编写文档
• 在生产环境中使用平台密钥管理器（Vercel、Railway 等）
• 每次部署前都进行验证
• 定期运行安全扫描

常见问题

“缺少等号”错误

原因：.env 中的行缺少 = 分隔符

解决方法：

# ❌ Bad
API_KEY

# ✅ Good
API_KEY=your_key_here

“重复键”错误

**原因：**同一变量被定义多次

解决方法：

# ❌ Bad
API_KEY=value1
API_KEY=value2

# ✅ Good
API_KEY=value2

“变量名无效”警告

**原因：**变量名不符合 UPPERCASE_WITH_UNDERSCORES 约定

解决方法：

# ❌ Bad
apiKey=value
api-key=value

# ✅ Good
API_KEY=value

“暴露给客户端的变量中可能包含密钥”警告

**原因：**NEXT_PUBLIC_、VITE_ 或 REACT_APP_ 变量包含类似密钥的值

解决方法：

# ❌ Bad (secret exposed to client!)
NEXT_PUBLIC_STRIPE_SECRET=sk_live_abc123

# ✅ Good (server-side only)
STRIPE_SECRET_KEY=sk_live_abc123
NEXT_PUBLIC_STRIPE_PUBLISHABLE=pk_live_xyz789

“值为空”警告

**原因：**变量没有值

解决方法：

# ❌ Bad
DATABASE_URL=

# ✅ Good (if optional, document it)
DATABASE_URL=  # Optional, uses SQLite if not set

# ✅ Better
DATABASE_URL=postgresql://localhost/mydb

文件未找到错误

**原因：**指定的 .env 文件不存在

解决方法：

# Check file exists
ls -la .env

# Or create it
touch .env

故障排除

本地验证通过，但在 CI 中失败

检查：

1. 行尾符（CRLF 与 LF）
2. 文件编码（预期为 UTF-8）
3. 文件权限
4. Python 版本（需要 3.7+）

关于客户端可见变量的警告

这是有意为之！ env-manager 正在提醒你，NEXT_PUBLIC_API_KEY 等变量会在浏览器中可见。

选项：

1. 将密钥移至服务端变量（移除 NEXT_PUBLIC_ 前缀）
2. 仅在客户端可见变量中使用公开密钥／可发布密钥
3. 如果确实不是密钥，则忽略此警告

.env.example 生成时替换内容过多

env-manager 对密钥采取保守处理。如果清理过度：

1. 生成后手动编辑 .env.example
2. 在 .env 中使用不会触发清理的特定占位值

高级用法

自定义验证模式

有关高级验证模式，请参阅 references/validation.md。

特定平台部署

有关 Vercel、Railway、Heroku 集成模式，请参阅 references/synchronization.md。

特定框架指南

有关全面的框架指南，请参阅 references/frameworks.md。

相关文档

• 验证参考：完整的验证工作流和检查项
• 安全参考：密钥扫描和安全模式
• 同步参考：平台同步模式（即将推出）
• 框架参考：特定框架的模式和约定
• 故障排除指南：常见问题及解决方案

与 Claude MPM 集成

env-manager 是 Claude MPM 中捆绑的技能。Agent 可以将其用于：

• 部署前验证
• 安全扫描
• 环境设置验证
• 文档生成

有关 Agent 集成模式，请参阅 INTEGRATION.md。

贡献

env-manager 遵循 Claude MPM 贡献指南：

1. 开发期间运行 make lint-fix
2. 提交前运行 make quality
3. 为新功能添加测试（要求覆盖率达到 85%+）
4. 更新文档

详情请参阅 CONTRIBUTING.md。

许可证

MIT 许可证 - Claude MPM 项目的一部分

支持

• 问题：通过 GitHub Issues 报告错误
• 文档：请参阅 references/ 目录
• 示例：请参阅 examples/ 目录
• 集成：请参阅 INTEGRATION.md

---

版本：1.0.0 状态：稳定，已通过安全审计 测试覆盖率：85%+ 性能：比目标快 80 倍