# @bremmdev/arca-env 中文文档 规范地址：https://npmcn.com/package/%40bremmdev/arca-env/ 版本：0\.4\.2 npm 元数据更新时间：2026-11-05T20:05:58.261Z 中文译文更新时间：2026-11-09T21:47:31.988Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40bremmdev/arca-env 原文对照：https://npmcn.com/package/%40bremmdev/arca-env/?lang=original 项目主页：https://github.com/bremmdev/arca-env#readme 源码仓库：https://github.com/bremmdev/arca-env ## 关键信息（来自 npm 元数据） - 包体积（解压后）：184 kB，10 个文件 - 模块格式：ES Module - TypeScript 类型：未声明 - Node.js 要求：\>=24 - 运行依赖：3 个 - 首次发布：2026-10-22T13:07:54.494Z - 最新版本发布：2026-11-05T20:05:57.900Z - 近 30 天下载量：1714（2026-10-09 至 2026-11-07，npm 官方下载统计） - 已发布版本数：10（近 12 个月 10 个） ## 中文简介 把秘密从.env的档案中保密,并且不让AI特工知道. 加密了本地商店,在运行时注入,输出总是被遮掩. ## 安装 ```sh npm install @bremmdev/arca-env ``` 也可以使用：`pnpm add @bremmdev/arca-env`、`yarn add @bremmdev/arca-env`、`bun add @bremmdev/arca-env` ## README # 弧形 **保守秘密 别让别人知道 `.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 ()[支持的平台](https://npmcn.com/package/%40bremmdev/arca-env/#readme-supported-platforms)) (中文(简体) ). ```console npm i -D @bremmdev/arca-env npx arca init npm run dev ``` `arca init` 创建 `arca.json` (只有可变名称, 已执行), 排序您的变量 `.env` 将文件输入到秘密和配置中, 导入这些秘密, 并包装您的脚本 : ```json { "scripts": { "dev": "arca run -- next dev", "build": "arca run -- next build" } } ```  `.env` 文件未受影响。 一旦你检查了所有工作, 取出简单的文本副本 : ```console npx arca import --delete # removes only the imported entries; config lines stay ``` 复制雷波运行的队友 `npm run dev`,然后运行 `npx arca setup`。步骤: [移动已存在的工程](https://npmcn.com/package/%40bremmdev/arca-env/#readme-moving-an-existing-project-to-arca)。 。 。 . ## 将已有工程移动到 arca 通常的起点:a `.env.local` (或 `.env`混合秘密(`DATABASE_URL`, (中文(简体) ), `STRIPE_SECRET_KEY`) 带有配置(`PORT`, (中文(简体) ), `NEXT_PUBLIC_*`),脚本喜欢 `"dev": "next dev"`。 。 。 . 1. **安装和运行 `init`** 在项目文件夹中 : ```console npm i -D @bremmdev/arca-env npx arca init ``` 它要求项目名称,那么哪些变量是机密. 看上去像秘密的人是预选的;例如 `NEXT_PUBLIC_*` 没有。 秘密进入了阿尔卡, 其他一切留在你的 `.env` 文件为配置,两者均在 `arca.json` (仅取名). 每个 `.env.` 文件,例如 `.env.staging`,作为 [配置文件](https://npmcn.com/package/%40bremmdev/arca-env/#readme-profiles)。然后它会问哪些脚本可以包装 `arca run`。 。 。 . `start` 保持不包装生产, 你得到一个 `start:local` 用你的秘密来管理制作 最后,它提供了一个简短的"秘密(arca)"部分,用于 `AGENTS.md`。这些秘密值被复制到 arca 和您的 `.env` 文件没有更改。 第一个副本创建了主密钥: 在您的 OS 密钥链中, 或者 [密码句后面](https://npmcn.com/package/%40bremmdev/arca-env/#readme-where-things-are-kept) 在WSL和无头的Linux上. 2. **检查它的工作:** `npm run dev` 开始于 `arca ▸ … output masked` 线条和你的应用都像以前一样. `npx arca list` 显示每个变量现在来自何处,以及 `npx arca doctor` 检查整个设置。 直到下一步 漏水的警卫警告说 秘密还在你身上 `.env` 文档。 这是预期的. 3. **删除纯文本副本 :** ```console 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和部署](https://npmcn.com/package/%40bremmdev/arca-env/#readme-ci-and-deploys)) (中文(简体) ). 为了回去, `npx arca export --output .env.local` 将每个值再次写入文件( 仅在终端上的人), 您删除 `arca run --` 从您的脚本. Next.js 16中,浏览器控制台警告和出错也出现在终端上(有上百个,如果您的本地设置很吵的话). 这是Next.js,不是Arca:它的 `logging.browserToTerminal` 选项默认为 `'warn'`,它做同样没有 `arca run`。只保留错误,或关闭: ```js // next.config.ts or next.config.mjs export default { logging: { browserToTerminal: 'error' }, // or false } ``` ### 一种情况下的若干环境 `.env.local` 一个普通的设置是 `.env.local` 每一个环境都有一个区块,除了一个之外,所有的评论,然后通过移动评论来切换. 注释出行仍然是一个代理能够读取的纯文本,所以它们也必须离开文件. 每个块变成一个 [配置文件](https://npmcn.com/package/%40bremmdev/arca-env/#readme-profiles)数字 : 1. **分出档案.** 保留您通常运行的块( say dev) `.env.local`,没有评论。 将对方的块, 未经评论, 在自己的 `.env.` 文件 : `.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` 尾端的指纹 : ```console 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 ` 与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 `总是得到正确的一个. | 命令 | 它会做什么 | AI探员 | | --- | --- | --- | | `arca run [--only A,B] -- ` | 用输入的秘密运行, 输出蒙蔽 | 只有通过 `package.json` 脚本 | | `arca list` | 每个可变的,以及它从哪里来(arca, `.env`,缺少)。 仅取名. | ✅ | | `arca check [--strict]` | 缺少所需变量时退出 1 . `--strict` 也失败于其中的秘密 `.env` 文档. | ✅ | | `arca doctor` | 关键链、项目、脚本和防漏诊断 | ✅ | | `arca set NAME [--generate]` | 存储一个值: 隐藏快取, `… | arca set NAME`,或随机值 | 只有一个人 | | `arca setup [--all]` | 为每个缺失的必要变量提示 | 只有一个人 | | `arca unset NAME` 编号 : `arca restore NAME` | 删除一个值/ 撤销上次更改 | 只有一个人 | | `arca reveal NAME` 编号 : `arca export` | 显示一个值/ 全部打印( O)`--format dotenv|json|shell`, (中文(简体) ), `--output file`(中文(简体) ) | 只有一个人 | | `arca import [files] [--only A,B] [--delete]` | 移动机密从 `.env` 文件进入弧形 | 只有一个人 | | `arca init [--yes] [--new-id] [--no-import]` | 建立一个项目( :`--no-import`: 写入 `arca.json` 和脚本,尚未存储值) | qq 不导入 | | `arca use [profile]` 编号 : `arca use --reset` | 显示或切换活动配置文件 | qq( 只当您询问时) | | `arca profiles` 编号 : `profiles add [--extends p]` 编号 : `profiles diff ` | 列出、添加和比较简介。 仅取名. | ✅ | | `arca profiles copy [--only A,B]` 编号 : `profiles rm ` | 在配置文件/ 删除配置文件及其值之间复制值 | 只有一个人 | | `arca policy set agent-run deny` | 阻止特工在这个项目中获取秘密 | 只有一个人 | | `arca projects [rm ]` | 这台机器上有秘密的项目 | 列表 | ## `arca.json` ```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`:相同的变量,几个不同的值. 一切相相相相相相相等相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相 你随便换换. ```json { "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`。 。 。 . ```console $ 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=`。 。 。 . 配置文件只决定哪个值是 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.` 文件作为配置文件。 一个在它宣布配置文件之前有值的项目会保留它们:它们会在第一次运行时移动到默认配置文件. ## 弧形中的秘密, 配置在 `.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. ## 支持的平台 | 平台 | 状态 | | --- | --- | | 视窗10和11 | 供养已. 每一次推都通过CI测试 | | Linux, 包括 WSL | 供养已. 在CI中测试了每一次推力, 包括针对真正的GNOME键盘 | | 马科斯 | 尚未支持 。 阿尔卡可能有用,但那里没有测试. `arca init` 财务报告和审定财务报表 `arca doctor` 显示警告 | CI测试了Windows x64,Linux x64和arm64,以及高山(musl),有npm,pnpm,纱线(1和4)和包. 节点24或更新. ## 保存着的东西 | 什麽 | 何处 | | --- | --- | | 加密金库 | `%LOCALAPPDATA%\arca` (窗户), `~/.local/share/arca` 或者说 `$XDG_DATA_HOME/arca` (Linux). 覆盖 `ARCA_HOME`。 。 。 . | | 主密钥 | Windows Creditial Manager, 或Linux上的特务(GNOME Keyring, KWallet). 在无持久性键链(WSL,无头Linux,或特勤局不回应)的地方,Arca使用密码句取而代之(`ARCA_KEYCHAIN=passphrase` 强迫它。 您键入一次: 在 Linux 上, 解锁的密钥会在内核密钥环中被记住12小时, 直到最晚重启为止 . `ARCA_PASSPHRASE_CACHE=` 改变, `0` 关掉. `npx arca doctor` 显示直到人们记得它. | 在 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`。 。 。 . ## 许可证 [麻省理工学院](https://npmcn.com/package/%40bremmdev/arca-env/LICENSE). 为任何目的自由使用、复制、修改和分发. ## 常见问题 ### @bremmdev/arca-env 是什么？ 把秘密从\.env的档案中保密,并且不让AI特工知道\. 加密了本地商店,在运行时注入,输出总是被遮掩\. ### 如何安装 @bremmdev/arca-env？ 在项目目录运行 npm install @bremmdev/arca-env，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 arca，可以用 npx arca 直接运行。 ### @bremmdev/arca-env 支持 TypeScript 吗？ 该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/bremmdev\_\_arca-env 是否存在。 ### @bremmdev/arca-env 支持 ESM 还是 CommonJS？ 以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。 ### @bremmdev/arca-env 需要什么版本的 Node\.js？ package\.json 的 engines 字段要求 Node\.js \>=24。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。 ### @bremmdev/arca-env 可以商用吗？ @bremmdev/arca-env 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @bremmdev/arca-env 的下载量有多少？ 根据 npm 官方下载统计，@bremmdev/arca-env 在 2026/10/09 – 2026/11/07 这 30 天内被下载 1,714 次，日均约 57 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @bremmdev/arca-env 还在维护吗？ 最新版本 0\.4\.2 发布于 2026/11/06（4 天前）；至今共发布 10 个版本，其中过去 12 个月发布了 10 个；首次发布于 2026/10/22。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。