环境变量契约审计器
将以下提示词粘贴到你的 AI 对话框中:
请根据 https://skillhub.cn/install/skillhub.md,将技能 @user_2a94830e/user-2a94830e-environment-contract-auditor 安装到你的 AI 助手中。
技能介绍
环境变量正在变成项目里最容易漂移的接口
绝大多数项目里,环境变量承担着代码与部署环境之间的通信职责:CI 传 DATABASE_URL,容器注入 DEBUG,本地开发依赖 .env 文件。但它几乎总是以「隐性接口」的方式存在——没有人负责维护它,也没有人检查它是否与代码实际引用保持一致。结果就是上线前才暴露的问题:一个改版后引入的 JWT_SECRET 未写入部署配置,进程静默使用了默认值;.env.example 里某个必填项被某个人留空,本地跑通而线上崩溃。这类问题不到部署那一刻不会浮现,排查时又要跨仓库、跨配置层来回对照。
它如何工作:把 contract 当成版本化接口
这个技能的核心思路是把环境变量当作契约来审计,而不是简单地做一次字符串匹配。流程如下:
- 选定权威示例文件:以仓库中规范的示例文件(如
.env.example)作为--contract基准。 - 定义必填与可选:通过
# optional行内注释标记可选条目;其余空值一律按必填处理。 - 扫描源码引用:遍历源码目录,定位所有环境变量读取点。
- 对账与分级:把代码引用与契约比对,结果分为两类——
- error(拦截级):代码引用了未记录的变量、必填键在运行时缺失、出现重复定义、或契约中混入了疑似凭证字面量。
- review warning(审查级):存在未使用的键、或不安全的默认值。
最终输出只包含变量名、位置、分类与严重级别,并明确标注运行时覆盖是否已校验,绝不回显任何变量值。
适用边界与注意
- 审计结果不包含变量值本身,因此不适合用来定位「线上值到底是什么」这类问题——它回答的是契约是否一致,而不是「值对不对」。
- 支持的语法范围与限制需查阅技能内的
references/contract-conventions.md,非常规的配置格式(如动态拼接的键名)可能无法被覆盖。 - 发现问题后应把 contract 与部署配置一起修改,避免修好一半遗留新债。
使用场景
- 合并新功能分支后,准备发布前扫描代码,确认没有引入代码引用了但 `.env.example` 未记录的新变量。
- 安全巡检时审查 `.env.example`,排查是否存在疑似硬编码的密码或 API Key 裸露在示例文件中。
- 在本地与线上配置不一致导致报错时,通过审计源码引用判断具体缺失了哪些必填的运行时键。
- 重构遗留系统期间,检查原型环境中是否存在不再被引用的废弃键或带有不安全默认值的冗余配置。
适合人员
- 负责应用上线流程的后端工程师,需要在部署前拦截缺失的环境变量导致的进程启动失败。
- 维护开源项目的文档维护者,需要确保提供给用户的示例配置文件与仓库源码真实调用保持一致。
- 负责迁移系统到容器平台的架构师,需要规范微服务之间以及代码与部署环境之间的变量接口标准。