camofox-browser 贡献指南环境变量白名单安全、测试体系与代码风格规范【免费下载链接】camofox-browserStealth headless browser for AI agents — bypass Cloudflare, bot detection, and anti-scraping. Drop-in Puppeteer/Playwright replacement.项目地址: https://gitcode.com/GitHub_Trending/ca/camofox-browser导读本文基于 camofox-browser 仓库的 CONTRIBUTING.md系统梳理该项目对贡献者的硬性要求子进程环境变量白名单安全是最高优先级的红线规则测试命令体系与代码风格规范则是保证多端OpenClaw 插件、MCP 服务器、REST 服务行为一致的基础设施。读完本文你将掌握如何在 camofox-browser 中安全地给子进程传环境变量、如何用三层测试命令验证改动以及如何写出符合项目风格的代码并理解这些规则背后的源码级实现逻辑。一、环境变量安全绝不把宿主环境泄漏给子进程1.1 这是一条硬性规则camofox-browser 的核心架构是插件进程OpenClaw / MCP通过spawn启动一个 Node.js 服务子进程server.js再由该子进程管理 Camoufox 反检测浏览器。这意味着插件进程所拥有的全部环境变量都会成为潜在泄漏面——如果直接把process.env整体传给子进程宿主环境中的 API Key、令牌、数据库凭证等机密就会跟着子进程一起暴露一旦子进程被注入代码或转储环境后果不堪设想。因此 CONTRIBUTING.md 的第一条、也是最严厉的规则是Do not pass the host environment to child processes. This is a hard rule.即派生子进程例如从插件启动服务器时只能传递显式声明的环境变量白名单严禁使用...process.env之类的展开写法。1.2 错误示范与正确示范以下两个例子直接来自 CONTRIBUTING.md是代码审查中最常见的红线检查点// WRONG — leaks all host secrets to the child process spawn(node, [serverPath], { env: { ...process.env, CAMOFOX_PORT: 9377 }, }); // RIGHT — only what the child actually needs spawn(node, [serverPath], { env: { PATH: process.env.PATH, HOME: process.env.HOME, NODE_ENV: process.env.NODE_ENV, CAMOFOX_PORT: 9377, }, });对比可以看出错误写法只是追加了一个CAMOFOX_PORT却把宿主环境完整展开正确写法只挑选子进程真正需要的少数变量其余一概不传。新增环境变量时必须显式加入白名单且要同时在plugin.ts与tests/helpers/startServer.js两处同步维护前者是生产路径后者是测试路径二者共用同一份serverEnv配置。1.3 白名单机制的源码级实现规则落到代码上就是 lib/config.js 中集中定义的serverEnv。该项目将所有process.env读取收敛到这一个文件里统一审计源码注释明确写着All process.env access is centralized here for auditability再以白名单对象的形式向外提供// lib/config.js (节选) serverEnv: { PATH: process.env.PATH, HOME: process.env.HOME, NODE_ENV: process.env.NODE_ENV, CAMOFOX_BIND_HOST: process.env.CAMOFOX_BIND_HOST, CAMOFOX_ADMIN_KEY: process.env.CAMOFOX_ADMIN_KEY, CAMOFOX_API_KEY: process.env.CAMOFOX_API_KEY, CAMOFOX_ACCESS_KEY: process.env.CAMOFOX_ACCESS_KEY, CAMOFOX_EVALUATE_MAX_BODY_SIZE: process.env.CAMOFOX_EVALUATE_MAX_BODY_SIZE, CAMOFOX_COOKIES_DIR: process.env.CAMOFOX_COOKIES_DIR, CAMOFOX_UPLOADS_DIR: process.env.CAMOFOX_UPLOADS_DIR, CAMOFOX_TRACES_DIR: process.env.CAMOFOX_TRACES_DIR, CAMOFOX_PROFILE_DIR: process.env.CAMOFOX_PROFILE_DIR, CAMOUFOX_EXECUTABLE: process.env.CAMOUFOX_EXECUTABLE, PROXY_STRATEGY: process.env.PROXY_STRATEGY, PROXY_HOST: process.env.PROXY_HOST, PROXY_PORT: process.env.PROXY_PORT, // ... 代理、VNC、交互模式等约 40 项显式声明 }这份白名单覆盖了几类关键配置运行基础PATH、HOME、NODE_ENV认证与密钥CAMOFOX_ADMIN_KEY、CAMOFOX_API_KEY、CAMOFOX_ACCESS_KEY注意这些是需要转发给子进程的密钥转发本身经过白名单显式授权与盲目展开process.env有本质区别存储目录CAMOFOX_COOKIES_DIR、CAMOFOX_UPLOADS_DIR、CAMOFOX_TRACES_DIR、CAMOFOX_PROFILE_DIR浏览器与代理CAMOUFOX_EXECUTABLE、PROXY_*系列可选功能ENABLE_VNC、VNC_*、CAMOFOX_INTERACTIVE等。实际派生子进程的地方在 lib/launcher.js 的launchServer它用cp.spawn启动node server.js环境变量只取调用方传入的env参数并追加服务端口// lib/launcher.js (节选) const proc startProcess(node, args, { cwd: pluginDir, env: { ...env, CAMOFOX_PORT: String(port) }, stdio: [ignore, pipe, pipe], detached: false, });而 plugin.ts 与 plugin.js 中的startServer正是以{ ...cfg.serverEnv }为基底即上文白名单再按插件配置选择性叠加MAX_SESSIONS、MAX_TABS_PER_SESSION、SESSION_TIMEOUT_MS、BROWSER_IDLE_TIMEOUT_MS等运行参数。测试侧 tests/helpers/startServer.js 同样以{ ...cfg.serverEnv, DEBUG_RESPONSES: false, ...extraEnv }构造子进程环境。三个入口共用同一份白名单正是新增环境变量要同时在plugin.ts和tests/helpers/startServer.js同步这条贡献规则的由来。仓库还配套了专门的防泄漏测试tests/unit/noSecrets.test.js 会静态扫描lib/reporter.js、camofox.config.json、workers/crash-reporter/index.ts等分发文件断言其中不包含私钥材料如BEGIN RSA PRIVATE KEY、base64 形式的-----BEGIN、不包含硬编码密钥 blob并验证 Worker 侧密钥只能来自env.GH_APP_ID/env.GH_INSTALL_ID/env.GH_PRIVATE_KEY这类环境变量——从生产代码到配置文件再到远程 Worker三层杜绝机密硬编码。1.4 禁止 dotenv绝不加载.env文件白名单之外CONTRIBUTING.md 还有第二条禁令不使用dotenv不加载任何.env文件。原因很实际camofox 常与其他工具共存于同一台机器用户目录下可能存在包含机密的其他工具.env文件。服务器只应从显式传入的环境变量读取配置统一由 lib/config.js 的loadConfig完成解析一旦引入 dotenv 自动加载机制就可能把无关工具的秘密卷进本进程破坏白名单规则建立的全部防线。这也是为什么 lib/config.js 里所有配置端口、超时、密钥、目录、代理全部从process.env.*显式读取、并带有默认值兜底而没有任何dotenv.config()调用。二、测试体系三层命令与两种开关CONTRIBUTING.md 规定的测试命令如下npm test # e2e tests npm run test:live # live site tests (requires RUN_LIVE_TESTS1) npm run test:debug # with server output (DEBUG_SERVER1)对照 package.json 中的scripts可以还原它们的完整语义文档中为简洁起见只写了摘要实际脚本是分层组合npm test实际执行npm run test:unit npm run test:e2e npm run test:plugins——依次跑单元测试tests/unit、端到端测试jest.config.e2e.cjs和插件测试plugins/均以--runInBand --forceExit串行执行。单元测试数量庞大且高度聚焦例如 tests/unit/config.test.js 会逐项断言serverEnv白名单的取值行为tests/unit/noSecrets.test.js 做机密扫描。npm run test:live对应RUN_LIVE_TESTS1 ... jest tests/live用于访问真实外部站点的场景。它默认是跳过的——tests/live/googleSearch.test.js 与 tests/live/macroExpansion.test.js 开头都有const SKIP_LIVE_TESTS !process.env.RUN_LIVE_TESTS;门控未设置该变量时测试被test.skip掉。原因正如源码注释所写Live Google tests are opt-in due to potential captchas/rate limiting——真实站点可能触发验证码或限流不适合作为默认 CI 用例。npm run test:debug对应DEBUG_SERVER1 ... jest --runInBand --forceExit不指定目录全量跑。DEBUG_SERVER开关在 tests/helpers/startServer.js 中生效只有设置该变量时测试助手才把服务器子进程的 stdout/stderr 打印出来方便排查启动失败或请求异常。三个命令组合起来构成完整的分层策略单元测试保证白名单与配置逻辑正确e2e 保证服务器端到端行为正确live 测试在显式开启时验证真实站点兼容性debug 模式则用于失败定位。三、代码风格可读性、常量与错误契约CONTRIBUTING.md 的代码风格规范短而严格每条都能在源码中找到对应实践不写解释代码行为的注释——保持代码本身可读。lib/config.js中的注释只承担安全审计定位等元信息职责而不是复述代码在做什么。默认const仅在有重赋值需求时用let——仓库中 lib/launcher.js 的startProcess cp.spawn这类仅初始化一次的绑定全部是constlet只出现在serverProcess、serverPort这类生命周期会变化的进程句柄上。错误响应统一为{ error: message }并携带恰当的 HTTP 状态码——这是 REST API 层的对外契约贯穿server.js及各路由处理器客户端只需检查error字段即可稳定地处理失败。所有 tab 操作必须携带userId以实现会话隔离——plugin.ts 中每次工具调用都会取ctx.agentId无则回退到随机生成的camofox-uuid作为userId传入runTool服务端据此隔离会话、限制MAX_SESSIONS、MAX_TABS_PER_SESSION等配额camofox tabs --user userId命令也支持按用户过滤标签页。这条规则直接服务于多租户场景下的数据隔离。四、提交前的自查清单综合全文向 camofox-browser 提交改动前请核对派生子进程只传cfg.serverEnv白名单没有...process.env展开新增的环境变量已同时加入lib/config.js的serverEnv、plugin.ts/plugin.js与tests/helpers/startServer.js没有引入dotenv没有加载.env文件本地已通过npm test全量unit e2e plugins涉及真实站点时用RUN_LIVE_TESTS1 npm run test:live验证失败排查用DEBUG_SERVER1 npm run test:debug代码无解释性注释、默认const、错误返回{ error: message }格式tab 相关改动均以userId为会话隔离前提。需要进一步对照源码时可重点阅读 lib/config.js白名单定义与配置解析、lib/launcher.js子进程派生、plugin.ts插件侧启动与工具注册、tests/helpers/startServer.js测试侧启动以及 tests/unit/noSecrets.test.js机密扫描防线。【免费下载链接】camofox-browserStealth headless browser for AI agents — bypass Cloudflare, bot detection, and anti-scraping. Drop-in Puppeteer/Playwright replacement.项目地址: https://gitcode.com/GitHub_Trending/ca/camofox-browser创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/15 14:58:35 · 阅读 1.2k camofox-browser 贡献指南：环境变量白名单安全、测试体系与代码风格规范
camofox-browser 贡献指南环境变量白名单安全、测试体系与代码风格规范【免费下载链接】camofox-browserStealth headless browser for AI agents — bypass Cloudflare, bot detection, and anti-scraping. Drop-in Puppeteer/Playwright replacement.项目地址: https://gitcode.com/GitHub_Trending/ca/camofox-browser导读本文基于 camofox-browser 仓库的 CONTRIBUTING.md系统梳理该项目对贡献者的硬性要求子进程环境变量白名单安全是最高优先级的红线规则测试命令体系与代码风格规范则是保证多端OpenClaw 插件、MCP 服务器、REST 服务行为一致的基础设施。读完本文你将掌握如何在 camofox-browser 中安全地给子进程传环境变量、如何用三层测试命令验证改动以及如何写出符合项目风格的代码并理解这些规则背后的源码级实现逻辑。一、环境变量安全绝不把宿主环境泄漏给子进程1.1 这是一条硬性规则camofox-browser 的核心架构是插件进程OpenClaw / MCP通过spawn启动一个 Node.js 服务子进程server.js再由该子进程管理 Camoufox 反检测浏览器。这意味着插件进程所拥有的全部环境变量都会成为潜在泄漏面——如果直接把process.env整体传给子进程宿主环境中的 API Key、令牌、数据库凭证等机密就会跟着子进程一起暴露一旦子进程被注入代码或转储环境后果不堪设想。因此 CONTRIBUTING.md 的第一条、也是最严厉的规则是Do not pass the host environment to child processes. This is a hard rule.即派生子进程例如从插件启动服务器时只能传递显式声明的环境变量白名单严禁使用...process.env之类的展开写法。1.2 错误示范与正确示范以下两个例子直接来自 CONTRIBUTING.md是代码审查中最常见的红线检查点// WRONG — leaks all host secrets to the child process spawn(node, [serverPath], { env: { ...process.env, CAMOFOX_PORT: 9377 }, }); // RIGHT — only what the child actually needs spawn(node, [serverPath], { env: { PATH: process.env.PATH, HOME: process.env.HOME, NODE_ENV: process.env.NODE_ENV, CAMOFOX_PORT: 9377, }, });对比可以看出错误写法只是追加了一个CAMOFOX_PORT却把宿主环境完整展开正确写法只挑选子进程真正需要的少数变量其余一概不传。新增环境变量时必须显式加入白名单且要同时在plugin.ts与tests/helpers/startServer.js两处同步维护前者是生产路径后者是测试路径二者共用同一份serverEnv配置。1.3 白名单机制的源码级实现规则落到代码上就是 lib/config.js 中集中定义的serverEnv。该项目将所有process.env读取收敛到这一个文件里统一审计源码注释明确写着All process.env access is centralized here for auditability再以白名单对象的形式向外提供// lib/config.js (节选) serverEnv: { PATH: process.env.PATH, HOME: process.env.HOME, NODE_ENV: process.env.NODE_ENV, CAMOFOX_BIND_HOST: process.env.CAMOFOX_BIND_HOST, CAMOFOX_ADMIN_KEY: process.env.CAMOFOX_ADMIN_KEY, CAMOFOX_API_KEY: process.env.CAMOFOX_API_KEY, CAMOFOX_ACCESS_KEY: process.env.CAMOFOX_ACCESS_KEY, CAMOFOX_EVALUATE_MAX_BODY_SIZE: process.env.CAMOFOX_EVALUATE_MAX_BODY_SIZE, CAMOFOX_COOKIES_DIR: process.env.CAMOFOX_COOKIES_DIR, CAMOFOX_UPLOADS_DIR: process.env.CAMOFOX_UPLOADS_DIR, CAMOFOX_TRACES_DIR: process.env.CAMOFOX_TRACES_DIR, CAMOFOX_PROFILE_DIR: process.env.CAMOFOX_PROFILE_DIR, CAMOUFOX_EXECUTABLE: process.env.CAMOUFOX_EXECUTABLE, PROXY_STRATEGY: process.env.PROXY_STRATEGY, PROXY_HOST: process.env.PROXY_HOST, PROXY_PORT: process.env.PROXY_PORT, // ... 代理、VNC、交互模式等约 40 项显式声明 }这份白名单覆盖了几类关键配置运行基础PATH、HOME、NODE_ENV认证与密钥CAMOFOX_ADMIN_KEY、CAMOFOX_API_KEY、CAMOFOX_ACCESS_KEY注意这些是需要转发给子进程的密钥转发本身经过白名单显式授权与盲目展开process.env有本质区别存储目录CAMOFOX_COOKIES_DIR、CAMOFOX_UPLOADS_DIR、CAMOFOX_TRACES_DIR、CAMOFOX_PROFILE_DIR浏览器与代理CAMOUFOX_EXECUTABLE、PROXY_*系列可选功能ENABLE_VNC、VNC_*、CAMOFOX_INTERACTIVE等。实际派生子进程的地方在 lib/launcher.js 的launchServer它用cp.spawn启动node server.js环境变量只取调用方传入的env参数并追加服务端口// lib/launcher.js (节选) const proc startProcess(node, args, { cwd: pluginDir, env: { ...env, CAMOFOX_PORT: String(port) }, stdio: [ignore, pipe, pipe], detached: false, });而 plugin.ts 与 plugin.js 中的startServer正是以{ ...cfg.serverEnv }为基底即上文白名单再按插件配置选择性叠加MAX_SESSIONS、MAX_TABS_PER_SESSION、SESSION_TIMEOUT_MS、BROWSER_IDLE_TIMEOUT_MS等运行参数。测试侧 tests/helpers/startServer.js 同样以{ ...cfg.serverEnv, DEBUG_RESPONSES: false, ...extraEnv }构造子进程环境。三个入口共用同一份白名单正是新增环境变量要同时在plugin.ts和tests/helpers/startServer.js同步这条贡献规则的由来。仓库还配套了专门的防泄漏测试tests/unit/noSecrets.test.js 会静态扫描lib/reporter.js、camofox.config.json、workers/crash-reporter/index.ts等分发文件断言其中不包含私钥材料如BEGIN RSA PRIVATE KEY、base64 形式的-----BEGIN、不包含硬编码密钥 blob并验证 Worker 侧密钥只能来自env.GH_APP_ID/env.GH_INSTALL_ID/env.GH_PRIVATE_KEY这类环境变量——从生产代码到配置文件再到远程 Worker三层杜绝机密硬编码。1.4 禁止 dotenv绝不加载.env文件白名单之外CONTRIBUTING.md 还有第二条禁令不使用dotenv不加载任何.env文件。原因很实际camofox 常与其他工具共存于同一台机器用户目录下可能存在包含机密的其他工具.env文件。服务器只应从显式传入的环境变量读取配置统一由 lib/config.js 的loadConfig完成解析一旦引入 dotenv 自动加载机制就可能把无关工具的秘密卷进本进程破坏白名单规则建立的全部防线。这也是为什么 lib/config.js 里所有配置端口、超时、密钥、目录、代理全部从process.env.*显式读取、并带有默认值兜底而没有任何dotenv.config()调用。二、测试体系三层命令与两种开关CONTRIBUTING.md 规定的测试命令如下npm test # e2e tests npm run test:live # live site tests (requires RUN_LIVE_TESTS1) npm run test:debug # with server output (DEBUG_SERVER1)对照 package.json 中的scripts可以还原它们的完整语义文档中为简洁起见只写了摘要实际脚本是分层组合npm test实际执行npm run test:unit npm run test:e2e npm run test:plugins——依次跑单元测试tests/unit、端到端测试jest.config.e2e.cjs和插件测试plugins/均以--runInBand --forceExit串行执行。单元测试数量庞大且高度聚焦例如 tests/unit/config.test.js 会逐项断言serverEnv白名单的取值行为tests/unit/noSecrets.test.js 做机密扫描。npm run test:live对应RUN_LIVE_TESTS1 ... jest tests/live用于访问真实外部站点的场景。它默认是跳过的——tests/live/googleSearch.test.js 与 tests/live/macroExpansion.test.js 开头都有const SKIP_LIVE_TESTS !process.env.RUN_LIVE_TESTS;门控未设置该变量时测试被test.skip掉。原因正如源码注释所写Live Google tests are opt-in due to potential captchas/rate limiting——真实站点可能触发验证码或限流不适合作为默认 CI 用例。npm run test:debug对应DEBUG_SERVER1 ... jest --runInBand --forceExit不指定目录全量跑。DEBUG_SERVER开关在 tests/helpers/startServer.js 中生效只有设置该变量时测试助手才把服务器子进程的 stdout/stderr 打印出来方便排查启动失败或请求异常。三个命令组合起来构成完整的分层策略单元测试保证白名单与配置逻辑正确e2e 保证服务器端到端行为正确live 测试在显式开启时验证真实站点兼容性debug 模式则用于失败定位。三、代码风格可读性、常量与错误契约CONTRIBUTING.md 的代码风格规范短而严格每条都能在源码中找到对应实践不写解释代码行为的注释——保持代码本身可读。lib/config.js中的注释只承担安全审计定位等元信息职责而不是复述代码在做什么。默认const仅在有重赋值需求时用let——仓库中 lib/launcher.js 的startProcess cp.spawn这类仅初始化一次的绑定全部是constlet只出现在serverProcess、serverPort这类生命周期会变化的进程句柄上。错误响应统一为{ error: message }并携带恰当的 HTTP 状态码——这是 REST API 层的对外契约贯穿server.js及各路由处理器客户端只需检查error字段即可稳定地处理失败。所有 tab 操作必须携带userId以实现会话隔离——plugin.ts 中每次工具调用都会取ctx.agentId无则回退到随机生成的camofox-uuid作为userId传入runTool服务端据此隔离会话、限制MAX_SESSIONS、MAX_TABS_PER_SESSION等配额camofox tabs --user userId命令也支持按用户过滤标签页。这条规则直接服务于多租户场景下的数据隔离。四、提交前的自查清单综合全文向 camofox-browser 提交改动前请核对派生子进程只传cfg.serverEnv白名单没有...process.env展开新增的环境变量已同时加入lib/config.js的serverEnv、plugin.ts/plugin.js与tests/helpers/startServer.js没有引入dotenv没有加载.env文件本地已通过npm test全量unit e2e plugins涉及真实站点时用RUN_LIVE_TESTS1 npm run test:live验证失败排查用DEBUG_SERVER1 npm run test:debug代码无解释性注释、默认const、错误返回{ error: message }格式tab 相关改动均以userId为会话隔离前提。需要进一步对照源码时可重点阅读 lib/config.js白名单定义与配置解析、lib/launcher.js子进程派生、plugin.ts插件侧启动与工具注册、tests/helpers/startServer.js测试侧启动以及 tests/unit/noSecrets.test.js机密扫描防线。【免费下载链接】camofox-browserStealth headless browser for AI agents — bypass Cloudflare, bot detection, and anti-scraping. Drop-in Puppeteer/Playwright replacement.项目地址: https://gitcode.com/GitHub_Trending/ca/camofox-browser创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考