跳转到内容
本站为社区维护的非官方中文翻译,与 Cloudflare, Inc. 无关联。本站不提供账户登录,请勿在任何非官方站点输入您的 Cloudflare 账户信息。官方文档:developers.cloudflare.com

配置

最后更新 查看 MarkdownAgent 设置

要在 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

如需将远程应用中的 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> --local

Flag 命令仍默认针对远程应用。不能同时传入 --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 = true

使用 cf CLI

cf 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 list
  • cf flagship apps flags list、get、create、update、patch、delete 和 evaluate
  • cf 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/state

cf 无法从远程应用复制 Flag。请改用 npx wrangler flagship flags pull <APP_ID>;如果指定过 --persist-to,也请传入相同的值。

这篇文档对您有帮助吗?