弧形

保守秘密 别让别人知道 .env 档案, 和AI特工无法获取.

阿尔卡移动你的秘密 .env 编号 : .env.local 进入项目外的加密商店 只有在程序运行时才会交给应用程序 你的应用程序还在读 process.env.DATABASE_URL,所以Next.js,Vite,Astro,TanStack Start,Nuxt,SvelteKit,和平地节点继续工作. 非敏感配置( N)PORT, (中文(简体) ), NEXT_PUBLIC_*,特征旗帜)可以留在 .env。 。 。 .

• 收回文件中没有秘密文件 . 值存在于您用户数据文件夹中的 AES-256-GCM 存储中。 密钥坐落在你的OS密钥链上,所以没有密码可以输入.
• 总是蒙住口. 您的应用打印通过 arca 来替换机密 [arca:DATABASE_URL],包括连接字符串内的编码表和密码。 在您的应用程序的节点进程内, 一个控制台守护器( 预装通过) NODE_OPTIONS(口罩) console.* 参数,所以将服务器日志转发到浏览器的dev工具(例如 TanStack Devtools)只看到 [arca:NAME]。 。 。 .
• 特工可以运行你的应用程序,而不是读取你的秘密. 人工智能特工只能通过你 package.json 剧本. 只有终端上的人才能揭示或改变值.

目标是 远比 .env 文件,不是无法突破。 任何运行在你的用户所能, 认真的努力, 达到你所能达到的。 arca关闭了容易,意外和"有帮助的代理"路径.

快开始

要求在 Windows 或 Linux 上更新节点 24 ()支持的平台) (中文(简体) ).

npm i -D @bremmdev/arca-env
npx arca init
npm run dev

arca init 创建 arca.json (只有可变名称, 已执行), 排序您的变量 .env 将文件输入到秘密和配置中, 导入这些秘密, 并包装您的脚本 :

{
  "scripts": {
    "dev": "arca run -- next dev",
    "build": "arca run -- next build"
  }
}

 .env 文件未受影响。 一旦你检查了所有工作, 取出简单的文本副本 :

npx arca import --delete     # removes only the imported entries; config lines stay

复制雷波运行的队友 npm run dev,然后运行 npx arca setup。步骤: 移动已存在的工程。 。 。 .

将已有工程移动到 arca

通常的起点:a .env.local (或 .env混合秘密(DATABASE_URL, (中文(简体) ), STRIPE_SECRET_KEY) 带有配置(PORT, (中文(简体) ), NEXT_PUBLIC_*),脚本喜欢 "dev": "next dev"。 。 。 .

1. 安装和运行 init 在项目文件夹中 :

   npm i -D @bremmdev/arca-env
   npx arca init
   

   它要求项目名称,那么哪些变量是机密. 看上去像秘密的人是预选的;例如 NEXT_PUBLIC_* 没有。 秘密进入了阿尔卡, 其他一切留在你的 .env 文件为配置,两者均在 arca.json (仅取名). 每个 .env.<name> 文件,例如 .env.staging,作为 配置文件。然后它会问哪些脚本可以包装 arca run。 。 。 . start 保持不包装生产, 你得到一个 start:local 用你的秘密来管理制作 最后,它提供了一个简短的"秘密(arca)"部分,用于 AGENTS.md。这些秘密值被复制到 arca 和您的 .env 文件没有更改。 第一个副本创建了主密钥: 在您的 OS 密钥链中, 或者 密码句后面 在WSL和无头的Linux上.

2. 检查它的工作: npm run dev 开始于 arca ▸ … output masked 线条和你的应用都像以前一样. npx arca list 显示每个变量现在来自何处,以及 npx arca doctor 检查整个设置。 直到下一步 漏水的警卫警告说 秘密还在你身上 .env 文档。 这是预期的.

3. 删除纯文本副本 :

   npx arca import --delete
   

   仅删除所导入的条目 。 配置行和注释保留,只有当其中没有其它内容时文件才会被删除 .

4. 提交 arca.json, (中文(简体) ), package.json 财务报告和审定财务报表 AGENTS.md。它们都没有价值。 留着吧 .env 和以前一样的文件.

5. 队友 拉,跑开 npm install 财务报告和审定财务报表 npm run dev。arca 命名缺失的变量,以及 npx arca setup 要求每个。 对于变量 "generate" 内 arca.json,它提供了一个随机值.

CI和部署不需要更改:没有储存, arca run 将平台的变量通过( v)CI和部署) (中文(简体) ).

为了回去, npx arca export --output .env.local 将每个值再次写入文件( 仅在终端上的人), 您删除 arca run -- 从您的脚本.

Next.js 16中,浏览器控制台警告和出错也出现在终端上(有上百个,如果您的本地设置很吵的话). 这是Next.js,不是Arca:它的 logging.browserToTerminal 选项默认为 'warn',它做同样没有 arca run。只保留错误,或关闭:

