env-validator（环境验证器）

Env Validator

Validates environment variable configurations by cross-referencing .env files against project requirements. Catches missing variables, type errors, insecure defaults, and orphaned entries before they cause runtime failures.

Reference Files

Prerequisites

• A .env file (or equivalent) in the project
• Optionally: .env.example, docker-compose.yml, or deployment manifests for cross-referencing

Workflow

Phase 1: Discovery

Locate environment configuration sources in the project:

1. Primary file: Find .env in the project root. If absent, check for .env.local, .env.development, .env.production
2. Schema file: Find .env.example or .env.template — this defines the expected variables
3. Code references: Grep for os.environ, process.env, env::var, os.Getenv patterns to find variables referenced in code
4. Deployment manifests: Check docker-compose.yml, Dockerfile, k8s/ manifests for ${VAR} or ENV VAR patterns

Report what was found before proceeding.

Phase 2: Schema Extraction

Build the expected variable schema from discovered sources:

For each variable found across all sources, record:

Phase 3: Validation

Run these checks against the primary .env file:

1. Missing required variables (CRITICAL)

- Variable referenced in code but absent from .env - Variable in .env.example without a default but absent from .env

1. Type mismatches (HIGH)

- PORT=abc when code does int(os.environ["PORT"]) - DEBUG=yes when code expects boolean (true/false) - URL variables without valid URL format

1. Insecure defaults (HIGH)

- SECRET_KEY=changeme, PASSWORD=password, API_KEY=xxx - DEBUG=true or DEBUG=1 in production-targeted files - Empty values for security-critical variables

1. Unreferenced variables (MEDIUM)

- Variables in .env not referenced anywhere in code or manifests - May indicate stale configuration

1. Format issues (LOW)

- Lines without KEY=VALUE format - Trailing whitespace in values - Inconsistent quoting (mixing single/double/no quotes) - Duplicate variable definitions (last wins, but likely a mistake)

See references/validation-rules.md for the complete rule catalog.

Phase 4: Report

Produce a structured validation report:

# Environment Validation Report

**File:** `.env`
**Schema:** `.env.example` + code references
**Verdict:** PASS | FAIL

## Summary

| Severity | Count |
|----------|-------|
| CRITICAL | N     |
| HIGH     | N     |
| MEDIUM   | N     |
| LOW      | N     |

## CRITICAL

### [ENV-001] Missing required variable: DATABASE_URL

- **Referenced in:** `src/db.py:12`, `docker-compose.yml:8`
- **Expected type:** URL (postgresql://...)
- **Fix:** Add `DATABASE_URL=postgresql://user:pass@localhost:5432/dbname` to `.env`

## HIGH

...

## Unreferenced Variables

| Variable        | In .env | In Code | In Manifests | Status       |
|-----------------|---------|---------|--------------|--------------|
| LEGACY_API_KEY  | Yes     | No      | No           | Unreferenced |

## Recommendations

1. [Highest priority fix]
2. [Second fix]

Error Handling

Limitations

• Cannot validate runtime-injected variables (from vault, AWS SSM, etc.)
• Type inference is heuristic — may misclassify complex values
• Does not check variable values against external services (e.g., valid API key format)
• Production vs. development distinction requires file naming conventions