@growthbook/edge-utils

中文文档
0.3.0发布于 2026/11/03MITTypeScriptCommonJS近 30 天下载 1.2万

边际工人基础应用

中文使用文档
文档目录7 节
  1. 安装
  2. 执行 Edge App 请求处理器
  3. 设置环境变量
  4. 设置有效载荷缓存( 可选)
  5. 配置
  6. 生命周期钩
  7. 进一步阅读

生长图 (基数)

增长图书 是一个模块化的地物标记和实验平台.

这个 生长图 提供一键可视化编辑器和URL在边缘重定向实验,同时不使用任何与前端实验相关的闪烁器,同时支持手动特性标出和实验. 它作为智能代理层在您的应用程序和终端用户之间运行. 也可以将全水化的前端 SDK 注入到渲染的页面上,这意味着不需要额外的网络请求.

  • 自动运行服务器侧或混合视觉实验而无需重排闪存.
  • 自动运行服务器侧或混合 URL 重定向实验, 不闪烁或延迟 .
  • 使用自定义特性标记和实验逻辑 生命周期钩。 。 。 .
  • 用水合有效载荷注入JavaScript SDK,使得前端可以拾取边缘所留下而没有任何额外网络请求的地方.

[注]

这是卖家不可知论 基础应用程序 用于 GrowthBook Edge App 的游戏。 它被我们的供应商专用的边缘Apps(Cloudflare Workers, Lambda@Edge)所使用. 您也可以轻松为您的边缘提供者构建自定义执行 .

安装

执行 Edge App 请求处理器

要运行边缘应用程序,请在您的项目中加入我们的软件处理器。 您需要手动构建应用程序上下文和辅助函数 :

import { edgeApp, getConfig, defaultContext } from "@growthbook/edge-utils";

export async function handler(request, env) {
  const context = await init(env);
  return edgeApp(context, request);
}

function init(env) {
  const context = defaultContext;
  context.config = getConfig(env);
  context.helpers = {
    // define utility functions for request/response manipulation
  };
return context;
}

设置环境变量

在环境变量中至少添加这些所需的字段:

PROXY_TARGET="https://internal.mysite.io"  # The non-edge URL to your website
GROWTHBOOK_API_HOST="https://cdn.growthbook.io"
GROWTHBOOK_CLIENT_KEY="abc123"
GROWTHBOOK_DECRYPTION_KEY="qwerty1234"  # Optional

参见 配置 节.

设置有效载荷缓存( 可选)

设置边键-val商店,并可选使用GrowthBook SDK Webhook来保持特性和实验值同步在GrowthBook和你的边缘工人之间. 这将消除您边缘到 GrowthBook 的网络请求 .

配置

GrowthBook Edge App支持通过环境变量提供的一些配置选项:

代理行为

  • PROXY_TARGET - 网站的源(非对接)基址
  • FORWARD_PROXY_HEADERS - “ true” 或“ 1” 从服务器保存响应信头( 默认) true(中文(简体) )
  • FOLLOW_REDIRECTS - “ true” 或“ 1” 处理源响应时跟踪方向( 默认) true(中文(简体) )
  • USE_DEFAULT_CONTENT_TYPE - “ true”或“ 1” 假设“ text- html” 的内容类型, 如果没有设置“ Content- Type” 页眉( 默认) false) (中文(简体) ).
  • PROCESS_TEXT_HTML_ONLY - “ true”或“ 1”只处理服务器的响应 Content-Type: text/html 页眉设置 - 其它将经过( 默认) true) (中文(简体) ).
  • AUTO_INFLATE -"真"或"一"自动解析出gzip内容. 大多数供应商不需要(默认: false) (中文(简体) ).
  • NOCACHE_ORIGIN -"真"或"一" 发送"nocache"头条的起源请求。 大多数供应商不需要(默认: false) (中文(简体) ).
  • NODE_ENV - 默认 : production
  • ROUTES - JSON根据请求URL模式匹配编码的路由、拦截规则、代理通过规则或出错

实验行为

  • RUN_VISUAL_EDITOR_EXPERIMENTS - 一个 everywhere, (中文(简体) ), edge, (中文(简体) ), browser,或 skip (默认) everywhere(中文(简体) )
  • DISABLE_JS_INJECTION - “ true” 或“ 1” 以跳过来自视觉实验的注射 JavaScript( 默认) false(中文(简体) )
  • RUN_URL_REDIRECT_EXPERIMENTS - 一个 everywhere, (中文(简体) ), edge, (中文(简体) ), browser,或 skip (默认) browser(中文(简体) )
  • RUN_CROSS_ORIGIN_URL_REDIRECT_EXPERIMENTS - 一个 everywhere, (中文(简体) ), edge, (中文(简体) ), browser,或 skip (默认) browser(中文(简体) )
  • INJECT_REDIRECT_URL_SCRIPT - “ true” 或“ 1” 通过窗口变换浏览器 URL. history. replace State () 来反映重定向的 URL( 默认) true(中文(简体) )
  • MAX_REDIRECTS - 保释前计算出的前沿转接次数。 只能从您的源头获取最终方向 。 (默认) 5(中文(简体) )
  • EXPERIMENT_URL_TARGETING - URL瞄准视觉编辑器和重定向实验: request 使用边缘工人URL的目标; origin 使用源服务器 URL。 (默认) request(中文(简体) )

前端 SDK 水合

  • SCRIPT_INJECTION_PATTERN - 在此符号前注入 GrowthBook SDK( 默认) </head>(中文(简体) )
  • DISABLE_INJECTIONS - “ true”或“ 1” 完全禁用 SDK 注射,包括跟踪回调( 默认) false(中文(简体) )

