# 标记 SDK Flags SDK（`flags` npm 包）是 Next.js 和 SvelteKit 的功能标志工具包。它将每个功能标志转换为可调用函数，通过适配器与任何标志提供程序一起使用，并使用预计算模式保持页面静态。 Vercel Flags 是第一方提供商，可让您从 Vercel 仪表板或“vercel flags” CLI 管理标志。 * 文档： * 仓库： ## 核心概念 ### 标志作为代码每个标志都被声明为一个函数。调用站点没有字符串键：从“flags/next”导入{flag}；导出 const exampleFlag = 标志({ 键：'示例标志'，决定（）{返回假； }, }); const 值 = 等待 exampleFlag(); ### 服务器端评估标志评估服务器端以避免布局变化、保持页面静态并保持机密性。将路由中间件与预计算模式相结合，以提供来自 CDN 的静态变体。 ### 适配器模式适配器替换标志声明中的“decide”和“origin”，将您的标志连接到提供者。 Vercel Flags (`@flags-sdk/vercel`) 是第一方适配器。第三方适配器可用于 Statsig、LaunchDarkly、PostHog 等。从“flags/next”导入{flag}；从 '@flags-sdk/vercel' 导入 { vercelAdapter }；导出 const exampleFlag = 标志({ 键：'示例标志'，适配器：vercelAdapter(), }); ## 代理工作流程：创建新标志当用户要求您创建或添加功能标志时，请按顺序执行以下步骤。不要将 CLI 步骤保留为用户的“后续步骤”——您自己执行它们。 ### 开始之前检查项目状态以调整命令并决定可以跳过哪些步骤： * 存在哪个锁文件（`pnpm-lock.yaml`、`package-lock.json`、`yarn.lock`、`bun.lockb`）？ → 相应地调整所有包管理器命令（`pnpm add`、`npm install`、`yarn add`、`bun add`）。 * “flags”在“package.json”中吗？ → 跳过安装（步骤 1） * `.vercel/` 目录是否存在？ → 项目已链接，跳过步骤 2 中的“vercel link” * `.env.local` 是否包含 `FLAGS=`？ → 环境变量已经拉取，跳过步骤 3 * `flags.ts`（或`lib/flags.ts`、`src/flags.ts`）是否存在？ → 添加而不是从头开始创建（第 4 步） * `@vercel/toolbar` 是否在 `package.json` 中？ → 跳过工具栏设置（步骤 6） * `app/.well-known/vercel/flags/route.ts` 是否存在？ → Flags Explorer 已设置，跳过步骤 7 ### 步骤 1. **安装软件包**（如果 `package.json` 中尚未安装）： pnpm 我标记@flags-sdk/vercel 2. **使用 Vercel 注册标志**：运行 `vercel flags add --kind boolean --description ""`。 > **先决条件**：`vercel flags` 命令需要安装并验证 Vercel CLI。如果未安装 Vercel CLI，请运行“pnpm i -g vercel”。对于身份验证或链接问题，请阅读并遵循“vercel-cli”技能。如果未安装，请运行“npx Skills add https://github.com/vercel/vercel --skill vercel-cli”。在运行“vercel flags add”之前，请验证项目是否已链接到 Vercel。检查项目根目录中是否有“.vercel”目录。如果不存在，请先运行 `vercel link`。 3. **拉取环境变量**：运行`vercel env pull`将`FLAGS`和`FLAGS_SECRET`写入`.env.local`。如果没有这些环境变量，`vercelAdapter()` 将无法评估标志。创建标志后，此步骤是**强制**。 4. **在代码中声明标志** ：使用 `vercelAdapter()` 将其添加到 `flags.ts` （如果不存在则创建该文件）：从“flags/next”导入{flag}；从 '@flags-sdk/vercel' 导入 { vercelAdapter }；导出 const myFlag = 标志({ 键：'我的标志'，适配器：vercelAdapter(), }); 5. **使用标志**：在页面或组件中调用它并根据结果有条件地渲染：从 '../flags' 导入 { myFlag }；导出默认异步函数 Page() { const 已启用 = 等待 myFlag(); 返回

