简介
功能开关是一项设置，可以在不修改应用代码的情况下启用或关闭某个功能。假设你正在准备一个新的公告横幅：你希望先在练习环境中试用，同时保持公开版本关闭。Workers KV 会将小型值存储在称为键的名称下。Worker 需要决定返回什么响应时，可以读取 banner:new 这样的键。这适合读取频繁、修改偶尔发生的设置。
开始本课程前，请先完成 将 LabEx 连接到你的 Cloudflare 账户。 该实验会介绍 LabEx VM 终端、设备授权、账户确认以及 account_id。如果你是直接进入本课程的，请先完成那个实验。你还应该了解如何编写简单的 JavaScript Worker，以及如何在 Workers 初学者课程中使用 Wrangler 部署 Worker。Worker 可以在 Cloudflare 上运行请求处理代码，无需你维护服务器。
在本实验中，你将创建一个命名空间。命名空间是一个具有名称的容器，用于将一组键与其他键分开。你会通过绑定将它连接到 Worker。绑定是代码访问该资源时使用的配置名称。你将练习本地和云端操作，发布一个只读的公告横幅端点，并删除本实验创建的临时资源。
使用你自己的学习账户。这个全新的 VM 需要使用具有 Workers 和 KV 权限的账户登录。本练习只使用一个 Worker、一个命名空间，以及 KV 免费额度 内的少量模拟值；完成本练习不需要购买域名或升级付费套餐。账户已有的使用量仍会计入其额度。公开端点不包含任何私密信息。
初始化过程会在 /home/labex/project/feature-flags 中安装 Node.js 22.22.0 和项目本地的 Wrangler 4.131.1。它会固定直接依赖的版本并运行 npm install；你不需要再次安装这些工具。在完成云端删除和注销检查前，请保持 VM 处于打开状态。
连接专用功能开关命名空间
在本步骤中，你将为本实验设置独立的资源名称，并将一个云端命名空间连接到项目。使用独立命名空间可以避免练习用的键与现有应用中的键混在一起。
进入已准备好的项目目录：
cd /home/labex/project/feature-flags
生成一次唯一名称。openssl rand -hex 6 会输出随机后缀；$(...) 会将该后缀插入名称。Shell 变量会在当前终端中保存这个名称，供后续命令使用。
WORKER_NAME="labex-flags-$(openssl rand -hex 6)"
printf '%s\n' "$WORKER_NAME"
为此 VM 授权。除了读取账户身份之外，Workers Scripts Write 权限允许部署和删除 Worker，Workers KV Write 权限允许管理本实验的命名空间和键。
npx wrangler login --device --browser=false --scopes account:read user:read workers_scripts:write workers_kv:write
在浏览器中打开显示的设备链接，输入当前验证码，查看请求的权限和学习账户，然后授权 Wrangler。授权页面上还可能显示后台访问权限。返回终端并等待登录完成。
在授权页面展开 Developer Platform，将请求的权限与下面的示例进行比较。本实验需要这两个写入权限；它们用于管理资源，而不只是读取功能开关。
npx wrangler whoami --json
确认结构化结果中包含 loggedIn: true，以及学习账户的 name，即使列表中只显示一个账户也要确认。复制该账户的 id。在运行下面的命令前，将配置中的 YOUR_ACCOUNT_ID 替换为这个值。这里的 cat heredoc 会将两个 JSON 行之间的全部内容写入文件；> 会替换文件内容。未加引号的分隔符允许 Shell 插入 $WORKER_NAME。
cat > wrangler.jsonc <<JSON
{
"name": "$WORKER_NAME",
"main": "src/index.js",
"compatibility_date": "2026-07-30",
"account_id": "YOUR_ACCOUNT_ID",
"workers_dev": true
}
JSON
在该账户中创建命名空间。命名空间标题使用与 Worker 相同的唯一名称，因此稍后可以识别这两个资源。--update-config=false 会让绑定编辑保持可见，而不是自动修改文件。
npx wrangler kv namespace create "$WORKER_NAME-flags" --update-config=false
输出中会包含新命名空间的 ID。复制这个 ID，然后在下面的完整配置中替换 YOUR_ACCOUNT_ID 和 YOUR_NAMESPACE_ID。FLAGS 是供代码使用的绑定名称；ID 则标识真实的 Cloudflare 资源。
cat > wrangler.jsonc <<JSON
{
"name": "$WORKER_NAME",
"main": "src/index.js",
"compatibility_date": "2026-07-30",
"account_id": "YOUR_ACCOUNT_ID",
"workers_dev": true,
"kv_namespaces": [
{ "binding": "FLAGS", "id": "YOUR_NAMESPACE_ID" }
]
}
JSON
npx wrangler kv namespace list
找到本实验的命名空间标题，并将其 ID 与配置文件中的 ID 进行比较。列表中可以包含其他命名空间；不要修改它们。此配置记录后续命令应使用的账户和资源。绑定是对命名空间的引用，不是命名空间数据的副本。
分离本地和远程功能开关
在本步骤中，你将在同一个键下存储不同的值，并验证本地修改不会影响云端数据。本地是指存储在此 LabEx VM 中的数据。远程是指你 Cloudflare 账户中的命名空间。Wrangler 使用绑定确定存储位置；显式的 --local 或 --remote 选项决定操作发生在哪里。
先保持公开功能关闭：
npx wrangler kv key put banner:new disabled --binding FLAGS --remote
在 VM 的本地存储中启用同一个功能：
npx wrangler kv key put banner:new enabled --binding FLAGS --local
读取两个值。put 用于写入键，get 用于读取键的值。banner:new 中的冒号是一种用于归类相关键的命名约定；它不会创建目录。
使用 --text 将存储的值解码为 UTF-8 文本，并在单独一行显示。
npx wrangler kv key get banner:new --binding FLAGS --local --text
预期结果为 enabled。
npx wrangler kv key get banner:new --binding FLAGS --remote --text
预期结果为 disabled。如果你误改了远程值，请使用 disabled 再次运行对应的 put 命令，然后重新读取。不要仅根据项目目录来判断操作目标。
现在练习删除已废弃的功能开关。下面的命令只会影响绑定为 FLAGS 的临时远程命名空间。
npx wrangler kv key put banner:old retired --binding FLAGS --remote
npx wrangler kv key list --binding FLAGS --remote
列表显示的是 banner:new 和 banner:old 这样的名称，而不是它们存储的值。需要读取值时，请使用 get。
npx wrangler kv key delete banner:old --binding FLAGS --remote
npx wrangler kv key list --binding FLAGS --remote
npx wrangler kv key list --binding FLAGS --local
现在两个列表都应该只包含 banner:new。如果需要确认两个值仍然不同，请再次读取它们。删除一个键只会移除一条记录；稍后删除命名空间则会移除整个容器。
KV 具有最终一致性：修改可能需要一段时间，才会在其他位置的读取操作中可见。Worker 可能会暂时读取到旧值，包括之前不存在的键。不要反复覆盖值来强制它显示出来。这些无害的显示类功能开关可以容忍这种延迟，但不适合用于需要立即撤销访问权限的决策。你将在后续实验中进一步了解这种行为。有关存储模型，请参阅 KV 的工作原理。
从本地 Worker 读取功能开关
在本步骤中，你将让应用行为依赖已存储的设置。Worker 会读取 env.FLAGS，其中 env 包含已配置的资源绑定。get() 是异步操作，因此 await 会等待它返回值，然后你才能决定返回什么内容。
编写处理程序。加引号的 JS 分隔符会原样保留 JavaScript，不会进行 Shell 变量展开。
cat > src/index.js <<'JS'
export default {
async fetch(request, env) {
if (new URL(request.url).pathname !== "/banner") {
return new Response("Not found", { status: 404 });
}
const value = await env.FLAGS.get("banner:new");
return Response.json({
feature: "new-banner",
enabled: value === "enabled"
});
}
};
JS
读取不存在的键时会返回 null。只与 "enabled" 进行比较，意味着缺少值或值异常时，这个可选公告横幅都会保持关闭。这是一个简单的安全默认值：没有提供设置时，应用仍然可以使用。它不会隐藏连接失败，因为连接失败与键不存在是两种不同的情况。
启动本地开发服务。--local 会在此 VM 中使用本地绑定运行 Worker。> local.log 2>&1 会将输出和错误写入日志；& 允许终端继续接受其他命令。$! 是后台进程 ID，这里将其保存下来，以便稍后停止该进程。
npx wrangler dev --local --ip 0.0.0.0 --port 8080 > local.log 2>&1 &
DEV_PID=$!
cat local.log
等待日志显示端口 8080 已准备就绪。如果服务仍在启动，请再次读取日志，确认启动完成后再继续。
curl -i http://127.0.0.1:8080/banner
curl -i 会显示响应头和响应正文。预期状态为 HTTP 200，内容类型为 JSON，并包含：
{"feature":"new-banner","enabled":true}
true 来自本地 KV 存储。启动开发服务器不会将远程的 disabled 值复制到 VM 中。保持服务器运行，以便进行下一步比较。
部署并比较公开响应
在本步骤中，你将发布相同的代码，并确认它读取的是云端命名空间。部署会上传 Worker 及其绑定配置，但不会上传本地 KV 条目。
npx wrangler deploy
阅读部署输出。确认其中包含 Worker 名称、FLAGS 绑定以及公开的 workers.dev 地址。将实际地址保存到下面的变量中，并在运行命令前替换示例地址。使用 Shell 变量可以避免重复输入较长的 URL。
WORKER_URL="https://YOUR_WORKER.YOUR_SUBDOMAIN.workers.dev"
curl -i "$WORKER_URL/banner"
预期状态为 HTTP 200，并包含：
{"feature":"new-banner","enabled":false}
云端设置为 disabled，因此公开响应中的 enabled 值为 false。如果新主机名暂时无法访问，请稍等片刻后重试。如果响应反映的是旧值，请先确认远程键的值，然后等待 KV 数据可见，不要快速反复改写。网络错误不能证明测试成功。
curl -i http://127.0.0.1:8080/banner
本地响应仍然应为 true。现在你有一个处理程序和两个相互分离的数据存储：本地开发读取 VM 中的数据，而已部署的 Worker 读取绑定所标识的命名空间。
在 Cloudflare Dashboard 中选择相同的学习账户，然后打开 Storage & databases → Workers KV。找到名称与本实验匹配的命名空间，并查看其中的键。确认其中只剩下 banner:new，且远程值为 disabled。接着打开 Workers & Pages，选择本实验的 Worker，并查看其 Bindings 页面。将其中的 FLAGS 绑定与刚才查看的命名空间进行比较。这些只是只读检查点；实际修改仍在终端中完成。
命名空间默认打开 Metrics 页面。选择 KV Pairs 查看实际条目；使用量统计可能晚于写入更新。如果 Workers & Pages 中暂时看不到新 Worker，请点击 Refresh。在 Bindings 中向下滚动到表格，对照绑定名称与命名空间。
你生成的名称、命名空间 ID 和公开子域名会与示例不同。在 Dashboard 中看到命名空间，可以确认它所在的位置；成功的 HTTP 响应则可以确认应用能够使用它。
删除临时云资源
在本步骤中，你将在 Wrangler 仍处于授权状态时删除两个资源。命名空间的生命周期可能长于 Worker，因此仅删除应用不会清理其中的数据。
停止在此终端中启动的本地开发进程：
kill "$DEV_PID"
删除任何资源前，先检查保存的资源引用：
cat wrangler.jsonc
确认其中的 labex-flags-... Worker 名称和 FLAGS 命名空间 ID。删除此配置所选中的 Worker：
npx wrangler delete
如果命令提示确认，请检查显示的名称是否与本实验匹配，并输入 y 确认。然后只删除 FLAGS 所引用的命名空间：
npx wrangler kv namespace delete --binding FLAGS
接受确认前，请在提示信息中检查命名空间。保留 wrangler.jsonc 不变，以便独立检查能够识别应该已经不存在的资源。
npx wrangler kv namespace list
本实验的命名空间应该已经不在列表中；无关的命名空间应当保留。刷新 Dashboard 中的列表，确认本实验的 Worker 和命名空间已经消失。请求失败或登录过期都不能证明删除成功。请在注销前运行本步骤的检查，以便它能够检查当前已授权账户中的资源清单。
结束 VM 授权
在本步骤中，你将在清理检查通过后断开 Wrangler 的授权。注销会结束此 VM 中保存的 Wrangler 授权；它不会删除云端资源，也不会将你从普通的 Dashboard 浏览器会话中注销。
npx wrangler logout
npx wrangler whoami --json
确认结构化结果报告 "loggedIn": false。此时未认证的命令可能以非零退出状态结束，这是预期行为。如果只出现连接错误，而没有明确的认证状态，请在连接恢复后重试。
剩余的本地文件和本地 KV 状态属于这个临时 VM，与之前删除的云端资源相互独立。现在可以结束本实验。
总结
你创建了一个隔离的 KV 命名空间，通过绑定将其连接到 Worker，并使用明确的本地和远程命令写入、读取、列出和删除键。你的 Worker 从两个独立的存储中读取同一个键：本地公告横幅已启用，而公开公告横幅仍处于关闭状态。你还为缺少功能开关的情况设置了安全默认值，并了解了为什么不能将 KV 更新视为立即生效的全局开关。
最后，你验证了公开响应，在保持授权的情况下删除了 Worker 和命名空间，并注销了 Wrangler。接下来，你将使用结构化 JSON 值来提供非敏感的账户偏好设置。
