⚡

环境变量管理技能Skill env-manager

环境变量管理技能用于管理和验证环境变量，包括分析环境变量、生成文档、验证配置和提供最佳实践，关键词包括环境变量、配置管理、DevOps、软件开发、安全。

DevOps 0 次安装 0 次浏览 更新于 3/11/2026

name: env-manager description: 环境变量管理、验证和文档化。

环境管理器技能

环境变量管理、验证和文档化。

指令

您是一名环境配置专家。当被调用时：

  1. 分析环境变量：

    • 识别代码中使用的所有环境变量
    • 检查未定义或缺失的变量
    • 验证变量格式（URL、数字、布尔值）
    • 检测应作为环境变量的硬编码值

  2. 生成文档：

    • 创建 .env.example 模板
    • 文档化必需与可选变量
    • 提供描述和示例
    • 列出默认值

  3. 验证配置：

    • 检查必需变量是否设置
    • 验证格式和类型
    • 确保源代码控制中无秘密
    • 验证跨环境一致性

  4. 提供最佳实践：

    • 命名约定
    • 安全建议
    • 环境特定配置
    • 秘密管理策略

环境变量约定

命名标准

# 使用 UPPER_SNAKE_CASE
DATABASE_URL=postgresql://localhost:5432/mydb
API_KEY=abc123xyz

# 按服务/类别前缀化
DB_HOST=localhost
DB_PORT=5432
DB_NAME=mydb
DB_USER=admin

REDIS_HOST=localhost
REDIS_PORT=6379

AWS_REGION=us-east-1
AWS_ACCESS_KEY_ID=AKIA...
AWS_SECRET_ACCESS_KEY=...

# 布尔值
ENABLE_LOGGING=true
DEBUG_MODE=false

环境前缀

# 开发环境
NODE_ENV=development
DEBUG=true
LOG_LEVEL=debug

# 预发布环境
NODE_ENV=staging
DEBUG=false
LOG_LEVEL=info

# 生产环境
NODE_ENV=production
DEBUG=false
LOG_LEVEL=error

.env.example 模板

# ======================
# 应用程序设置
# ======================

# 环境（development、staging、production）
NODE_ENV=development

# 应用程序端口
PORT=3000

# 应用程序URL
APP_URL=http://localhost:3000

# ======================
# 数据库配置
# ======================

# PostgreSQL 连接字符串
# 格式：postgresql://用户名:密码@主机:端口/数据库
DATABASE_URL=postgresql://user:password@localhost:5432/myapp

# 数据库连接池
DB_POOL_MIN=2
DB_POOL_MAX=10

# ======================
# Redis 配置
# ======================

# Redis 连接 URL
REDIS_URL=redis://localhost:6379

# Redis 密码（可选）
# REDIS_PASSWORD=

# ======================
# 身份验证
# ======================

# JWT 密钥（必需 - 使用命令生成：openssl rand -base64 32）
JWT_SECRET=your-secret-key-here

# JWT 过期时间（默认：24h）
JWT_EXPIRES_IN=24h

# 会话密钥
SESSION_SECRET=your-session-secret

# ======================
# 外部服务
# ======================

# AWS 配置
AWS_REGION=us-east-1
AWS_ACCESS_KEY_ID=your-access-key
AWS_SECRET_ACCESS_KEY=your-secret-key
AWS_S3_BUCKET=my-app-uploads

# 电子邮件服务（SendGrid）
SENDGRID_API_KEY=SG.xxxxx
EMAIL_FROM=noreply@example.com

# Stripe
STRIPE_PUBLIC_KEY=pk_test_xxxxx
STRIPE_SECRET_KEY=sk_test_xxxxx

# ======================
# 功能标志
# ======================

# 启用新仪表板
ENABLE_NEW_DASHBOARD=false

# 启用电子邮件通知
ENABLE_EMAIL_NOTIFICATIONS=true

# ======================
# 日志和监控
# ======================

# 日志级别（error、warn、info、debug）
LOG_LEVEL=info

# Sentry DSN 用于错误跟踪
# SENTRY_DSN=https://xxxxx@sentry.io/xxxxx

# ======================
# 安全
# ======================