// next.config.ts or next.config.mjs
export default {
  logging: { browserToTerminal: 'error' }, // or false
}

一种情况下的若干环境 .env.local

一个普通的设置是 .env.local 每一个环境都有一个区块,除了一个之外,所有的评论,然后通过移动评论来切换. 注释出行仍然是一个代理能够读取的纯文本,所以它们也必须离开文件. 每个块变成一个 配置文件数字 :

1. 分出档案. 保留您通常运行的块( say dev) .env.local,没有评论。 将对方的块, 未经评论, 在自己的 .env.<profile> 文件 : .env.staging, (中文(简体) ), .env.prod。删除注释的块 .env.local。 。 。 .

   别用 .env.test, (中文(简体) ), .env.development 或者说 .env.production: Next.js 和 Vite 根据模式自行加载(.env.test 在维特或杰斯特下,所以 init 别管他们 选择另一个名字,例如 .env.qa。文件名称成为配置名称.

2. 运行 npx arca init。 。 。 . 对于每个文件,它问 "创建剖面 从.env.staging?" 一个共享大部分秘密的配置 .env.local extends 默认集,只存储不同的值,所以共享 STRIPE_SECRET_KEY 被存储一次。 配置行会留在每个文件中,只有这个配置可以加载它们.

3. 删除纯文本副本 带有命令 init 尾端的指纹 :

   npx arca import --delete
   npx arca import .env.staging --profile staging --delete
   npx arca import .env.prod --profile prod --delete
   

4. 切换 与 npx arca use staging 并带回 npx arca use --reset,或为一个终端 ARCA_PROFILE=prod npm run dev。 。 。 .

init 呼唤 .env.local 设定 default。从不键入默认配置文件的名称,这样可以。 给它起名 dev 相反,在导入前重命名它, 因为存储的值属于一个配置文件名称 :

1. npx arca init --no-import
2. 单位 arca.json,重命名 default 改为 dev 下级 profiles 在每笔捐款中 extends,并添加 "defaultProfile": "dev"。 。 。 .
3. 运行第3步的导入命令, 默认设置为先 .

队友也一样 .env.local,或者拉 承诺和运行 npx arca setup 默认集和 npx arca setup -p staging 用于对方的配置。 arca不同步机器之间的数值.

图标

arca是每个工程安装的,所以在一个终端中,您通过您的软件包管理器运行: npx arca <command> 与npm, , , , pnpm arca, (中文(简体) ), yarn arca (也在插管下) npx arca (没有用)或者 bun arca. arca自己的提示使用您需要的表格。 一个赤裸的 arca 给出“ 命令未找到” , 因为 node_modules/.bin 不是在你的路径。 内部 package.json 脚本,平面 arca run -- … 工作,因为软件包管理器为脚本添加了该文件夹. 光着身子 arca 在任何地方,也在全球安装: npm i -g @bremmdev/arca-env。 。 。 .

在运行前安装弧 npx arca没有本地安装, npx arca 获取 arca 从 npm,这是一个无关的软件包。 包裹名称, npx @bremmdev/arca-env <command>总是得到正确的一个.

arca.json

{
  "$schema": "./node_modules/@bremmdev/arca-env/schema.json",
  "id": "arc_7k2m9q4x8w1z3p5n",
  "name": "acme-web",
  "vars": {
    "DATABASE_URL": {
      "required": true,
      "description": "Local Postgres",
      "example": "postgres://postgres:postgres@localhost:5432/acme"
    },
    "STRIPE_SECRET_KEY": {
      "required": true,
      "docs": "https://dashboard.stripe.com/test/apikeys"
    },
    "AUTH_SECRET": { "required": true, "generate": { "bytes": 32 } },
    "NEXT_PUBLIC_POSTHOG_KEY": { "sensitive": false }
  }
}

• sensitive 默认为 true:值出自arca并被蒙上. false 所居住的配置标记 .env。 。 。 .
• 这个 id 把复制人和工作树 与同样的秘密联系起来.
• envFiles (选入)名单 .env 为不装入的工具编写的文件 node, (中文(简体) ), tsx) (中文(简体) ). 留空给装入自己的框架.
• leakGuard.ignore 关闭漏出 警卫的具体名称.

简介

剖面图是工程变量的一组值. 说你有 dev 财务报告和审定财务报表 staging:相同的变量,几个不同的值. 一切相相相相相相相等相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相 你随便换换.

{
  "defaultProfile": "dev",
  "profiles": {
    "dev": {},
    "staging": { "extends": "dev", "envFiles": [".env.staging"] }
  }
}

