mcpField
E
env-validator

env-validator

github.com/mathews-tom开发33785 次安装2 天前更新
代码仓库

关于 env-validator

env-validator 是用于检查项目环境变量配置的技能，适合开发和维护项目配置的人员。它将 .env 文件与代码、示例文件和部署清单交叉核对，报告缺失项、类型错误、不安全默认值及未引用变量。

主要功能

  1. 01发现环境配置来源
  2. 02从代码和清单提取变量要求
  3. 03检查缺失变量与类型错误
  4. 04标记不安全默认值和孤立变量
  5. 05生成结构化验证报告

适用场景

  1. 01在运行前检查项目的 .env 配置
  2. 02核对 .env.example 与代码所需变量
  3. 03清理部署配置中的过期或未引用变量

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/mathews-tom/armory --skill env-validator

安装后在 Claude Code 中输入/env-validator确认已加载。

附带文件evals/cases.yamlreferences/validation-rules.md

详细介绍

Env Validator

通过交叉比对 .env 文件与项目要求，验证环境变量配置。在导致运行时故障之前，捕获缺失变量、类型错误、不安全的默认值和孤立条目。

参考文件

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

前提条件

  • 项目中有 .env 文件（或等效文件）
  • 可选：用于交叉比对的 .env.example、docker-compose.yml 或部署清单

工作流

阶段 1：发现

在项目中定位环境配置来源：

  1. 主文件： 在项目根目录查找 .env。如果不存在，则检查 .env.local、.env.development、.env.production
  2. 架构文件： 查找 .env.example 或 .env.template，这些文件定义了预期变量
  3. 代码引用： 搜索 os.environ、process.env、env::var、os.Getenv 模式，查找代码中引用的变量
  4. 部署清单： 检查 docker-compose.yml、Dockerfile、k8s/ 清单中的 ${VAR} 或 ENV VAR 模式

继续之前，报告找到的内容。

阶段 2：提取架构

根据发现的来源构建预期变量架构：

对于所有来源中找到的每个变量，记录：

字段来源
名称变量名称（例如，DATABASE_URL）
必需在代码引用中出现，或在示例中标记为必需
类型提示根据用法推断（URL、整数、布尔值、字符串、路径）
默认值.env.example 中的值（如果存在）
使用位置引用此变量的文件列表
阶段 3：验证

针对主 .env 文件运行以下检查：

  1. 缺少必需变量（CRITICAL）

    • 代码中引用了该变量，但 .env 中不存在
    • .env.example 中存在该变量且未设置默认值，但 .env 中不存在

  2. 类型不匹配（HIGH）

    • 代码执行 int(os.environ["PORT"])，但值为 PORT=abc
    • 代码期望布尔值（true/false），但值为 DEBUG=yes
    • URL 变量格式无效

  3. 不安全的默认值（HIGH）

    • SECRET_KEY=changeme、PASSWORD=password、API_KEY=xxx
    • 面向生产环境的文件中出现 DEBUG=true 或 DEBUG=1
    • 安全关键变量的值为空

  4. 未引用的变量（MEDIUM）

    • .env 中的变量未在代码或清单中的任何位置引用
    • 可能表示配置已过期

  5. 格式问题（LOW）

    • 行不符合 KEY=VALUE 格式
    • 值末尾有空格
    • 引号使用不一致（混用单引号、双引号或不加引号）
    • 变量定义重复（后者生效，但很可能是错误）

完整规则目录请参阅 references/validation-rules.md。

阶段 4：报告

生成结构化验证报告：

# 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]

错误处理

错误解决方法
未找到 .env 文件报告文件缺失；检查是否有其他环境变量来源
没有 .env.example 或架构文件仅根据代码引用进行验证
.env 为二进制文件或文件过大跳过；报告格式不受支持
未找到代码引用仅验证格式和安全性；跳过完整性检查

限制

  • 无法验证运行时注入的变量（来自 vault、AWS SSM 等）
  • 类型推断基于启发式规则，可能会误判复杂值
  • 不会通过外部服务检查变量值（例如 API 密钥格式是否有效）
  • 区分生产环境与开发环境需要遵循文件命名约定

评论

支持 Markdown