# CORS 允许来源（逗号分隔）
CORS_ORIGINS=http://localhost:3000,http://localhost:3001

# 速率限制
RATE_LIMIT_MAX_REQUESTS=100
RATE_LIMIT_WINDOW_MS=900000

# ======================
# 仅开发环境
# ======================

# 启用调试模式
DEBUG=false

# 禁用 SSL 验证（生产环境绝不允许！）
# NODE_TLS_REJECT_UNAUTHORIZED=0

环境验证

Node.js 示例

// env.js - 环境验证
const envalid = require('envalid');

const env = envalid.cleanEnv(process.env, {
  // 应用程序
  NODE_ENV: envalid.str({ choices: ['development', 'staging', 'production'] }),
  PORT: envalid.port({ default: 3000 }),
  APP_URL: envalid.url(),

  // 数据库
  DATABASE_URL: envalid.url({ desc: 'PostgreSQL 连接 URL' }),
  DB_POOL_MIN: envalid.num({ default: 2 }),
  DB_POOL_MAX: envalid.num({ default: 10 }),

  // Redis
  REDIS_URL: envalid.url(),
  REDIS_PASSWORD: envalid.str({ default: '' }),

  // 秘密
  JWT_SECRET: envalid.str({ desc: 'JWT 签名密钥' }),
  JWT_EXPIRES_IN: envalid.str({ default: '24h' }),

  // AWS
  AWS_REGION: envalid.str({ default: 'us-east-1' }),
  AWS_ACCESS_KEY_ID: envalid.str(),
  AWS_SECRET_ACCESS_KEY: envalid.str(),

  // 功能标志
  ENABLE_NEW_DASHBOARD: envalid.bool({ default: false }),
  ENABLE_EMAIL_NOTIFICATIONS: envalid.bool({ default: true }),

  // 日志
  LOG_LEVEL: envalid.str({
    choices: ['error', 'warn', 'info', 'debug'],
    default: 'info'
  }),

  // 安全
  CORS_ORIGINS: envalid.str({ desc: '逗号分隔的允许来源' }),
  RATE_LIMIT_MAX_REQUESTS: envalid.num({ default: 100 }),
});

module.exports = env;

Python 示例

# config.py - 环境验证
import os
from typing import Optional
from pydantic import BaseSettings, validator, AnyHttpUrl

class Settings(BaseSettings):
    # 应用程序
    ENV: str = "development"
    PORT: int = 8000
    APP_URL: AnyHttpUrl

    # 数据库
    DATABASE_URL: str
    DB_POOL_MIN: int = 2
    DB_POOL_MAX: int = 10

    # Redis
    REDIS_URL: str
    REDIS_PASSWORD: Optional[str] = None

    # 秘密
    JWT_SECRET: str
    JWT_EXPIRES_IN: str = "24h"

    # AWS
    AWS_REGION: str = "us-east-1"
    AWS_ACCESS_KEY_ID: str
    AWS_SECRET_ACCESS_KEY: str

    # 功能标志
    ENABLE_NEW_DASHBOARD: bool = False
    ENABLE_EMAIL_NOTIFICATIONS: bool = True

    # 日志
    LOG_LEVEL: str = "info"

    @validator("ENV")
    def validate_env(cls, v):
        allowed = ["development", "staging", "production"]
        if v not in allowed:
            raise ValueError(f"ENV 必须是其中之一 {allowed}")
        return v

    @validator("LOG_LEVEL")
    def validate_log_level(cls, v):
        allowed = ["error", "warn", "info", "debug"]
        if v not in allowed:
            raise ValueError(f"LOG_LEVEL 必须是其中之一 {allowed}")
        return v

    class Config:
        env_file = ".env"
        case_sensitive = True

settings = Settings()

使用示例

@env-manager
@env-manager --validate
@env-manager --generate-example
@env-manager --check-secrets
@env-manager --document

安全最佳实践

绝不提交秘密

# .gitignore
.env
.env.local
.env.*.local
*.pem
*.key
secrets/

秘密检测

# 检查意外提交的秘密
git secrets --scan

# 使用工具如：
# - gitleaks
# - truffleHog
# - git-secrets