{启用？ '功能开启' : '功能关闭'}

; } 6. **设置 Vercel 工具栏**（如果尚未存在）： * 运行 `pnpm i @vercel/toolbar` * 使用工具栏插件包装 `next.config.ts` * 在根布局中渲染 `` 有关完整代码，请参阅 [references/nextjs.md — 工具栏设置]()。 7. **设置 Flags Explorer**（如果尚未存在）：创建 `app/.well-known/vercel/flags/route.ts` — 请参阅下面的 Flags Explorer 设置部分。 ## 维塞尔标志 Vercel Flags 是 Vercel 的功能标志平台。您可以从 Vercel 仪表板或“vercel flags” CLI 创建和管理标志，然后使用“@flags-sdk/vercel”适配器将它们连接到您的代码。当您在 Vercel 中创建标志时，会自动配置“FLAGS”和“FLAGS_SECRET”环境变量。要创建端到端标志，请遵循上面的代理工作流程。有关完整的 Vercel 提供程序参考 — 用户定位、`vercel flags` CLI 子命令、自定义适配器配置和 Flags Explorer 设置 — 请参阅 [references/providers.md]()。 ## 声明标志使用 Vercel Flags 时，请使用 `vercelAdapter()` 声明标志，如代理工作流程中所示。对于其他提供程序，请参阅 [references/providers.md]()。以下是一般的“flag()”模式。 ### 基本标志从“flags/next”导入{flag}； // 或 'flags/sveltekit' 导出 const showBanner = flag({ key: '显示横幅', 描述: '显示促销横幅', 默认值：假，选项：[ { 值: false, 标签: '隐藏' }, { 值: true, 标签: '显示' }, ], 决定（）{返回假； }, }); ### 带有评估上下文的标志使用“identify”来确定请求的对象。返回的实体被传递给“decide”：从 'flags/next' 导入 { dedupe, flag }; 从“flags”导入类型{ReadonlyRequestCookies}；接口实体{ 用户？：{ id：字符串}； } const 识别 = 重复数据删除( ({ cookies }: { cookies: ReadonlyRequestCookies }): 实体 => { const userId = cookies.get('user-id')?.value; 返回 { 用户：用户 ID ？ { id: userId } : 未定义 }; }, ）；导出常量仪表板Flag = flag <布尔值，实体>（{ key: '新仪表板', 识别，决定（{实体}）{ if (!entities?.user) 返回 false； return ['user1', 'user2'].includes(entities.user.id); }, }); ### 使用另一个适配器标记适配器将标志连接到第三方提供商。每个适配器都会替换“decide”和“origin”：从“flags/next”导入{flag}；从'@flags-sdk/statsig'导入{statsigAdapter}；导出 const myGate = 标志({ 键：'我的门'，适配器： statsigAdapter.featureGate((gate) => gateway.value), 识别， }); 有关所有受支持的适配器，请参阅 [references/providers.md]()。 ### 关键参数参数|类型 |描述 ---|---|--- `关键` | `字符串` |唯一标志标识符 `决定` | `函数` |解析标志值 `默认值` | `任何` |如果“decide”返回未定义或抛出异常，则回退 `描述` | `字符串` |显示在标志资源管理器中 `起源` | `字符串` |用于管理提供商仪表板中标志的 URL `选项` | `{ 标签？：字符串，值：任意 }[]` |可能的值，用于预计算 + Flags Explorer `适配器` | `适配器` |实现“决定”和“起源”的提供者适配器 `识别` | `函数` |返回“decide”的评估上下文（实体） ## 重复数据删除将共享函数（尤其是“identify”）包装在“dedupe”中，以便每个请求运行一次：从'flags/next'导入{重复数据删除}； const 识别 = 重复数据删除(({ cookies }) => { return { user: { id: cookies.get('uid')?.value } }; }); 注意：“重复数据删除”在 Pages Router 中不可用。 ## 标记资源管理器设置 ### Next.js（应用程序路由器） // app/.well-known/vercel/flags/route.ts 从 'flags/next' 导入 { getProviderData, createFlagsDiscoveryEndpoint }; 从 '../../../../flags' 导入 * 作为标志；导出 const GET = createFlagsDiscoveryEndpoint(async () => { 返回 getProviderData(flags); }); ### 使用外部提供商数据将第三方提供商与 Vercel Flags 一起使用时，请将其数据与“mergeProviderData”合并。每个提供程序适配器都会导出自己的“getProviderData” - 请参阅 [references/providers.md]() 中特定于提供程序的示例。 ### SvelteKit // src/hooks.server.ts 从 'flags/sveltekit' 导入 { createHandle }；从 '$env/static/private' 导入 { FLAGS_SECRET }；从 '$lib/flags' 导入 * 作为标志；导出 const 句柄 = createHandle({ 秘密: FLAGS_SECRET, 标志 }); ## 标志_秘密预计算和 Flags Explorer 所需。必须是 32 个随机字节，base64 编码：节点-e“console.log(crypto.randomBytes(32).toString('base64url'))” 存储为“FLAGS_SECRET”环境变量。在 Vercel 上：“vc env add FLAGS_SECRET”，然后“vc env pull”。 ## 预计算模式在使用功能标志时，使用预计算保持页面静态。中间件评估标志并通过重写将结果编码到 URL 中。该页面读取预先计算的值而不是重新计算。高级流程： 1. 声明标志并将它们分组到一个数组中 2. 在中间件中调用`precompute(flagGroup)`，得到一个`code`字符串 3. 将请求重写为`/${code}/original-path` 4.页面从`code`中读取flag值：`await myFlag(code, flagGroup)` 有关完整的实现细节，请参阅特定于框架的参考： * **Next.js** ：参见 [references/nextjs.md]() — 涵盖代理中间件、预计算设置、ISR、generatePermutations、多个组 * **SvelteKit** ：参见 [references/sveltekit.md]() — 涵盖重新路由钩子、中间件、预计算设置、ISR、预渲染 ## 自定义适配器创建一个适配器工厂，返回一个带有“origin”和“decide”的对象。有关完整模式（包括默认适配器和单例客户端示例），请参阅 [references/providers.md]()。 ## 加密函数为了在浏览器中保持标记数据的机密性（由 Flags Explorer 使用）：功能|目的 ---|--- `加密标志值` |加密已解析的标志值 `decryptFlagValues` |解密标志值 `加密标志定义` |加密标志定义/元数据 `decryptFlagDefinitions` |解密标志定义 `加密覆盖` |加密工具栏覆盖 `decryptOverrides` |解密工具栏覆盖默认情况下都使用“FLAGS_SECRET”。示例：从“flags”导入{ encryptFlagValues }；从'flags/react'导入{FlagValues}；异步函数 ConfidentialFlags({ value }) { const 加密 = 等待 encryptFlagValues(值); 返回; } ## 反应组件从 'flags/react' 导入 { FlagValues, FlagDefinitions }; // 使用标志资源管理器的标志值呈现脚本标签 // 使用标志资源管理器的标志定义呈现脚本标签 ## 参考文献详细的框架和提供程序指南位于单独的文件中，以保持上下文简洁： * **[references/nextjs.md]()** ：Next.js 快速入门、工具栏、App Router、Pages Router、中间件/代理、预计算、重复数据删除、仪表板页面、营销页面、悬念回退 * **[references/sveltekit.md]()** ：SvelteKit 快速入门、工具栏、挂钩设置、使用重新路由+中间件进行预计算、仪表板页面、营销页面 * **[references/providers.md]()** ：所有提供者适配器 - Vercel、Edge Config、Statsig、LaunchDarkly、PostHog、GrowthBook、Hypertune、Flagsmith、Reflag、Split、Optimizely、OpenFeature 和自定义适配器 * **[references/api.md]()** : `flags`、`flags/react`、`flags/next` 和 `flags/sveltekit` 的完整 API 参考

标志SDK

包含技能