Cloudflare 中文文档
Pages
Cloudflare 中文文档
Pages
编辑这个页面
跳转官方原文档
Set theme to dark (⇧+D)
  1. Products
  2. Pages
  3. Functions
  4. Bindings

绑定

绑定 使你的Pages Functions 能够与 Cloudflare 开发人员平台上的资源交互。使用绑定将你的 Pages 函数与 Cloudflare 资源(如 KV、Durable Objects、R2 和 D1)集成。你可以为生产环境和预览环境设置绑定。

本指南将指导你为页面功能配置绑定。你必须已经设置了 Cloudflare 开发者平台资源才能继续。

​​ KV 命名空间

Workers KV 是 Cloudflare 的键值存储解决方案。

要将 KV 命名空间绑定到 Pages 函数，你可以在 wrangler.toml或 Cloudflare 面板中配置 KV 命名空间绑定。

通过 Cloudflare 面板配置 KV 命名空间绑定：

  1. 登录 Cloudflare 仪表板 并选择你的账户。
  2. 在账户主页，选择工作者和页面。
  3. 选择页面项目 > 设置> 功能> KV命名空间绑定> 添加绑定。
  4. 选择是在生产环境还是预览环境中设置装订。
  5. 在变量名下为绑定命名。
  6. 在KV 命名空间下，选择所需的命名空间。对于 生产和 预览环境，必须重复步骤 5 和 6。
  7. 重新部署项目，使绑定生效。

下面是一个如何在函数中使用 KV 的示例。在下面的示例中，KV 命名空间绑定名为 TODO_LIST，你可以在 context.env 中访问 Function 代码中的绑定：

​​ 在本地与 KV 命名空间交互

你可以通过两种方式之一在本地与 KV 命名空间绑定交互：

  • 配置 Pages 项目的 wrangler.toml 文件并运行 npx wrangler pages dev.
  • 直接向 wrangler pages dev 传递参数。

要通过向 Wrangler CLI 传递参数与本地的 KV 命名空间绑定进行交互，请在 wrangler pages dev 命令中添加 -k <BINDING_NAME> 或 --kv=<BINDING_NAME> 。例如，如果你的 KV 命名空间通过 TODO_LIST 绑定与你的 Function 绑定，则在本地开发中通过运行以下命令访问 KV 命名空间：

​​ Durable Objects

耐用对象 (DO) 是 Cloudflare 的强一致性数据存储，可支持连接 WebSockets 和处理状态等功能。

You must create a Durable Object Worker and bind it to your Pages project using the Cloudflare dashboard or your Pages project’s wrangler.toml. You cannot create and deploy a Durable Object within a Pages project.

要将耐用对象绑定到页面功能，你可以在 wrangler.toml或 Cloudflare 面板中配置耐用对象绑定。

通过 Cloudflare 面板配置持久对象绑定：

  1. 登录 Cloudflare 仪表板 并选择你的账户。
  2. 在账户主页，选择工作者和页面。
  3. 选择页面项目 > 设置> 功能> 持久对象绑定> 添加绑定。
  4. 选择是在生产环境还是预览环境中设置装订。
  5. 在变量名下为绑定命名。
  6. 在耐用对象命名空间下，选择所需的命名空间。对于 生产和 预览环境，必须重复步骤 5 和 6。
  7. 重新部署项目，使绑定生效。

下面是一个如何在函数中使用持久对象的示例。在下面的示例中，你的 DO 绑定名为 DURABLE_OBJECT，你可以在函数代码的 context.env 中访问该绑定：

​​ 在本地与耐用对象命名空间交互

你可以通过两种方式之一与本地的持久对象绑定进行交互：

  • 配置 Pages 项目的 wrangler.toml 文件并运行 npx wrangler pages dev.
  • 直接向 wrangler pages dev 传递参数。

在本地开发时，要与持久对象命名空间交互，请在导出持久对象的 Worker 目录中运行 wrangler dev。在另一个终端，在 Pages 项目目录下运行 wrangler pages dev。

要通过 Wrangler CLI 在本地与耐用对象命名空间交互，请在 wrangler pages dev 中添加 --do <BINDING_NAME>=<CLASS_NAME>@<SCRIPT_NAME> 。CLASS_NAME 表示 Durable Object 的类名，SRIPT_NAME 表示 Worker 的名称。

例如，如果你的 Worker 名为 do-worker，并且声明了一个名为 DurableObjectExample 的持久对象类，那么在 do-worker 目录中运行 npx wrangler dev 即可访问该持久对象。同时，在 Pages 的项目目录中运行 npx wrangler pages dev <OUTPUT_DIR> --do MY_DO=DurableObjectExample@do-worker 。使用 context.env(例如，context.env.MY_DO)与功能代码中的 MY_DO 绑定进行交互。

