要在 Cloudflare Worker 中使用 Flagship,请将 Flagship 绑定添加到您的 Wrangler 配置文件中。该绑定使您的 Worker 可以访问 env.FLAGS,从而提供评估功能标志的方法。
将 flagship 块添加到您的 Wrangler 配置文件中,并附带绑定名称和您的应用程序 ID。
{
"flagship": [
{
"binding": "FLAGS",
"app_id": "<APP_ID>",
},
],
}[[flagship]]
binding = "FLAGS"
app_id = "<APP_ID>"将 <APP_ID> 替换为您 Flagship 应用程序中的应用程序 ID。如果您还没有创建应用程序,请参阅入门指南。binding 字段设置您在 Worker 代码中用于访问 Flagship 的名称(例如,env.FLAGS)。
单个 Worker 可以绑定到多个 Flagship 应用程序。使用数组形式定义多个绑定:
{
"flagship": [
{
"binding": "FLAGS",
"app_id": "<APP_ID_1>",
},
{
"binding": "EXPERIMENT_FLAGS",
"app_id": "<APP_ID_2>",
},
],
}[[flagship]]
binding = "FLAGS"
app_id = "<APP_ID_1>"
[[flagship]]
binding = "EXPERIMENT_FLAGS"
app_id = "<APP_ID_2>"每个绑定均可作为 env 对象上的单独属性使用(例如,env.FLAGS 和 env.EXPERIMENT_FLAGS)。
添加绑定后,运行 npx wrangler types 生成 TypeScript 类型。这会创建 Env 接口,其中每个绑定的类型为 Flagship。
interface Env {
FLAGS: Flagship;
EXPERIMENT_FLAGS: Flagship;
}调用 env.FLAGS 上的评估方法以在运行时解析标志值。每个方法都接受一个标志键、一个默认值和一个可选的评估上下文。
export default {
async fetch(request, env) {
const isEnabled = await env.FLAGS.getBooleanValue("my-feature", false, {
userId: "user-42",
});
return new Response(isEnabled ? "Feature is on" : "Feature is off");
},
};export default {
async fetch(request: Request, env: Env): Promise<Response> {
const isEnabled = await env.FLAGS.getBooleanValue("my-feature", false, {
userId: "user-42",
});
return new Response(isEnabled ? "Feature is on" : "Feature is off");
},
};有关方法的完整列表,请参阅绑定 API 参考。
本地开发期间,Flagship 绑定默认使用本地 Flag 存储。此设置适用于 wrangler dev、Cloudflare Vite 插件、Vitest 集成和 cf dev。存储初始为空,因此在添加 Flag 前,评估会返回你在调用处传入的默认值。
这是 Wrangler v4.135.0 及更高版本,以及 @cloudflare/vite-plugin v1.56.0 及更高版本中的默认行为。
如需将远程应用中的 Flag 复制到本地存储:
npx wrangler flagship flags pull <APP_ID>pull 还会植入百分比发布分桶所用的账户标签,使本地分桶与远程应用一致。仅存在于本地存储中的 Flag 会保留。
Flag 不会自动拉取,因此 wrangler dev 可以离线运行,也不会覆盖你在本地修改的 Flag。
pull 会写入 .wrangler/state 中的默认本地存储。如果开发服务器将数据保存在其他目录,请传入 --persist-to <DIRECTORY>,使 pull 写入相同位置。例如,Cloudflare Vite 插件 2.0 beta 会将数据保存在 .cloudflare/state:
npx wrangler flagship flags pull <APP_ID> --persist-to .cloudflare/state如需在不影响远程应用的情况下创建或更改 Flag,请在 Flag 命令中传入 --local:
npx wrangler flagship flags create <APP_ID> new-checkout --local
npx wrangler flagship flags list <APP_ID> --localFlag 命令仍默认针对远程应用。不能同时传入 --local 和 --remote。
你也可以在 Local Explorer中检查和编辑本地存储。Wrangler v4.148.0 及更高版本和 @cloudflare/vite-plugin v1.63.0 及更高版本中的 Local Explorer 会显示 Flagship 应用。
如需在本地开发期间针对远程应用进行评估,请在绑定上将 remote 设为 true:
{
"flagship": [
{
"binding": "FLAGS",
"app_id": "<APP_ID>",
"remote": true,
},
],
}[[flagship]]
binding = "FLAGS"
app_id = "<APP_ID>"
remote = truecf dev与 wrangler dev 一样使用本地 Flag 存储。
如需使用 cf 管理本地 Flag,请在受支持的 cf flagship 命令中添加 --local。无需启动开发服务器,也无需将应用绑定到 Worker。
cf flagship apps flags list --app-id <APP_ID> --local
cf flagship apps flags get <FLAG_KEY> --app-id <APP_ID> --local以下命令支持 --local:
cf flagship apps listcf flagship apps flags list、get、create、update、patch、delete和evaluatecf flagship apps evaluate get
其他 cf flagship 命令(例如 cf flagship apps get、cf flagship apps definitions get 和 cf flagship apps flags changelog)会报错:This command has no local equivalent. 若要使用远程应用,请在运行这些命令时省略 --local。
默认情况下,cf 会将本地数据保存在自己的目录中,而 wrangler dev 和 Cloudflare Vite 插件不会读取该目录。若要使用与开发服务器相同的 Flag,请传入其数据目录:wrangler dev 和 Cloudflare Vite 插件 1.x 使用 .wrangler/state,Vite 插件 2.0 beta 使用 .cloudflare/state:
cf flagship apps flags list --app-id <APP_ID> --local --persist-to .wrangler/statecf 无法从远程应用复制 Flag。请改用 npx wrangler flagship flags pull <APP_ID>;如果指定过 --persist-to,也请传入相同的值。