用途:这是一个较窄的应用配置与 .env 兼容技能,目标是在各环境中让应用配置清晰且安全:判断什么应放入环境变量、组织 .env 文件与优先级规则、校验必填配置、分离公开与私有值、减少本地、CI、预发与生产之间的配置漂移,并让密钥交付显式化。
适用场景:设计 .env.example、.env.local 或按环境的配置结构;解释环境变量优先级以及哪些值可提交、哪些不可;用类型化或运行时检查校验必填变量;分离服务端专用与客户端暴露的变量;减少各环境配置漂移;清理环境文件、密钥文档与运行时预期不一致的仓库;判断何时环境变量足够、何时需密钥管理器注入。
使用方式:先对配置问题分类(primary_goal、app_shape、current_storage、drift_surface、confidence),再选择单一模式:env-file-structure(文件布局、命名与优先级)、env-validation(缺失或错误值导致运行时/构建问题)、secret-handoff-boundary(.env 与密钥管理器冲突)、framework-config-rules(框架特有前缀、构建期与运行期暴露)、drift-cleanup(模板、文档、CI 变量与运行时预期不一致)。随后应用配置规则并输出“Environment Config Brief”结构。
主要规则:部署相关值不进源码,只提交安全模板;提交模板与开发者本地值分离;公开/客户端变量与仅服务端值在视觉上区分;应用足够大、漂移代价高时采用类型化校验;记录密钥来源(本地文件、密钥管理器、CI 变量或云平台)。
限制与边界:不适用于让整个仓库跨机器可运行、本地服务编排、Docker 或 devcontainer 等任务,这些应转向 system-environment-setup;部署自动化或生产发布应配合 deployment-automation;更广泛的安全审查应配合 security-best-practices。不要将其写成 Docker/devcontainer 教程,不要掩盖公开/私有环境变量暴露风险,不要假设 .env 足以覆盖所有密钥流程。参考资料包括 references/env-patterns.md、references/scope-boundaries.md、Twelve-Factor config、Next.js 环境变量指南和 T3 Env 介绍;具体代码示例与安装命令资料暂未提供。