​​ R2 桶

R2 是 Cloudflare 的 blob 存储解决方案，允许开发人员存储大量非结构化数据，而无需支付出口费用。

要将 R2 桶绑定到 Pages 功能，你可以在 wrangler.toml或 Cloudflare 面板中配置 R2 桶绑定。

要通过 Cloudflare 面板配置 R2 数据桶绑定，请执行以下操作

  1. 登录 Cloudflare 仪表板 并选择你的账户。
  2. 在账户主页，选择工作者和页面。
  3. 选择页面项目 > 设置> 功能> R2桶绑定> 添加绑定。
  4. 选择是在生产环境还是预览环境中设置装订。
  5. 在变量名下为绑定命名。
  6. 在 R2存储桶下，选择所需的 R2 存储桶。对于 生产和 预览环境，必须重复步骤 5 和 6。
  7. 重新部署项目，使绑定生效。

下面是一个如何在函数中使用 R2 存储桶的示例。在下面的示例中，R2 数据桶绑定名为 BUCKET，你可以在 context.env 中访问函数代码中的绑定：

​​ 在本地与 R2 存储桶交互

你可以通过两种方式之一在本地与 R2 水桶绑定进行交互：

  • 配置 Pages 项目的 wrangler.toml 文件并运行 npx wrangler pages dev.
  • 直接向 wrangler pages dev 传递参数。

要通过 Wrangler CLI 在本地与 R2 数据桶交互，请在 wrangler pages dev 命令中添加 --r2=<BINDING_NAME>。如果你的 R2 源代码桶已通过 BUCKET 绑定与你的 Function 绑定，则可在本地开发中通过运行以下命令访问该 R2 存储桶：

使用 context.env(例如 context.env.BUCKET)与此绑定进行交互。

​​ D1 数据库

D1 是 Cloudflare 的本地无服务器数据库。

要将 D1 数据库绑定到你的页面功能，你可以在 wrangler.toml或 Cloudflare 面板中配置 D1 数据库绑定。

通过 Cloudflare 面板配置 D1 数据库绑定：

  1. 登录 Cloudflare 仪表板 并选择你的账户。
  2. 在账户主页，选择工作者和页面。
  3. 选择页面项目 > 设置> 功能> D1数据库绑定> 添加绑定。
  4. 选择是在生产环境还是预览环境中设置装订。
  5. 在变量名下为绑定命名。
  6. 在D1 数据库下，选择所需的 D1 数据库。对于 生产和 预览环境，必须重复步骤 5 和 6。
  7. 重新部署项目，使绑定生效。

下面是如何在函数中使用 D1 的示例。在下面的示例中，你的 D1 数据库绑定是 NORTHWIND_DB，你可以在 context.env 中访问 Function 代码中的绑定：

​​ 在本地与 D1 数据库交互

你可以通过两种方式之一在本地与 D1 数据库绑定交互：

  • 配置 Pages 项目的 wrangler.toml 文件并运行 npx wrangler pages dev.
  • 直接向 wrangler pages dev 传递参数。

要在本地开发时通过 Wrangler CLI 与 D1 数据库交互，请在 wrangler pages dev 命令中添加--d1 <BINDING_NAME>=<DATABASE_ID> 。

如果 D1 数据库通过 NORTHWIND_DB 绑定到了 Pages Function，且 wrangler.toml 文件中的 database_id 为 xxxx-xxxx-xxxx-xxxx-xxxx，则可在本地开发中通过运行 Wrangler.toml 访问该数据库：

通过使用 context.env(例如 context.env.NORTHWIND_DB)与此绑定进行交互。

有关 D1 绑定上可用的 API 方法，请参阅 D1 客户端 API 文档。

​​ 将索引矢量化

Vectorize 是 Cloudflare 的本地矢量数据库。

要将 Vectorize 索引绑定到页面功能，可在 wrangler.toml或 Cloudflare 面板中配置 Vectorize 索引绑定。

通过 Cloudflare 面板配置 Vectorize 索引绑定：

  1. 登录 Cloudflare 仪表板 并选择你的账户。
  2. 在账户主页，选择工作者和页面。
  3. 选择是在生产环境还是预览环境中设置绑定。
  4. 选择页面项目 > 设置> 功能> 矢量化索引绑定> 添加绑定。
  5. 在变量名下为绑定命名。
  6. 在矢量化索引下，选择所需的矢量化索引。你必须对 生产和 预览环境重复步骤 5 和 6。
  7. 重新部署项目，使绑定生效。

