# @guidelytech/flags 中文文档

规范地址：https://npmcn.com/package/%40guidelytech/flags/

版本：0\.18\.0
npm 元数据更新时间：2026-11-09T02:01:48.259Z
中文译文更新时间：2026-11-17T03:05:39.750Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40guidelytech/flags
原文对照：https://npmcn.com/package/%40guidelytech/flags/?lang=original
项目主页：https://github.com/GuidelyTech/Guidely/tree/main/packages/flags#readme
源码仓库：https://github.com/GuidelyTech/Guidely

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

- 包体积（解压后）：1 MB，28 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2026-10-19T17:59:28.423Z
- 最新版本发布：2026-11-09T02:01:48.068Z
- 近 30 天下载量：14353（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：13（近 12 个月 13 个）

## 中文简介

TypeScript 的向导特征旗和实验:浏览器,节点.js,Next.js,边缘运行时间

## 安装

```sh
npm install @guidelytech/flags
```

也可以使用：`pnpm add @guidelytech/flags`、`yarn add @guidelytech/flags`、`bun add @guidelytech/flags`

## README

# @ 指导技术/旗子

TypeScript 的向导特征旗帜,远程配置和实验. 一个浏览器客户端, Node.js ~ 18, Next.js (服务器和边缘), Deno, Bun and React Industrial; 没有运行时间依赖性.

如果您已经使用指南 SDK(`@guidelytech/react`, (中文(简体) ), `nextjs`, (中文(简体) ), `react-native`, (中文(简体) ), `svelte`, (中文(简体) ), `sveltekit`, (中文(简体) ), `sdk-core` 或脚本标签),旗帜构建于: `guidely.flags`, (中文(简体) ), `useFlag()`, (中文(简体) ), `flag()`...有身份、页面和设备属性 直接使用此软件包 用于服务器、边缘功能和只使用旗帜的应用程序.

```bash
pnpm add @guidelytech/flags
```

## 密钥

-   **公用钥匙** `pk_…` ——您已经用作环境密钥 `projectId` 用于跟踪。 工程 无处不在,没有其他配置.
-   **密钥** `gly_sk_…` (范围) `flags:read`——也需要 `environment`获取 ,当环境从公共密钥中隐藏规则时工作.

## 浏览器

```ts
import { createFlagsClient } from "@guidelytech/flags";

const flags = createFlagsClient({
  sdkKey: "pk_prod_…",
  apiUrl: "https://guidelytech.com",
  attributes: { id: user.id, plan: user.plan, account: { id: org.id } },
});

await flags.ready();
if (flags.isEnabled("new-checkout")) showNewCheckout();
const color = flags.getString("checkout-button-color", "blue");
flags.subscribe(() => render()); // payload, attribute or override changes
flags.updateAttributes({ plan: "enterprise" });
```

最后一个有效载荷保存在 `localStorage`因此,返回的来访者立即获得旗帜,并下线.

## 节点.js / 服务器

每个进程有一个客户;对每个请求进行评价 `forUser()` (它永远不会改变客户端):

```ts
import { createFlagsClient } from "@guidelytech/flags";

export const flags = createFlagsClient({ sdkKey: process.env.GUIDELY_SDK_KEY!, environment: "production" });

app.get("/checkout", async (req, res) => {
  await flags.ready(); // resolves once, after the first download (or failure)
  const f = flags.forUser({ id: req.user.id, plan: req.user.plan });
  res.render("checkout", { newCheckout: f.isEnabled("new-checkout"), limits: f.getJson("limits", {}) });
});
```

## 下一个.js

使用 `@guidelytech/nextjs/server` (单位:千美元)`getFlags()`, (中文(简体) ), `getFlagsBootstrap()`: 它让一个客户横跨 请求和热重装并绕过 Next.js 获取缓存 。 过 `getFlagsBootstrap()` 页:1 在服务器和客户端上生成相同值的浏览器提供者 .

## 边缘运行时间和无服务器

当缓存停止时

```ts
const flags = createFlagsClient({ sdkKey: "pk_prod_…", pollingMode: "lazy", cacheTtlSeconds: 30 });
```

## API 密码

