vercel-flags

Vercel Flags

Vercel Flags 是 Vercel 的功能标志平台。可以在 Vercel 控制面板中或通过 vercel flags CLI 创建和管理标志，在应用中通过服务端进行评估，并按环境（Development、Preview、Production）切换，无需重新部署。

• 文档：https://vercel.com/docs/flags
• CLI 参考：https://vercel.com/docs/cli/flags

使用此技能来决定如何为功能设置标志、创建和更改标志，以及运行逐步发布和实验。使用与技术栈匹配的技能编写应用代码（参见选择方案）。不要把 CLI 步骤留作用户的“后续步骤”；请自行执行。

路由请求

• 规划（“为此设置标志”“按 10% 的比例逐步发布”“对定价页面进行 A/B 测试”“添加紧急关闭开关”）：按照规划标志，然后按照选择方案。
• 无需更改代码即可创建或管理标志（创建、检查、启用、设置、拆分、逐步发布、配置规则、归档）：按照使用 CLI 管理标志。这需要经过身份验证的 CLI，而不是 SDK 包、Toolbar、Flags Explorer 或 .env.local（但 vercel flags override 会读取 FLAGS_SECRET）。
• 在项目间共享标志：按照项目连接连接同一团队中的项目，然后配置使用方应用。
• 清理或移除标志（“移除此标志”“清理过时标志”“将此标志内联”）：按照references/cleanup.md，然后在归档前查看生命周期与安全。
• 向已使用 Flags SDK 的应用添加标志（package.json 中有 flags）：立即加载 flags-sdk 技能；它会在 Vercel 上创建标志并在代码中声明该标志。
• 其他情况在代码中实现：按照选择方案，并加载匹配的技能或参考资料。在应用代码仓库中，将含糊的请求视为需要规划、创建并实现。

选择方案

编写代码前检查项目。

• 已使用其他标志提供商（Statsig、LaunchDarkly、PostHog、GrowthBook 等）：继续使用该提供商。在 Next.js 或 SvelteKit 中，Flags SDK 可通过适配器连接到该提供商；请加载 flags-sdk 技能。在其他技术栈中，使用该提供商自己的 SDK。该提供商的逐步发布、定向和实验需在其自己的控制面板中配置，而不是使用 vercel flags；此技能中的 CLI 和生命周期部分不适用。
• 尚无提供商：使用 Vercel Flags。根据技术栈选择集成方式（SDK）：
  • Next.js 或 SvelteKit：使用 Flags SDK（flags + @flags-sdk/vercel）。它支持 Flags Explorer 集成，并可为静态页面预计算。请加载 flags-sdk 技能。如果无法使用，请建议运行 npx skills add vercel/flags@flags-sdk（不要自动安装）。
  • 其他框架或普通服务端（例如 Express）：使用 @vercel/flags-core。参见其他框架。
  • 用户需要提供商可移植性或已使用 OpenFeature：使用 Vercel Flags OpenFeature 提供商（将 OpenFeature 与 Vercel Flags 配合使用）。

无论使用哪种集成方式，控制面板和 vercel flags CLI 的工作方式都相同。

规划一个标志

创建标志前，请先确定以下内容；之后无法更改标志类型。

• 类型：开关和紧急停用开关使用 boolean；如果标志用于选择变体或携带配置，则使用 string、number 或 json（标志类型）。
• 变体：使用行为命名（control、new-checkout），不要按发布阶段命名。
• 键：使用 kebab-case，保持稳定，并确保 CLI、控制面板和代码中的字符串一致（flag() 中的 key 或 evaluate() 的第一个参数）。
• 环境：每个环境都有自己的值或定向规则。规划好在发布时 Development、Preview 和 Production 各自提供什么。
• 定向：按百分比发布或进行 A/B 拆分时，需要一个稳定的分桶标识，例如 user.id。请先在 Flags → Entities 下定义实体和属性；应用必须在其评估上下文中返回相同的名称（实体）。
• 回退值：当标志已归档、尚未创建或评估失败时，应用提供的值。这将成为代码中的 defaultValue。
• 退出：除非是长期运行的运维开关，否则标志都是临时的。请在 references/cli.md — 生命周期与安全性 中规划移除顺序。

使用 CLI 管理标志

CLI 使用你的 Vercel 账户进行身份验证。SDK 密钥和 vercel env pull 是应用凭证，并非 CLI 的前置条件。

前置条件：必须已安装并完成身份验证的 Vercel CLI。如果尚未安装，请运行 pnpm i -g vercel。如遇到身份验证或关联问题，请使用 vercel-cli skill（如果可用）。如果不可用，请建议运行 npx skills add vercel/vercel@vercel-cli（不要自动安装），并暂时使用 vercel <command> --help。

运行 vercel flags --help 查看当前子命令列表，并在使用子命令前运行 vercel flags <cmd> --help。references/cli.md 涵盖了 --help 无法说明的内容：CLI 概念如何映射到应用、提升顺序、静态值与定向模式的区别，以及归档或删除前要执行的检查。

项目定向

