d
dmno-dev/varlock
AI-safe .env files: Schemas for agents, Secrets for humans.
configurationdotenvenvenv-varsschemasecurityvalidation
TypeScriptMIT创建于 2025/4/11更新于 今天
README
由 Gemini 翻译整理
Varlock
AI-safe（AI 安全）的 .env 文件：为 AI 代理提供 Schema（模式），为人类提供 Secrets（机密信息）。
- 🤖 AI-safe 配置 —— 代理程序可以读取你的 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
# ---
# our environment flag, will control automatic loading of `.env.xxx` files
# @type=enum(development, preview, production, test)
APP_ENV=development # default value, can override
# @type=port
API_PORT=8080 # non-sensitive values can be set directly
# API url including _expansion_ referencing another env var
# @type=url
API_URL=http://localhost:${API_PORT}
# sensitive api key, with extra validation
# @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=
# Fetch secrets using 1Password secret references
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
工作流程
使用以下命令验证你的 .env.schema 并美化输出环境变量：
varlock load
如果你需要将解析后的环境变量传递给另一个进程，可以运行：
varlock run -- python script.py
在许多情况下，你可以使用我们的 即插即用集成方案 来获得无缝体验，并享受额外的安全防护，如日志脱敏和泄露预防。
AI-Safe 配置
你的 .env.schema 为 AI 代理提供了关于配置的完整上下文信息——包括变量名称、类型、验证规则和描述——而不会暴露任何敏感的机密值。结合 varlock scan 来捕获 AI 生成代码中泄露的机密，Varlock 是专为 AI 时代打造的工具。了解更多信息，请查看 AI-safe 配置指南。
@env-spec
Varlock 构建于 @env-spec 之上，这是一个全新的 DSL（领域特定语言），用于通过 JSDoc 风格的注释为 .env 文件添加 Schema 和附加功能。@env-spec 包包含了一个解析器以及该规范本身的相关信息。
已发布的包
核心包
| 包名 | 发布页面 |
|---|---|
| varlock |  |
| @env-spec/parser |  |
| @env-spec VSCode 扩展 | VSCode 市场, Open VSX 注册表 |
| varlock Docker 镜像 | GitHub 容器注册表 |
插件
| 包名 | 发布页面 |
|---|---|
| @varlock/1password-plugin |  |
| @varlock/aws-secrets-plugin |  |
| @varlock/azure-key-vault-plugin |  |
| @varlock/bitwarden-plugin |  |