env-validator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

通过将

.env

文件与项目要求交叉比对来验证环境变量配置，在缺失变量、类型错误、不安全默认值和孤立配置项导致运行时故障之前提前发现问题。

Reference Files

参考文件

File	Contents	Load When
`references/validation-rules.md`	Built-in validation rules and severity definitions	Always

文件	内容	加载时机
`references/validation-rules.md`	内置验证规则和严重级别定义	始终加载

Prerequisites

前置要求

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

项目中存在
```
.env
```
文件（或同等作用的环境变量文件）
可选：
```
.env.example
```
、
```
docker-compose.yml
```
或部署清单，用于交叉比对

Workflow

工作流程

Phase 1: Discovery

阶段1：资源发现

Locate environment configuration sources in the project:

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

Report what was found before proceeding.

定位项目中的环境配置源：

主配置文件： 查找项目根目录下的
```
.env
```
，如果不存在，再检查
```
.env.local
```
、
```
.env.development
```
、
```
.env.production
```
Schema 文件： 查找
```
.env.example
```
或
```
.env.template
```
—— 这类文件定义了预期的变量
代码引用： 检索
```
os.environ
```
、
```
process.env
```
、
```
env::var
```
、
```
os.Getenv
```
模式，找到代码中引用的变量
部署清单： 检查
```
docker-compose.yml
```
、
```
Dockerfile
```
、
```
k8s/
```
清单中的
```
${VAR}
```
或
```
ENV VAR
```
模式

继续处理前先报告已发现的资源。

Phase 2: Schema Extraction

阶段2：Schema 提取

Build the expected variable schema from discovered sources:

For each variable found across all sources, record:

Field	Source
Name	Variable name (e.g., `DATABASE_URL` )
Required	Present in code references or marked required in example
Type hint	Inferred from usage (URL, integer, boolean, string, path)
Default	Value in `.env.example` if present
Used in	List of files that reference this variable

从已发现的数据源中构建预期的变量 Schema：

对所有来源中发现的每个变量，记录以下信息：

字段	来源
名称	变量名（例如 `DATABASE_URL` ）
是否必填	在代码中被引用，或在示例文件中标记为必填
类型提示	从使用方式推断（URL、整数、布尔值、字符串、路径）
默认值	若 `.env.example` 中存在则记录
使用位置	引用该变量的文件列表

Phase 3: Validation

阶段3：验证

Run these checks against the primary

.env

file:

Missing required variables (CRITICAL)
- Variable referenced in code but absent from
```
.env
```
- Variable in
```
.env.example
```
  without a default but absent from
```
.env
```
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
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
Unreferenced variables (MEDIUM)
- Variables in
```
.env
```
  not referenced anywhere in code or manifests
- May indicate stale configuration
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.

对主

.env

文件执行以下检查：

缺失必填变量（严重）
- 代码中引用了该变量，但
```
.env
```
  中不存在
- ```
.env.example
```
  中存在该变量且无默认值，但
```
.env
```
  中不存在
类型不匹配（高优先级）
- 代码中执行
```
int(os.environ["PORT"])
```
  但配置为
```
PORT=abc
```
- 代码期望布尔值（
```
true
```
  /
```
false
```
  ）但配置为
```
DEBUG=yes
```
- URL 变量不符合合法 URL 格式
不安全默认值（高优先级）
- ```
SECRET_KEY=changeme
```
  、
```
PASSWORD=password
```
  、
```
API_KEY=xxx
```
  这类配置
- 面向生产环境的文件中配置了
```
DEBUG=true
```
  或
```
DEBUG=1
```
- 安全关键变量为空值
未引用变量（中优先级）
- ```
.env
```
  中存在的变量未在代码或部署清单中任何位置引用
- 可能是过期配置
格式问题（低优先级）
- 不符合
```
KEY=VALUE
```
  格式的行
- 值末尾有尾随空格
- 引号使用不一致（混合使用单引号/双引号/无引号）
- 重复定义变量（最后定义的生效，但大概率是错误）

完整规则目录请查看

references/validation-rules.md

。

Phase 4: Report

阶段4：报告

Produce a structured validation report:

markdown

undefined

生成结构化的验证报告：

markdown

undefined

Environment Validation Report

File:

.env

Schema:

.env.example

+ code references Verdict: PASS | FAIL

File:

.env

Schema:

.env.example

+ code references Verdict: PASS | FAIL

Summary

Severity	Count
CRITICAL	N
HIGH	N
MEDIUM	N
LOW	N

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

.env

Referenced in:
```
src/db.py:12
```
,
```
docker-compose.yml:8
```
Expected type: URL (postgresql://...)

Fix: Add

DATABASE_URL=postgresql://user:pass@localhost:5432/dbname

.env

HIGH

...

Unreferenced Variables

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

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

Recommendations

[Highest priority fix]
[Second fix]

undefined

[Highest priority fix]
[Second fix]

undefined

Error Handling

错误处理

Error	Resolution
No .env file found	Report absence; check for alternative env sources
No .env.example or schema	Validate based on code references only
Binary or very large .env	Skip; report as unsupported format
No code references found	Validate format and security only; skip completeness

错误	解决方案
未找到 .env 文件	报告缺失情况，检查是否有其他替代的环境变量源
未找到 .env.example 或 Schema	仅基于代码引用进行验证
二进制格式或体积过大的 .env 文件	跳过处理，报告为不支持的格式
未找到代码引用	仅验证格式和安全性，跳过完整性检查

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

无法验证运行时注入的变量（来自 vault、AWS SSM 等）
类型推断是启发式的，可能会对复杂值分类错误
不会对照外部服务检查变量值（例如合法 API 密钥格式）
生产与开发环境的区分依赖文件命名规范