Bindings - OpenNext 中文文档

绑定

绑定 (opens in a new tab) 允许您的 Worker 与 Cloudflare 开发者平台上的资源进行交互。当您在 Worker 上声明绑定时，您就授予了它特定的能力，例如能够读取和写入文件到 R2 (opens in a new tab) 存储桶。

如何配置您的 Next.js 应用以便访问绑定

安装 @opennextjs/cloudflare (opens in a new tab)，然后在您的 Next.js 应用的根目录中添加一个 wrangler 配置文件 (opens in a new tab)，如入门指南中所述。

如何在您的 Next.js 应用中访问绑定

您可以通过 getCloudflareContext 从 Next.js 应用的任何路由访问绑定 (opens in a new tab)：

import { getCloudflareContext } from "@opennextjs/cloudflare";
 
export async function GET(request) {
  const myKv = getCloudflareContext().env.MY_KV_NAMESPACE;
  await myKv.put("foo", "bar");
  const foo = await myKv.get("foo");
 
  return new Response(foo);
}

getCloudflareContext 仅在“异步模式”下的 SSG 路由中可用（使其返回一个 promise），要以这种方式运行函数，只需提供一个选项参数并将 async 设置为 true：

const context = await getCloudflareContext({ async: true });

警告：在 SSG 期间建议谨慎操作，因为密钥（存储在 .dev.vars 文件中）和来自绑定的本地开发值（如保存在本地 KV 中的值）将用于页面的静态生成。

如何向您的 Worker 添加绑定

通过将绑定添加到您的 wrangler 配置文件 (opens in a new tab) 来向您的 Worker 添加绑定。

绑定的 TypeScript 类型声明

为了确保上述 getCloudflareContext().env 中的 env 对象具有准确的 TypeScript 类型，请运行以下 Wrangler 命令来生成与您的 Worker 配置匹配的类型 (opens in a new tab)：

npx wrangler types --env-interface CloudflareEnv

这将生成一个 d.ts 文件并将其保存为 worker-configuration.d.ts。

为了确保您的类型始终是最新的，请在配置文件发生任何更改后运行 wrangler types --env-interface CloudflareEnv。

绑定的本地访问

如入门指南中所示，您的应用既可以进行开发（next dev）也可以本地预览，在这两种情况下，绑定都可以从您的应用代码中访问。

此类绑定默认是本地模拟，模拟实际 Cloudflare 资源的行为。

远程绑定

如上所述，默认使用的是绑定的本地模拟。

然而，也可以使用远程绑定 (opens in a new tab)，允许您的应用代码在本地运行的同时，连接到与您的 Cloudflare 账户关联的远程资源。

您要做的就是在任何绑定的配置字段中将 remote 设置为 true，正如远程绑定文档 (opens in a new tab) 中所述。

远程绑定 API 已在 wrangler 4.36.0 中稳定，因此如果您使用的是更早版本的 wrangler 为了使用远程绑定，您需要在 next.config.ts 文件中启用它：

- initOpenNextCloudflareForDev();
+ initOpenNextCloudflareForDev({
+  experimental: { remoteBindings: true }
+ });

并且您需要设置 experimental_remote，而不是将 remote 设置为绑定配置选项。

请注意，远程绑定也会在构建期间使用，例如在使用 ISR (opens in a new tab) 等功能时这非常有用，以便读取的生产数据可用于网站的静态生成

其他 Cloudflare API（`cf`, `ctx`）

您可以从 cf 对象 (opens in a new tab) 访问有关传入请求的上下文，以及从 ctx 对象 (opens in a new tab) 访问生命周期方法，这些都来自 getCloudflareContext() (opens in a new tab) 的返回值：

import { getCloudflareContext } from "@opennextjs/cloudflare";
 
export async function GET(request) {
  const { env, cf, ctx } = getCloudflareContext();
 
  // ...
}

绑定