​​ 使用矢量化索引绑定

要在Pages Functions 中使用 Vectorize 索引，可以在Pages Functions 代码中访问 Vectorize 索引绑定。在下面的示例中，你的 Vectorize 索引绑定名为 VECTORIZE_INDEX，你可以在Pages Functions 代码中的 context.env 中访问该绑定。

​​ Works AI

Workers AI允许你在 Cloudflare 的全球网络上运行由无服务器 GPU 驱动的机器学习模型。

要将 Workers AI 绑定到你的页面功能，你可以在 wrangler.toml或 Cloudflare 面板中配置 Workers AI 绑定。

使用 Wrangler 进行本地开发时，可以使用 --ai 标志定义 AI 绑定。在开发模式下运行 wrangler pages dev --ai AI 启动 Wrangler，以公开 context.env.AI 绑定。

要通过 Cloudflare 控制面板配置 Workers AI 绑定：

  1. 登录 Cloudflare 仪表板 并选择你的账户。
  2. 在账户主页，选择工作者和页面。
  3. 选择页面项目 > 设置> 功能> 工作程序 AI 绑定> 添加绑定。
  4. 选择是在生产环境还是预览环境中设置装订。
  5. 在变量名下为绑定命名。
  6. 重新部署项目，使绑定生效。

​​ 使用Works AI绑定

要在页面功能中使用 Workers AI，你可以在页面功能代码中访问 Workers AI 绑定。在下面的示例中，Workers AI 绑定名为 AI，你可以在页面功能代码的 context.env 中访问该绑定。

​​ 在本地与你的Works AI绑定互动

你可以通过两种方式之一在本地与Works AI绑定进行交互：

  • 配置 Pages 项目的 wrangler.toml 文件并运行 npx wrangler pages dev.
  • 直接向 wrangler pages dev 传递参数。

要在本地开发时通过 Wrangler CLI 与 Workers AI 绑定交互，请运行

​​ 服务绑定

服务绑定 使你可以在Pages Function中调用 Worker。

要将你的页面功能绑定到 Worker，请使用 wrangler.toml 或 Cloudflare 面板在你的页面功能中配置服务绑定。

通过 Cloudflare 面板配置服务绑定：

  1. 登录 Cloudflare 仪表板 并选择你的账户。
  2. 在账户主页，选择工作者和页面。
  3. 选择页面项目 > 设置> 功能> 服务绑定> 添加绑定。
  4. 选择是在生产环境还是预览环境中设置装订。
  5. 在变量名下为绑定命名。
  6. 在服务下，选择所需Works。你必须对 生产和 预览环境重复步骤 5 和 6。
  7. 重新部署项目，使绑定生效。

下面是一个如何在函数中使用服务绑定的示例。在下面的示例中，服务绑定名为 SERVICE，你可以在 context.env 中访问函数代码中的绑定：

​​ 与本地服务绑定互动

你可以通过两种方式之一在本地与服务绑定交互：

  • 配置 Pages 项目的 wrangler.toml 文件并运行 npx wrangler pages dev.
  • 直接向 wrangler pages dev 传递参数。

要在本地开发时与服务绑定进行交互，请通过wrangler dev运行你要绑定的 Worker，同时运行wrangler pages dev，并在其中加入--service <BINDING_NAME>=<SRIPT_NAME>，其中SRIPT_NAME表示 Worker 的名称。例如，如果 Worker 的名称是 my-worker，则通过 npx wrangler dev(在 Worker 的目录下)与 npx wrangler pages dev <OUTPUT_DIR> --service MY_SERVICE=my-worker(在 Pages 的目录下)同时运行来连接该 Worker。使用 context.env(例如 context.env.MY_SERVICE)与此绑定交互。

如果通过 Cloudflare 控制面板设置服务绑定，则需要在wrangler pages dev 后添加--service <BINDING_NAME>=<SRIPT_NAME>，其中BINDING_NAME是服务绑定的名称，SRIPT_NAME是 Worker 的名称。

例如，要进行本地开发，如果 Worker 的名称是 my-worker，则在 my-worker 目录下运行 npx wrangler dev。在另一个终端，也在 Pages 项目目录下运行 npx wrangler pages dev <OUTPUT_DIR> --service MY_SERVICE=my-worker。使用 context.env(例如，context.env.MY_SERVICE)与此服务绑定交互。

​​ 队列生产者

队列生产者 使你能够在页面功能中将消息发送到队列中。

要将队列绑定到你的页面功能，请使用 wrangler.toml或 Cloudflare 面板在你的页面功能中配置队列生产者绑定：