|  |  |
| --- | --- |
| `ready()` 编号 : `isReady()` | 第一个负载确定( bootstrap, 网络成功或失败) 。 绝不拒绝. |
| `isEnabled(key, fallback = false)` | 只有布尔旗:任何其他值给出 `fallback`。 。 。 . |
| `getValue(key, fallback)` | 数值,或 `fallback` 失踪时,无效或属于JSON类型. |
| `getString` 编号 : `getNumber` 编号 : `getBoolean` 编号 : `getJson` | 键入器有相同的规则. |
| `getDetails(key, fallback)` | 数值加 `reason`, (中文(简体) ), `ruleId`, (中文(简体) ), `variationId`, (中文(简体) ), `experiment`, (中文(简体) ), `usedFallback`。 。 。 . |
| `getAll()` | 每面旗帜的值(记录不曝光). |
| `forUser(attributes)` | 获取其它属性( 合并到客户端) . |
| `setAttributes` 编号 : `updateAttributes` 编号 : `getAttributes` | 替换/ 合并/ 读取属性 . |
| `setOverrides(map | null)` | 当地价值(见 `overrideBehaviour`) (中文(简体) ). |
| `setOffline(bool)` 编号 : `refresh()` | 暂停网络活动 / 现在获取 . |
| `getPayload()` | 从服务器渲染中拖出浏览器的有效载荷(或远程结果) . |
| `subscribe(listener)` | 更改通知; 返回 `unsubscribe` (与 `useSyncExternalStore`) (中文(简体) ). |
| `flush()` 编号 : `destroy()` | 现在发送使用/ 停止计时器和流 . |

Getters 从不掷出也从不挡道:在旗下加载(或者如果向导无法到达)之前,他们返回 你的后退 以及最后的好载荷.

### 选项