使用 --project <name-or-id> 和 --scope <team>，无需本地关联即可选择目标。如果 CLI 拒绝 --project，请先升级 CLI（pnpm i -g vercel）。不使用这些选项时，命令会使用已关联的项目：运行 vercel project inspect --non-interactive 并检查报告中的所有者和项目名称；仅有 .vercel/ 目录并不能证明项目已关联。如果报告显示 link_required，则表示项目尚未关联。如果用户指定的项目或团队与输出不一致，请停止操作并询问用户，不要重新关联。在未关联的目录中，优先使用 --project / --scope，而不是 vercel link；如果目标项目不明确，请询问用户。

常见流程

始终先运行 inspect，了解各环境当前提供的内容，并让 CLI 键与应用已声明的标志相匹配；创建第二个标志不能替代采用现有标志。

• 创建：vercel flags create <key> --kind boolean --description "<description>"。如果键已存在，则采用现有键。
• 开启或关闭：布尔标志使用 enable / disable，任何类型的标志都可以使用 set <key> 来提供一个变体。这些操作会将环境设为静态值模式。
• 逐步发布：rollout <key> --by user.id ...（逐步发布功能）。
• A/B 测试：split <key> --by user.id ...（运行 A/B 测试）。
• 定向规则和分群：使用 rules、segments 和 targeting enable <key>，将环境从静态值切换回定向和规则模式（65 之前的 CLI 版本称其为 use-targeting <key>）。
• 验证：使用 inspect 查看当前提供的状态，使用 versions 查看历史记录，使用 evaluations 确认流量已到达新变体。
• 数据文件：datafile --environment <production|preview|development> --json 会显示 SDK 当前用于调试的数据文件。
• 退役：先移除代码（references/cleanup.md），确认没有评估记录后，再运行 archive；只有对已归档标志才能运行 rm。请遵循生命周期与安全。

archive、unarchive、rm 和 update --remove-variant 会提示确认。用户批准操作后，请传入 --yes。

凭据

• OIDC：在 Vercel 上，应用使用项目的 OIDC 令牌进行身份验证，并评估当前环境的配置。vercel env pull 会将 Development 令牌写入 .env.local，供本地开发使用（入门）。
• 项目连接：无需 SDK 密钥，即可使用使用方项目的 OIDC 令牌读取同一团队中其他项目的标志。请按照项目连接中的说明完成设置并满足最低版本要求。
• SDK 密钥（FLAGS）：适用于 Vercel 之外的应用、需要显式选择环境，或需要跨团队读取标志的情况。每个密钥仅限一个环境，并且只会在创建时显示一次（SDK 密钥）。这不是 CLI 身份验证失败时的恢复方式。
• FLAGS_SECRET：为项目启用 Vercel Flags 时，会针对每个环境创建该密钥。它用于签署 Flags Explorer 覆盖项和预计算代码，vercel flags override 会从环境或 .env.local 中读取它。请保留现有值，不要在日常设置中轮换；本地缺少该值不代表远程值也缺失，因此请先检查目标环境，再生成新值。flags-sdk 技能文档介绍了如何生成缺失的值。不要将密钥打印到终端、日志或聊天中。

Flags Explorer

Flags Explorer 是 Vercel Toolbar 面板，用于列出应用的标志，并允许通过由 FLAGS_SECRET 签名的 Cookie 在每个浏览器中覆盖这些标志（Flags Explorer）。应用会通过发现端点公开其标志；该端点由 Flags SDK 生成（flags-sdk 技能）。vercel flags override <key>=<value> 会在终端中生成相同的 Cookie 令牌。

其他框架

对于没有 Flags SDK 入口点的框架，直接使用 @vercel/flags-core（Core SDK）。在模块作用域创建一个客户端，并在请求处理程序中调用 evaluate() 或 bulkEvaluate()；两者都会在首次使用时初始化客户端。不要在模块作用域调用 client.initialize()，也不要缓存其 Promise 供处理程序等待。

// src/flags.ts
import { createClient } from "@vercel/flags-core";

const client = createClient();

// Call from a request handler, not during module loading.
export async function showNewCheckout(userId: string): Promise<boolean> {
  const result = await client.evaluate<boolean>("new-checkout", false, {
    user: { id: userId },
  });
  return result.value;
}

使用 OIDC 时，令牌可能来自请求上下文，在模块加载期间可能尚不存在。即使是嵌入式定义，也需要令牌来根据其 project_id 选择条目，而本地 .env.local 凭据可能会掩盖这一时序问题。显式初始化是可选的，且必须等到身份验证信息可用后再进行；之后再等待一个已经启动的初始化 Promise，并不会让初始化转移到请求上下文中。在 Vercel 之外，请传入 SDK 密钥：createClient(process.env.FLAGS)。

evaluate() 的第三个参数是评估上下文；其中的实体名称和属性名称必须与 Flags → Entities 下定义的名称一致，这样分流和规则才能据此进行分桶。

参考资料

• references/cli.md：说明 vercel flags 中的概念如何映射到应用（key、kind、variants、fallback、targeting attributes、timestamp conditions、authentication、overrides、embedded definitions、datafiles），以及推广、验证、移除和归档标志的生命周期与安全检查清单。
• references/cleanup.md：说明如何从代码中移除标志：需要遵循的仓库规则、需要收集的证据、要内联的值、何时停止、要删除的内容，以及清理 PR 应包含的内容。