通过 Cloudflare 面板配置队列生产者绑定：

  1. 登录 Cloudflare 仪表板 并选择你的账户。
  2. 在账户主页，选择工作者和页面。
  3. 选择你的 Pages 项目 > 设置> 功能> 队列生成器绑定> 添加绑定。
  4. 选择是在生产环境还是预览环境中设置装订。
  5. 在变量名下为绑定命名。
  6. 在数据集下，输入所需的数据集。对于 生产和 预览环境，你必须重复步骤 5 和 6。
  7. 重新部署项目，使绑定生效。

下面是一个如何在函数中使用队列生产者绑定的示例。在此示例中，绑定名为 MY_QUEUE，你可以在函数代码的 context.env: 中访问绑定：

​​ 在本地与队列生产者绑定互动

如果将队列生产者绑定到 Pages Function，就可以在本地向队列发送事件。但是，无法使用Pages Functions 从队列中消费事件。你必须创建一个单独的消费者 Worker和一个队列消费者处理程序，才能从队列中消费事件。Wrangler 尚不支持在本地分别运行绑定到同一队列的生产者函数和消费者 Worker。

​​ 分析引擎

分析引擎 绑定可让你在页面功能中编写分析。

要将分析引擎数据集绑定到你的页面功能，必须使用 wrangler.toml或 Cloudflare 面板配置分析引擎绑定：

通过 Cloudflare 面板配置分析引擎绑定：

  1. 登录 Cloudflare 仪表板 并选择你的账户。
  2. 在账户主页，选择工作者和页面。
  3. 选择页面项目 > 设置> 功能> 分析引擎绑定> 添加绑定。
  4. 选择是在生产环境还是预览环境中设置装订。
  5. 在变量名下为绑定命名。
  6. 在数据集下，输入所需的数据集。对于 生产和 预览环境，你必须重复步骤 5 和 6。
  7. 重新部署项目，使绑定生效。

下面是如何在函数中使用分析引擎绑定的示例。在下面的示例中，绑定名为 ANALYTICS_ENGINE，你可以在 context.env 中访问函数代码中的绑定：

​​ 在本地与分析引擎绑定互动

无法在本地使用分析引擎绑定。

​​ 环境变量

环境变量 是一个注入值，可由你的函数访问。环境变量是一种绑定类型，可将文本字符串或 JSON 值附加到 Pages 函数。它以纯文本形式存储。在运行时和构建时，直接在 Cloudflare 面板中为生产环境和预览环境设置环境变量。

要在 Pages 项目中添加环境变量，可使用 wrangler.toml或 Cloudflare 面板。

要通过 Cloudflare 面板配置环境变量：

  1. 登录 Cloudflare 仪表板 并选择你的账户。
  2. 在账户主页，选择工作者和页面。
  3. 选择页面项目 > 设置> 环境变量。
  4. 在制作和/或预览下选择添加变量。
  5. 设置变量名和变量值后，选择保存。

下面是一个如何在函数中使用环境变量的示例。本例中的环境变量是 ENVIRONMENT，你可以通过 context.env访问该环境变量：

​​ 与本地环境变量互动

你可以通过两种方式之一在本地与环境变量交互：

  • 配置 Pages 项目的 wrangler.toml 文件并运行 npx wrangler pages dev。
  • 直接向 wrangler pages dev 传递参数。

要通过 Wrangler CLI 在本地与环境变量交互，请在 wrangler pages dev 命令中添加 -binding=<ENVIRONMENT_VARIABLE_NAME>=<ENVIRONMENT_VARIABLE_VALUE>：

​​ Secrets

Secrets是一种绑定类型，允许你为Pages Functions 附加加密文本值。设置Secrets后，你将无法看到Secrets，只能在 context.env上以编程方式访问Secrets。Secrets用于存储敏感信息，如 API 密钥和授权令牌。

要在 Pages 项目中添加Secrets：

  1. 登录 Cloudflare 仪表板 并选择你的账户。
  2. 在账户主页，选择工作者和页面。
  3. 选择页面项目 > 选择 设置> 环境变量。
  4. 在制作和/或预览下选择添加变量。
  5. 选择加密，创建你的Secrets。
  6. 选择 保存。

Secrets的使用方法与环境变量相同。使用 Wrangler 或在 Cloudflare 面板中设置Secrets时，需要在使用这些Secrets的部署之前完成。有关更多指导，请参阅 环境变量。

​​ 在本地与你的Secrets互动

本地开发时，在 Pages 项目的根目录下创建一个 .dev.vars 文件来添加Secrets。然后将以下代码段添加到 .dev.vars：