| 选项 | 默认 |  |
| --- | --- | --- |
| `sdkKey` (别名) `projectId`(中文(简体) ) | —— 说 | `pk_…` 或者说 `gly_sk_…`。 。 。 . |
| `apiUrl` | `https://guidelytech.com` | 您的指南 URL . |
| `environment` | —— 说 | 要求为 `gly_sk_` 键. |
| `attributes` | `{}` | 默认属性. |
| `pollingMode` | `auto` | `auto` (每个 `pollIntervalSeconds`,默认为60, `lazy` (关于 `cacheTtlSeconds`, (中文(简体) ), `manual` (单位:千美元)`refresh()` 仅此而已, `stream` (服务器出席活动,断开时进行投票). |
| `payload` 编号 : `remoteResults` | —— 说 | 靴子:即时使用(`ready` (一时). |
| `remoteEval` | `false` | 对服务器进行评估( E)`POST /flags/evaluate`用于隐藏其规则的环境。 当公钥获得时自动打开 `remote_evaluation_required`。当属性改变时,重新评价(解析出);每个属性集的结果被缓存. |
| `decryptionKey` | —— 说 | 对于加密的有效载荷(AES-256-GCM通过WebCrypto). |
| `overrides` 编号 : `overrideBehaviour` | \- / (单位:千美元) `localOverRemote` | `localOnly` (从不取来; 覆盖,然后是靴子) `payload`, (中文(简体) ), `localOverRemote` (胜诉), `remoteOverLocal` (仅用于远程缺失的旗帜). |
| `devOverrides` | `true` | 读取 [dev 覆盖](https://npmcn.com/package/%40guidelytech/flags/#readme-dev-overrides-ci-and-tests) 从环境变量和测试全局. |
| `enableUrlOverrides` | `false` | 浏览器 QA : `?guidely_flags=new-checkout:true,checkout-button-color:"green"`。 。 。 . |
| `stickyBucketService` | —— 说 | `InMemoryStickyBucketStore` 编号 : `LocalStorageStickyBucketStore`:用户保留其实验变异. |
| `storage` | `localStorage` 在浏览器中 | 任意 `getItem`编号 :`setItem` 存储、同步或同步. `false` 禁用 . |
| `trackingCallback(experiment, result)` | —— 说 | 每(实验,用户,变异)一次:向你的分析仪发送曝光. |
| `trackExposures` | `true` 除非 `trackingCallback` | 向"向导"发送曝光,获取实验结果. |
| `reportUsage` | `true` | 合计评价计数,最多为每60人`sendBeacon` 在页面隐藏中). |
| `onReady`, (中文(简体) ), `onChange`, (中文(简体) ), `onFlagEvaluated`, (中文(简体) ), `onError` | —— 说 | 钩子. |
| `offline`, (中文(简体) ), `fetch`, (中文(简体) ), `logger`, (中文(简体) ), `now` | —— 说 | 开始下线; 自定义获取; `null` 沉默日志; 用于测试的时钟. |

`createStaticFlags({ payload, attributes })` 在没有网络的有效载荷上给同样的进取器 或跟踪——框架绑定使用它来提供服务器和水合物.

## Dev 覆盖( CI和测试)

不触摸应用程序的平子旗值 。 每个客户都读过一次,当它创建时:

| 来源 | 示例 |
| --- | --- |
| `GUIDELY_FLAG_OVERRIDES` | `new-checkout:true,limit:5,theme:"dark"` 或者说 `{"new-checkout":true}` |
| `GUIDELY_FLAG_OVERRIDES_FILE` | 路径到持有相同文本的文件( JSON 对象或一个) `key:value` (每行) |
| `GUIDELY_FLAG_OVERRIDE_BEHAVIOUR` | `localOnly` ——无网络,无缓存有效载荷:隐形试验 |
| `globalThis.__GUIDELY_FLAG_OVERRIDES__` 编号 : `__GUIDELY_FLAG_OVERRIDE_BEHAVIOUR__` | 对象或同文本,由页面中的测试导师设置 |

```bash
GUIDELY_FLAG_OVERRIDES='new-checkout:true' GUIDELY_FLAG_OVERRIDE_BEHAVIOUR=localOnly pnpm test
GUIDELY_FLAG_OVERRIDES_FILE=ci/flags.json pnpm test
```

样本 `ci/flags.json` (键为旗下键;给每个值为旗下类型,因为 类型错误或 `null` 使受难者返回倒计时:

```json
{
  "new-checkout": true,
  "checkout-button-color": "green",
  "max-cart-items": 25,
  "pricing-page": { "layout": "grid", "plans": ["starter", "pro", "team"] },
  "holiday-banner": null
}
```

```ts
// Playwright: set before the page's scripts run.
await page.addInitScript(() => {
  (window as any).__GUIDELY_FLAG_OVERRIDES__ = { "new-checkout": true };
});
// Cypress: cy.visit("/", { onBeforeLoad: (win) => { win.__GUIDELY_FLAG_OVERRIDES__ = { "new-checkout": true }; } });
```

每旗,后取胜: `overrides` 编号 : `setOverrides()` \* 文件 · 可变 · 全球 · `?guidely_flags=`。 。 。 . `setOverrides()` 仅取代第一个。 价值有道理 `OVERRIDE`客户端 日志一个列出使用中的源的警告, 因此生产中设置的变量显示于 日志; 格式错误的源到 `onError` 并被置之不理. `devOverrides: false` 关掉它.

使用服务器渲染, 既设置:服务器代码的变量, 也设置浏览器的全局性变量 (反应和Svelte服务器使读取靴子载荷,该载荷没有覆盖). `parseOverrides(text)` 用于在其它地方读取相同的格式.

## 国 际

```bash
# In CI on your main branch: upload where each flag is used in code (shown on the flag's page).
npx guidely-flags code-refs --key "$GUIDELY_API_KEY" --environment production --repo acme/web

# Debug an evaluation.
npx guidely-flags evaluate --key pk_prod_… --flag new-checkout --attributes '{"id":"u1","plan":"pro"}'
```

`code-refs` 需要一个 `gly_sk_` 键为 `flags:read` 财务报告和审定财务报表 `flags:code-refs`它扫描来自 `git ls-files` (或散步跳过) `node_modules`, (中文(简体) ), `dist`, (中文(简体) ), `build`, (中文(简体) ), `vendor`...) 旗下 1 MB 键作为引用的字符串文字写入,并上传 `{ repo, branch, commit, refs }`部门 承诺默认为当前 git 退出( 或 `GITHUB_REF_NAME` 编号 : `GITHUB_SHA`) (中文(简体) ). `--dry-run` 打印参考文献. `guidely-flags --help` 列出每个选项.

评价语义在 [文件/地貌-旗帜-规格.md](https://github.com/GuidelyTech/Guidely/blob/main/docs/feature-flags-spec.md)。 。 。 .

## 常见问题

### @guidelytech/flags 是什么？

TypeScript 的向导特征旗和实验:浏览器,节点\.js,Next\.js,边缘运行时间

### 如何安装 @guidelytech/flags？

在项目目录运行 npm install @guidelytech/flags，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 guidely-flags，可以用 npx guidely-flags 直接运行。

### @guidelytech/flags 支持 TypeScript 吗？

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

### @guidelytech/flags 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @guidelytech/flags 可以商用吗？

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

### @guidelytech/flags 的下载量有多少？

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

### @guidelytech/flags 还在维护吗？

最新版本 0\.18\.0 发布于 2026/11/09（8 天前）；至今共发布 13 个版本，其中过去 12 个月发布了 13 个；首次发布于 2026/10/20。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

