Varlock：Schema 驱动的类型安全环境变量管理
Varlock 用 .env.schema 替代 .env：配置结构入库、密钥运行时从密钥管理器解析。本文讲解安装、装饰器语法与密钥管理器集成。
Varlock 把 .env 拆成两半：可入库的 .env.schema（声明变量、类型、校验规则、默认值）+ 运行时才解析的真实值（来自环境或 1Password/AWS Secrets Manager 等）。密钥永不落盘，配置契约入库共享。
.env 的老问题
- 新同事克隆仓库后要四处索要 .env 文件；
- .env.example 是手工维护的影子文档，必然腐化失同步；
- 密钥明文躺在每个开发者的磁盘上；
- 缺变量/拼错变量运行时才炸。
.env.schema 方案
npm install varlock
npx varlock init
# .env.schema —— 可以安全入库
DATABASE_URL= # @type=url @required
PORT=3000 # @type=integer
API_KEY= # @required @sensitive
装饰器声明类型与约束——配置的单一事实源入库了。
运行时注入
varlock run -- node app.js
值解析顺序：真实环境变量 → 密钥管理器引用 → Schema 默认值。缺必需变量启动即失败（附清晰错误），不再随机崩溃。
密钥管理器集成
Schema 中的值可以引用外部密钥：API_KEY=$1password:op://vault/item/key 类语法——varlock 运行时从 1Password/AWS Secrets Manager/Azure Key Vault 拉取。磁盘上永远没有明文密钥。
实践考量
- CI 环境：密钥走 CI 的 Secret 注入，varlock 读取环境变量即可；
- 团队推广：.env.schema 替代 README 的"环境配置"章节；
- 类型安全：varlock 生成 TS 类型，process.env 拼错编译报错。
常见问题（FAQ）
Q：和 dotenv + Joi 校验的组合比？
那是"校验已有配置"；Varlock 是"Schema 定义配置 + 密钥外置"——解决的是密钥落盘与文档失同步两个更深的问题。
Q：老项目迁移成本？
.env 内容逐个迁入 Schema 声明；值存量的用密钥管理器引用替换。半天级工作量。
Q：和 Mise 的 env 功能冲突吗？
互补：Mise 管开发环境变量注入，Varlock 管应用配置的 Schema 与密钥解析——可组合使用。
参考文档
本文依据公开文档整理，示例需按项目依赖版本验证；不将文档中的性能描述视为本项目实测结果。
