快速入门

运行以下命令创建名为 kv-tutorial 的新项目：

npm create cloudflare@latest -- kv-tutorial

yarn create cloudflare kv-tutorial

pnpm create cloudflare@latest kv-tutorial

进行设置时，请选择以下选项：

• 对于 What would you like to start with?，选择 Hello World example。
• 对于 Which template would you like to use?，选择 Worker only。
• 对于 Which language do you want to use?，选择 TypeScript。
• 对于 Do you want to use git for version control?，选择 Yes。
• 对于 Do you want to deploy your application?，选择 No（部署前我们还会做一些修改）。

这将创建新的 kv-tutorial 目录，如下所示。

新的 kv-tutorial 目录包括：

• index.ts 中的 "Hello World" Worker。
• wrangler.jsonc 配置文件。wrangler.jsonc 是 kv-tutorial Worker 访问 kv 数据库的方式。

进入你刚为 Worker 项目创建的目录：

cd kv-tutorial

在 Cloudflare 仪表板中，前往 Workers & Pages 页面。

选择 Create application（创建应用程序）。

选择 Start with Hello World!（从 Hello World 开始！） > Get started（开始使用）。

命名 Worker。在本教程中，将 Worker 命名为 kv-tutorial。

选择 Deploy（部署）。

打开终端并运行以下命令：

npx wrangler kv namespace create <BINDING_NAME>

npx wrangler kv namespace create <BINDING_NAME> 子命令将新的绑定（binding）名称作为参数。KV 命名空间使用 Worker 名称（来自 Wrangler 文件）和你提供的绑定（binding）名称的拼接创建。<BINDING_ID> 会为你随机生成。

在本教程中，使用绑定（binding）名称 USERS_NOTIFICATION_CONFIG。

npx wrangler kv namespace create USERS_NOTIFICATION_CONFIG

🌀 Creating namespace with title "USERS_NOTIFICATION_CONFIG"
✨ Success!
Add the following to your configuration file in your kv_namespaces array:
{
	"kv_namespaces": [
		{
			"binding": "USERS_NOTIFICATION_CONFIG",
			"id": "<BINDING_ID>"
		}
	]
}

在 Cloudflare 仪表板中，前往 Workers KV 页面。

选择 Create instance（创建实例）。

输入命名空间名称。在本教程中，使用 kv_tutorial_namespace。

选择 Create（创建）。

在 Wrangler 文件中，添加以下内容，使用终端中从步骤 2 生成的值：

{
	"kv_namespaces": [
		{
			"binding": "USERS_NOTIFICATION_CONFIG",
			"id": "<BINDING_ID>"
		}
	]
}

[[kv_namespaces]]
binding = "USERS_NOTIFICATION_CONFIG"
id = "<BINDING_ID>"

绑定（binding）名称不需要与你创建的命名空间对应。绑定（binding）名称只是引用。具体来说：

• 你为 binding 设置的值（字符串）用于在 Worker 中引用此 KV 命名空间。在本教程中，应为 USERS_NOTIFICATION_CONFIG。
• 绑定（binding）必须是有效的 JavaScript 变量名 ↗。例如，binding = "MY_KV" 或 binding = "routingConfig" 都是有效的绑定（binding）名称。
• 绑定（binding）在 Worker 内的 env.<BINDING_NAME> 处可用。在本教程中，绑定（binding）在 env.USERS_NOTIFICATION_CONFIG 处可用。

在 Cloudflare 仪表板中，前往 Workers & Pages 页面。

选择你在步骤 1 中创建的 kv-tutorial Worker。

前往 Bindings（绑定） 选项卡，然后选择 Add binding（添加绑定）。

选择 KV namespace（KV 命名空间） > Add binding（添加绑定）。

在 Variable name（变量名称） 中命名绑定（binding）（BINDING_NAME），然后从下拉菜单中选择你在步骤 2 中创建的 KV 命名空间（kv_tutorial_namespace）。

选择 Add binding（添加绑定） 以部署绑定（binding）。

在终端中运行 wrangler kv key put 子命令，分别输入键和值。<KEY> 和 <VALUE> 是你选择的值。

npx wrangler kv key put --binding=<BINDING_NAME> "<KEY>" "<VALUE>"

在本教程中，你将向步骤 2 中创建的 KV 命名空间添加键 user_1，值为 enabled。

npx wrangler kv key put --binding=USERS_NOTIFICATION_CONFIG "user_1" "enabled"

Writing the value "enabled" to key "user_1" on namespace <BINDING_ID>.

在 Cloudflare 仪表板中，前往 Workers KV 页面。

选择你创建的 KV 命名空间（kv_tutorial_namespace）。