秘密管理解决方案

# 开发环境
# - .env 文件（git忽略）
# - direnv

# 生产环境
# - AWS Secrets Manager
# - HashiCorp Vault
# - Azure Key Vault
# - Google Secret Manager
# - Kubernetes Secrets
# - Docker Secrets

静态加密

# 加密敏感 .env 文件
# 使用 SOPS（Secrets OPerationS）
sops -e .env > .env.encrypted

# 使用 git-crypt
git-crypt init
echo '.env' >> .gitattributes
git-crypt add-gpg-user user@example.com

环境特定配置

多个 .env 文件

.env                  # 默认（提交 .env.example）
.env.local           # 本地覆盖（git忽略）
.env.development     # 开发环境
.env.staging         # 预发布环境
.env.production      # 生产环境（绝不提交！）

加载优先级（Node.js）

// 使用 dotenv 级联加载
require('dotenv').config({ path: '.env.local' });
require('dotenv').config({ path: `.env.${process.env.NODE_ENV}` });
require('dotenv').config({ path: '.env' });

常见问题与解决方案

缺失环境变量

// ❌ 差 - 静默失败
const apiKey = process.env.API_KEY;

// ✓ 好 - 显式验证
const apiKey = process.env.API_KEY;
if (!apiKey) {
  throw new Error('API_KEY 环境变量必需');
}

// ✓ 更好 - 使用验证库
const env = require('./env'); // 加载时验证
const apiKey = env.API_KEY;

类型强制转换

// ❌ 差 - 字符串比较
if (process.env.DEBUG === true) { } // 总是 false！

// ✓ 好 - 正确解析布尔值
const DEBUG = process.env.DEBUG === 'true';

// ✓ 更好 - 使用验证
const { bool } = require('envalid');
const DEBUG = bool({ default: false });

默认值

// ✓ 提供合理默认值
const PORT = process.env.PORT || 3000;
const LOG_LEVEL = process.env.LOG_LEVEL || 'info';
const ENABLE_CACHE = process.env.ENABLE_CACHE !== 'false'; // 默认 true

文档模板

# 环境变量

## 必需变量

### DATABASE_URL
- **类型**：URL
- **描述**：PostgreSQL 连接字符串
- **格式**：`postgresql://用户名:密码@主机:端口/数据库`
- **示例**：`postgresql://user:pass@localhost:5432/mydb`

### JWT_SECRET
- **类型**：字符串
- **描述**：JWT 令牌签名的密钥
- **安全**：绝不提交此值
- **生成**：`openssl rand -base64 32`

### AWS_ACCESS_KEY_ID
- **类型**：字符串
- **描述**：用于 S3 和其他服务的 AWS 访问密钥
- **安全**：生产环境中存储在秘密管理器

## 可选变量

### PORT
- **类型**：数字
- **描述**：应用程序服务器端口
- **默认**：`3000`
- **示例**：`3000`

### LOG_LEVEL
- **类型**：字符串
- **描述**：日志详细程度
- **选择**：`error`, `warn`, `info`, `debug`
- **默认**：`info`

### ENABLE_CACHE
- **类型**：布尔值
- **描述**：启用 Redis 缓存
- **默认**：`true`
- **值**：`true`, `false`

## 功能标志

### ENABLE_NEW_DASHBOARD
- **类型**：布尔值
- **描述**：启用新仪表板 UI
- **默认**：`false`
- **状态**：实验性

## 环境设置

### 开发环境
```bash
cp .env.example .env.local
# 使用本地值编辑 .env.local

生产环境

使用秘密管理器设置：

  • DATABASE_URL
  • JWT_SECRET
  • AWS 凭证
  • API 密钥

## 备注

- 使用 `.env.example` 作为模板（提交到 git）
- 绝不提交包含秘密的实际 `.env` 文件
- 在应用程序启动时验证环境变量
- 生产环境使用秘密管理
- 文档化所有变量，包括描述和示例
- 使用一致的命名约定（UPPER_SNAKE_CASE）
- 前缀相关变量（DB_, AWS_, REDIS_）
- 尽可能提供合理默认值
- 使用类型验证库
- 考虑环境特定配置文件