• extends 继承配置文件本身不保存的每个值,所以 staging 只存储不同的东西。 没有它,种子 完整的副本与 npx arca profiles copy dev staging。 。 。 .
• envFiles 列出该配置文件的 arca 装入的非敏感配置 。 使用名称框架不会加载自己( U).env.staging没有 .env.production) (中文(简体) ).
• 每个值命令都需要 --profile 编号 : -p数字 : npx arca set DATABASE_URL -p staging, (中文(简体) ), npx arca setup -p staging, (中文(简体) ), npx arca import .env.staging -p staging。 。 。 .

$ npx arca use staging
✔ acme-web now uses profile staging for every arca run on this machine
$ npm run dev
arca ▸ profile staging (via arca use) · 3 secrets · output masked
$ npx arca use --reset

arca use 适用于 arca run 的操作。 它被存放在repo外,因此队友没有受到影响. 哪个配置图胜出 : --profile (一个脚本可以标出一个: "test": "arca run --profile test -- vitest",则 ARCA_PROFILE 一个终端,那么 arca use,则 defaultProfile除默认外,任何配置文件的运行都始于 arca ▸ profile … 应用程序 ARCA_PROFILE=<name>。 。 。 .

配置文件只决定哪个值是 arca 注入 。 它没有设定 NODE_ENV 或更改 next dev 输入 next build。 。 。 .

输出被以下值所掩盖: 每个 剖面图,所以 staging a 期间显示的连接字符串 dev 运行静态打印为 [arca:DATABASE_URL@staging]。 。 。 . npx arca list 每个配置文件显示一列,以及 npx arca profiles diff dev staging 显示哪个配置文件将自动设定并继承哪些配置文件.

arca init 各提供 .env.<name> 文件作为配置文件。 一个在它宣布配置文件之前有值的项目会保留它们:它们会在第一次运行时移动到默认配置文件.

弧形中的秘密, 配置在 .env

当一个名字出现在一个以上的地方时,谁获胜: 阿尔卡,然后你的外壳,然后 .env 文件。当 arca 覆盖了与您外壳不同的值时, 它会这么说( 按名称, 从不按值) . --no-override 翻转它一跑.

这个 防渗出 检查你 .env* 每次运行的文件。 它警告当一个人包含一个存储在arca的值,一个被宣布为秘密的变量,或者一些看起来像秘密的东西(英语:sk_live_…,带有密码,长随机字符串的URL). arca doctor 显示细节和固定. arca check --strict 让它失败,为CI 或前承诺钩.

如何识别代理商

代理工具在其运行的命令中设置环境变量 : AI_AGENT (共同公约), CLAUDECODE, (中文(简体) ), CURSOR_AGENT, (中文(简体) ), CODEX_SANDBOX, (中文(简体) ), GEMINI_CLI, (中文(简体) ), OPENCODE 还有其他 你可以自己在店里加标记 config.json (单位:千美元)"agentMarkers": ["MY_AGENT"]),或设置 ARCA_AGENT=1 在特工的配置.

对于检测到的毒剂, arca run 检查是由一个 package.json 脚本,其文本与文件相匹配,且命令是脚本中的命令. 没有标记和终端(IDE任务,git hooks)的呼叫者可以运行任何东西,蒙面. 显示或改变值需要一个真正的终端,没有代理标记. 如果一个标记泄露到自己的终端,Arca会要求您输入一个短代码.

CI和部署

在CI,在Vercel和多克没有商店,所以 arca run 仅用平台的变量运行命令,然后检查需要的变量是否存在. start 剧本没有被包装,所以制作图像不需要arca.

支持的平台

CI测试了Windows x64,Linux x64和arm64,以及高山(musl),有npm,pnpm,纱线(1和4)和包. 节点24或更新.

保存着的东西

在 WSL 上运行 npm install 从WSL,不是Windows。 A 类 node_modules 从Windows安装的只有Arca的密钥环模块的Windows构建. 口号仍然有效,但Arca记不住了,所以每次跑都问起. 阿尔卡和 npx arca doctor 都告诉你当它发生.

如果键链条目丢失,金库无法被解密. 对于当地的开发秘密,通常都很好,因为可以从他们的仪表板上再取来.

限制

arca无法停止故意绕行:隐藏其标记,编辑的代理 package.json 以添加打印机密的脚本(在您 git diff 中显示),或者直接读取密钥链。 也阻止不了恶意软件的运行 也阻止不了自己的应用程序读取 process.env。其他输出您的应用程序发送到浏览器(显示一个值的错误覆盖或页面)或写入文件时没有被遮掩 .

状态

今天可以在Windows和Linux上使用:上面的一切,包括配置和密码句缓存. 每天对照 Next.js 和 TanStack Start Dev 服务器在浏览器中检查. 计划:充分互动工具的PTY模式,IDE测试跑取器的在流程中加载器,以及 arca scan。 。 。 .

许可证

麻省理工学院. 为任何目的自由使用、复制、修改和分发.