前往 KV Pairs（KV 键值对） 选项卡。

输入你选择的 <KEY>。

输入你选择的 <VALUE>。

选择 Add entry（添加条目）。

在终端中运行 wrangler kv key get 子命令，并输入键值：

npx wrangler kv key get --binding=<BINDING_NAME> "<KEY>"

在本教程中，你将从步骤 2 中创建的 KV 命名空间获取键 user_1 的值。

npx wrangler kv key get --binding=USERS_NOTIFICATION_CONFIG "user_1" --text

与 put 命令类似，get 命令也可以通过两种方式访问 KV 命名空间——使用 --binding 或 --namespace-id：

在 Cloudflare 仪表板中，前往 Workers KV 页面。

前往你创建的 KV 命名空间（kv_tutorial_namespace）。

前往 KV Pairs（KV 键值对） 选项卡。

在 Worker 脚本中，在 Env 接口中添加 KV 绑定（binding）。如果你使用 JavaScript 引导项目，则不需要此步骤。

interface Env {
	USERS_NOTIFICATION_CONFIG: KVNamespace;
	// ... other binding types
}

在 USERS_NOTIFICATION_CONFIG 上使用 put() 方法创建新的键值对。你将向 KV 命名空间添加新键 user_2，值为 disabled。

let value = await env.USERS_NOTIFICATION_CONFIG.put("user_2", "disabled");

使用 KV get() 方法获取存储在 KV 命名空间中的数据。你将从 KV 命名空间获取键 user_2 的值。

let value = await env.USERS_NOTIFICATION_CONFIG.get("user_2");

在 Cloudflare 仪表板中，前往 Workers & Pages 页面。

前往你创建的 kv-tutorial Worker。

选择 Edit Code（编辑代码）。

清除 workers.js 文件的内容，然后粘贴以下代码。

export default {
	async fetch(request, env, ctx) {
		try {
			await env.USERS_NOTIFICATION_CONFIG.put("user_2", "disabled");
			const value = await env.USERS_NOTIFICATION_CONFIG.get("user_2");
			if (value === null) {
				return new Response("Value not found", { status: 404 });
			}
			return new Response(value);
		} catch (err) {
			console.error(`KV returned error:`, err);
			const errorMessage =
				err instanceof Error
					? err.message
					: "An unknown error occurred when accessing KV storage";
			return new Response(errorMessage, {
				status: 500,
				headers: { "Content-Type": "text/plain" },
			});
		}
	},
};

export interface Env {
  USERS_NOTIFICATION_CONFIG: KVNamespace;
}

export default {
  async fetch(request, env, ctx): Promise<Response> {
    try {
      await env.USERS_NOTIFICATION_CONFIG.put("user_2", "disabled");
      const value = await env.USERS_NOTIFICATION_CONFIG.get("user_2");
      if (value === null) {
        return new Response("Value not found", { status: 404 });
      }
      return new Response(value);
    } catch (err) {
      console.error(`KV returned error:`, err);
      const errorMessage =
        err instanceof Error
          ? err.message
          : "An unknown error occurred when accessing KV storage";
      return new Response(errorMessage, {
        status: 500,
        headers: { "Content-Type": "text/plain" },
      });
    }
  },
} satisfies ExportedHandler<Env>;

上述代码：

1. 使用 KV 的 put() 方法向 BINDING_NAME 写入键。
2. 使用 KV 的 get() 方法读取同一键，如果键为 null（或键未设置或不存在）则返回错误。
3. 使用 JavaScript 的 try...catch ↗ 异常处理捕获潜在错误。从任何服务（如 Workers KV 或使用 fetch() 的外部 API）写入或读取时，你应预期显式处理异常。

浏览器应简单地返回与你在 get() 方法中指定的 KEY 对应的 VALUE。

选择 Deploy（部署） 旁边的下拉箭头并选择 Save（保存）。

运行以下命令将 KV 部署到 Cloudflare 全球网络：

npm run deploy

访问新创建的 Workers KV 应用的 URL。

例如，如果你的新 Worker URL 是 kv-tutorial.<YOUR_SUBDOMAIN>.workers.dev，访问 https://kv-tutorial.<YOUR_SUBDOMAIN>.workers.dev/ 会向 Worker 发送请求，该请求写入（并读取）Workers KV。

在 Cloudflare 仪表板中，前往 Workers & Pages 页面。

选择你的 kv-tutorial Worker。

选择 Deployments（部署）。

从 Version History（版本历史） 表中选择 Deploy version（部署版本）。

从 Deploy version（部署版本） 页面选择 Deploy（部署）。

这会将 Worker 代码的最新版本部署到生产环境。