GrowthBook SDK 行为

  • GROWTHBOOK_API_HOST - 必需
  • GROWTHBOOK_CLIENT_KEY - 必需
  • GROWTHBOOK_DECRYPTION_KEY - 使用加密的 SDK 连接时需要

  • STALE_TTL - 模拟 SDK 缓存 TTL( 默认 1分钟 = 60000) (中文(简体) ).
  • GROWTHBOOK_TRACKING_CALLBACK - 自定义 JavaScript 客户端跟踪回调的字符串表示.
  • ENABLE_STREAMING - “ true” 或“ 1” 启用前端 SSE 流线( 默认) false(中文(简体) )
  • ENABLE_STICKY_BUCKETING - “ true” 或“ 1” 以默认方式启用粘性 Bucketing( 默认) false(中文(简体) )
  • STICKY_BUCKET_PREFIX - 粘盘饼干的名称前缀( 默认) gbStickyBuckets__(中文(简体) )

用户属性行为

  • PERSIST_UUID - “ true”或“ 1” 从边缘服务器而不是从浏览器( 默认) 将用户的ID写入 cookie false(中文(简体) )
  • NO_AUTO_COOKIES - “真”或“ 1” 以避免写出任何饼干( 不包括粘贴 Buckets) ,直到用户在前端通过 document.dispatchEvent(new CustomEvent("growthbookpersist")); (默认) false(中文(简体) )
  • UUID_COOKIE_NAME - 自定义粘接用户ID的饼干名( 默认) gbuuid(中文(简体) )
  • UUID_KEY - 自定义用户标识名称(默认) id(中文(简体) )
  • SKIP_AUTO_ATTRIBUTES “ true” 或“ 1” 跳过自动生成目标属性( 默认) false(中文(简体) )

生命周期钩

  • ALWAYS_PARSE_DOM - 通常,只有在出现视觉变化时,工人才会建立虚拟DOM。 设定为" true"或"1",总是会构建虚拟DOM,以便您可以在生命周期钩子(例如: onBodyReady(中文(简体) )

杂项

  • CONTENT_SECURITY_POLICY - CSP头值
  • EMIT_TRACE_HEADERS - “ true” 或“ 1” 设置额外的信头, 以检测边缘重定向回路并稳定 gbuuid 生成( 默认) true) (中文(简体) ).

生命周期钩

您可以在 Edge App 生命周期的不同阶段执行自定义逻辑并可选择返回一个响应. 这样可以表达自定义的路由,用户属性突变,头和体(DOM)突变,以及自定义特征旗和实验执行——同时保留自动运行可视和URL重定向实验和SDK水分的能力.

通过每个钩子,您可以突变所提供的任何属性 或者说 返回早期响应以停止 Edge App 处理。 以下钩子可供使用

  • onRequest - 最初用户要求时被解雇。 可以根据请求的 URL 提前退出 .
  • onRoute - 在标准路线处理完毕后被解除。 可以基于手动路由逻辑提前出站(代理).
  • onUserAttributes - 在自动属性分配给用户后被解除。 要么加强所提供的 attributes 如果需要,则提前对象或退出.
  • onGrowthBookInit - Edge App内部GrowthBook SDK被初始化后被放出. 如果需要,请提前调用 SDK 函数或退出 .
  • onBeforeOriginFetch - 与上述相似的钩;在进行URL重定向实验后,但在提出任何原产地请求之前触发.
  • onOriginFetch - 在找到原产地后立即开火,但在全部反应尸体被俘之前。 用于根据响应状态或信头提前退出.
  • onBodyReadyParams - 一旦整个反应体被解析出来,就发射 除了提前退出外,您还可以通过 resHeaders 编辑 setBody() 方法。 案文 body 以及可选解析的虚拟 DOM root (默认残疾,使用) ALWAYS_PARSE_DOM 被曝光。 注:如果 root DOM,这是你的责任 setBody() ,在返回回复前有最新更改.
  • onBeforeResponse - 将响应还给用户之前所发射的最后钩子,在视觉编辑器的修改和客户SDK水分注射后触发. 虽然虚拟 DOM 已无法使用,但此钩可以用来应用通过 setBody()。 。 。 .

进一步阅读

见边缘App 文档 更多细节和实例.

版本与发布记录

@growthbook/edge-utils 共发布 25 个版本,首次发布于 2024/05/07;过去 12 个月发布了 4 个版本。

版本发布日期距今
0.3.0latest2026/11/0314 天前
0.2.92026/05/136 个月前
0.2.82026/02/178 个月前
0.2.72026/02/119 个月前
0.2.62025/08/191.2 年前
0.2.52025/03/201.7 年前

关于 @growthbook/edge-utils 的常见问题

@growthbook/edge-utils 是什么?

边际工人基础应用

如何安装 @growthbook/edge-utils?

在项目目录运行 npm install @growthbook/edge-utils,或使用 pnpm add / yarn add / bun add。

@growthbook/edge-utils 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@growthbook/edge-utils 支持 ESM 还是 CommonJS?

以 CommonJS 形式发布,可以直接 require();在 ES Module 项目中也可以用 import 引入(Node.js 会把 module.exports 作为默认导出)。

@growthbook/edge-utils 可以商用吗?

@growthbook/edge-utils 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@growthbook/edge-utils 的下载量有多少?

根据 npm 官方下载统计,@growthbook/edge-utils 在 2026/10/17 – 2026/11/15 这 30 天内被下载 11,783 次,日均约 393 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@growthbook/edge-utils 还在维护吗?

最新版本 0.3.0 发布于 2026/11/03(14 天前);至今共发布 25 个版本,其中过去 12 个月发布了 4 个;首次发布于 2024/05/07。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。