# @growthbook/edge-utils 中文文档

规范地址：https://npmcn.com/package/%40growthbook/edge-utils/

版本：0\.3\.0
npm 元数据更新时间：2026-11-03T01:09:23.606Z
中文译文更新时间：2026-11-17T01:30:31.775Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40growthbook/edge-utils
原文对照：https://npmcn.com/package/%40growthbook/edge-utils/?lang=original
项目主页：https://github.com/growthbook/growthbook-proxy#readme
源码仓库：https://github.com/growthbook/growthbook-proxy

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：345 kB，51 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：3 个
- 首次发布：2024-05-06T21:16:17.951Z
- 最新版本发布：2026-11-03T01:09:23.387Z
- 近 30 天下载量：11783（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：25（近 12 个月 4 个）

## 中文简介

边际工人基础应用

## 安装

```sh
npm install @growthbook/edge-utils
```

也可以使用：`pnpm add @growthbook/edge-utils`、`yarn add @growthbook/edge-utils`、`bun add @growthbook/edge-utils`

## README

# 生长图 _(基数)_

[增长图书](https://www.growthbook.io/) 是一个模块化的地物标记和实验平台.

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

-   自动运行服务器侧或混合视觉实验而无需重排闪存.
-   自动运行服务器侧或混合 URL 重定向实验, 不闪烁或延迟 .
-   使用自定义特性标记和实验逻辑 [生命周期钩](https://npmcn.com/package/%40growthbook/edge-utils/#readme-lifecycle-hooks)。 。 。 .
-   用水合有效载荷注入JavaScript SDK,使得前端可以拾取边缘所留下而没有任何额外网络请求的地方.

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

## 安装

### 执行 Edge App 请求处理器

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

```javascript
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
```

参见 [配置](https://npmcn.com/package/%40growthbook/edge-utils/#readme-configuration) 节.

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

设置边键-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 [文档](https://docs.growthbook.io/lib/edge/other) 更多细节和实例.

## 常见问题

### @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 和提交记录判断。

