dmno-dev/varlock

Varlock

AI-safe（AI 安全）的 .env 文件：为 AI Agent 提供 Schema（模式），为人类提供 Secrets（密钥）。

• 🤖 AI-safe 配置 —— AI Agent 可以读取你的 Schema，但永远无法接触你的密钥。
• 🔍 主动泄露扫描 —— 通过 varlock scan 及 git hooks 实现。
• 🔏 运行时保护 —— 提供日志脱敏和防泄露功能。
• 🛡️ 验证与类型安全 —— 支持验证、强制转换、类型安全以及 IntelliSense。
• 🌐 灵活的多环境管理 —— 支持自动加载 .env.* 文件及显式导入。
• 🔌 插件系统 —— 支持从各种后端（1Password, Infisical, AWS, Azure, GCP, HCP Vault 等）拉取数据。

与 .env.example 不同，你的 .env.schema 是单一事实来源（Single Source of Truth），专为协作而生，确保配置永不同步失效。

# @defaultSensitive=false @defaultRequired=infer @currentEnv=$APP_ENV
# ---
# 环境变量标志，用于控制 `.env.xxx` 文件的自动加载
# @type=enum(development, preview, production, test)
APP_ENV=development # 默认值，可覆盖

# @type=port
API_PORT=8080 # 非敏感值可直接设置

# API url，包含引用其他环境变量的“扩展”功能
# @type=url
API_URL=http://localhost:${API_PORT}

# 敏感的 api key，带有额外验证
# @required @sensitive @type=string(startsWith=sk-)
OPENAI_API_KEY=

灵活的插件系统：添加新的装饰器、函数和类型，实现安全且声明式的密钥加载。

# @plugin(@varlock/1password-plugin)
# @initOp(token=$OP_TOKEN, allowAppAuth=forEnv(dev), account=acmeco)
# ---

# @type=opServiceAccountToken @sensitive
OP_TOKEN=

# 使用 1Password 密钥引用获取密钥
DB_PASS=op(op://my-vault/database-password/password)
API_KEY=op(op://api-vault/stripe/api-key)

安装

你可以通过安装 CLI 开始使用 Varlock：

# 运行安装向导，这将作为 JavaScript 项目的依赖进行安装
npx varlock init

# 或者作为独立二进制文件安装
brew install dmno-dev/tap/varlock # 通过 homebrew
curl -sSfL https://varlock.dev/install.sh | sh -s # 通过 cURL

# 或者使用官方 Docker 镜像
docker pull ghcr.io/dmno-dev/varlock:latest

更多信息请参阅完整的 安装文档 或 Docker 指南。

工作流

使用以下命令验证你的 .env.schema 并美观地打印环境变量：

varlock load

如果你需要将解析后的环境变量传递给另一个进程，可以运行：

varlock run -- python script.py

在许多情况下，你可以使用我们的 集成插件 来获得无缝体验，并配合额外的安全防护措施，如日志脱敏和防泄露保护。

AI-Safe 配置

你的 .env.schema 为 AI Agent 提供了关于你配置的完整上下文 —— 变量名、类型、验证规则和描述 —— 而无需暴露任何密钥值。配合用于捕获 AI 生成代码中泄露密钥的 varlock scan，Varlock 专为 AI 时代而打造。在 AI-safe 配置指南 中了解更多。

@env-spec

Varlock 构建于 @env-spec 之上，这是一种使用 JSDoc 风格注释为 .env 文件附加 Schema 和额外功能的新型 DSL。@env-spec 包包含一个解析器以及关于该规范本身的信息。

• @env-spec 文档
• @env-spec RFC

已发布包

核心库

包名	发布列表页面
varlock
@env-spec/parser
@env-spec VSCode 插件	VSCode Marketplace, Open VSX Registry
varlock Docker 镜像	GitHub Container Registry

插件

包名	发布列表页面
@varlock/1password-plugin
@varlock/aws-secrets-plugin
@varlock/azure-key-vault-plugin
@varlock/bitwarden-plugin