environment-config

Environment Config Skill — 配置管理

何时使用

• 启动 / 部署多环境项目（dev / staging / prod）
• 排查"为什么 prod 用了错的 DB"
• 防 secrets 进 git
• 设计配置注入到 Docker / K8s / Vercel / Lambda
• 区分 build-time vs runtime config

一、12-Factor #3：Config

"Config that varies between deploys is stored in environment variables."

关键：

• ✅ env vars 严格区分 code 与 deploy
• ✅ 不在 git 里
• ✅ 每个 deploy 自己一套
• ✅ 不同环境差异只在 env vars，code 完全相同

二、Config 层级（合并优先级）

[lowest → highest 优先级]

1. 代码默认值          (硬编码，最后兜底)
2. 配置文件默认         (config/default.yaml)
3. 环境特定文件         (config/production.yaml)
4. 本地覆盖文件         (config/local.yaml — gitignored)
5. 环境变量            (NODE_ENV / PORT / DATABASE_URL)
6. CLI flags          (--port=8080)

后面的覆盖前面的。运行时 config = merge(defaults, files, env, flags)。

三、Secret vs Config

维度	Config	Secret
例子	PORT, LOG_LEVEL, FEATURE_X_ENABLED	DB 密码, API key, JWT secret
谁能看	任何工程师	仅运维 / 管理员
存哪	env vars / ConfigMap / yaml	Vault / Secrets Manager / K8s Secret + KMS
轮换	罕见	定期轮换
日志	可打印	永远不打印

永远分开存。混在一起 → 给某人 read config 就给了 read secret。

四、.env 文件模式

# .env.example  ← 加入 git，列所有需要的 key
DATABASE_URL=postgres://user:pass@localhost/mydb
REDIS_URL=redis://localhost:6379
JWT_SECRET=replace-me-in-prod

# .env  ← gitignored，本机实际值
DATABASE_URL=postgres://localhost/mydb_dev
REDIS_URL=redis://localhost:6379
JWT_SECRET=dev-only-secret-12345

.gitignore 必须含：

.env
.env.local
.env.*.local
!.env.example

Node.js (Vite/Next 内置)：

.env                # 所有环境
.env.local          # 本机覆盖（gitignored）
.env.development    # dev 时
.env.production     # prod 时

注意：.env.production 通常不进 git（实际 prod 值由 CI 注入），只有 .env.example 入仓。

五、加载与校验（启动即崩）

// src/config.ts
import { z } from 'zod'
import 'dotenv/config'         // 仅 dev，prod 由部署平台注入

const Env = z.object({
  NODE_ENV:     z.enum(['development', 'staging', 'production', 'test']),
  PORT:         z.coerce.number().int().positive().default(8080),
  DATABASE_URL: z.string().url(),
  REDIS_URL:    z.string().url().optional(),
  JWT_SECRET:   z.string().min(32, 'JWT_SECRET must be 32+ chars'),
  LOG_LEVEL:    z.enum(['debug','info','warn','error']).default('info'),
})

const result = Env.safeParse(process.env)
if (!result.success) {
  console.error('Invalid env config:')
  for (const issue of result.error.issues) {
    console.error(`  ${issue.path.join('.')}: ${issue.message}`)
  }
  process.exit(1)
}
export const env = result.data