env-setup — 环境变量管理器

扫描代码库中所有引用的环境变量，生成 .env.example，验证当前的 .env 文件，并确保敏感信息未被提交。

步骤

1. 扫描代码库中的环境变量

在常见模式下搜索所有环境变量引用：

# Node.js / JavaScript / TypeScript
grep -rn "process\.env\.\w\+" --include="*.js" --include="*.ts" --include="*.jsx" --include="*.tsx" . | grep -v node_modules | grep -v dist

# Python
grep -rn "os\.environ\|os\.getenv\|environ\.get" --include="*.py" . | grep -v __pycache__ | grep -v .venv

# Rust
grep -rn "env::var\|env::var_os\|dotenv" --include="*.rs" . | grep -v target

# Go
grep -rn "os\.Getenv\|os\.LookupEnv\|viper\." --include="*.go" . | grep -v vendor

# Docker / docker-compose
grep -rn "\${.*}" --include="*.yml" --include="*.yaml" docker-compose* 2>/dev/null

# 配置文件中的通用 .env 引用
grep -rn "env\." --include="*.toml" --include="*.yaml" --include="*.yml" . 2>/dev/null

Windows PowerShell 替代方案：

Get-ChildItem -Recurse -Include *.js,*.ts,*.jsx,*.tsx -Exclude node_modules,dist | Select-String "process\.env\.\w+"
Get-ChildItem -Recurse -Include *.py -Exclude __pycache__,.venv | Select-String "os\.environ|os\.getenv"

2. 提取变量名称

解析 grep 输出，提取唯一的变量名：

• process.env.DATABASE_URL → DATABASE_URL
• os.environ.get("SECRET_KEY", "default") → SECRET_KEY（默认值：default）
• os.getenv("API_KEY") → API_KEY
• env::var("RUST_LOG") → RUST_LOG

去重并按字母顺序排序。记录每个变量所在的文件和行号。

3. 分类变量

对每个变量进行分类：

4. 生成 .env.example

创建包含说明、类别和安全默认值的 .env.example：

# ============================================
# 环境配置
# 由 env-setup 工具生成
# ============================================

# --- 应用配置 ---
NODE_ENV=development
PORT=3000
LOG_LEVEL=info

# --- 数据库 ---
DATABASE_URL=postgresql://user:password@localhost:5432/dbname

# --- 认证（🔴 敏感信息 — 永远不要提交真实值）---
JWT_SECRET=change-me-in-production
API_KEY=your-api-key-here

# --- 外部服务 ---
REDIS_URL=redis://localhost:6379

规则：

• 敏感变量使用占位符值（如 change-me、your-xxx-here）
• 配置变量使用合理的默认值
• 按类别分组，并添加注释标题
• 在敏感变量上添加 🔴 敏感信息 警告

5. 验证当前的 .env 文件

如果存在 .env 文件，则与发现的变量进行对比：

## .env 验证报告

### ❌ 缺失（代码中引用但未在 .env 中定义）
- `STRIPE_SECRET_KEY` — 在 src/billing.ts:14 中引用
- `SMTP_PASSWORD` — 在 src/email.ts:8 中引用

### ⚠️ 未使用（存在于 .env 但代码中未引用）
- `OLD_API_ENDPOINT` — 可能可安全删除

### ✅ 存在且被引用
- `DATABASE_URL` ✓
- `PORT` ✓
- `NODE_ENV` ✓

6. 确保 .gitignore 安全

检查 .env 是否已加入 .gitignore：

grep -q "^\.env$\|^\.env\.\*" .gitignore 2>/dev/null

若未找到，建议添加以下内容：

# 环境文件
.env
.env.local
.env.*.local

同时检查 Git 历史中是否曾意外提交过 .env 文件：

git log --all --diff-filter=A -- .env .env.local .env.production 2>/dev/null

若发现，提醒用户敏感信息可能已存在于 Git 历史中，并建议使用 git filter-branch 或 BFG Repo-Cleaner 进行清理。

7. 输出汇总报告

# 环境变量报告
| 指标 | 数量 |
|------|------|
| 发现的总变量数 | 15 |
| 🔴 敏感信息 | 4 |
| ❌ .env 中缺失 | 2 |
| ⚠️ .env 中未使用 | 1 |
| ✅ 配置正确 | 12 |
| .gitignore 保护 | ✅ |

特殊情况处理

• 框架特定环境变量：Next.js 使用 NEXT_PUBLIC_*（客户端暴露），需单独标记
• Docker 环境变量：需检查 docker-compose.yml 中的 environment: 部分
• 多个 .env 文件：.env.development、.env.production、.env.test —— 需全部验证
• 无 .env 文件存在：同时生成 .env.example 和一个初始的 .env 文件
• 变量插值：Shell 脚本中的 ${VAR:-default} —— 提取 VAR 名称

错误处理

*由 Clawb (SOVEREIGN) 构建 — 更多技能敬请期待*