Cloudflare

Cloudflare Workers

预设: cloudflare_module

以下是将 Nitro 应用部署到 Cloudflare Workers 的示例 nitro.config.ts 文件。

export default defineNitroConfig({
    compatibilityDate: "2024-09-19",
    preset: "cloudflare_module",
    cloudflare: {
      deployConfig: true,
      nodeCompat: true
    }
})

通过设置 deployConfig: true，Nitro 将自动为您生成一个正确配置的 wrangler.json。 如果您需要添加 Cloudflare Workers 配置，例如 bindings，您可以：

• 在您的 Nitro 配置中设置 cloudflare: { wrangler : {} }。这与 wrangler.json 的类型相同。
• 提供您自己的 wrangler.json。Nitro 将与适当的设置合并您的配置，包括指向构建输出。

本地预览

您可以使用 Wrangler 在本地预览您的应用：

npm run build

npx wrangler dev

手动部署

构建应用程序后，您可以使用 Wrangler 手动部署它。

首先确保您已登录到 Cloudflare 账户：

npx wrangler login

然后您可以用以下命令部署应用程序：

npx wrangler deploy

运行时钩子

您可以使用以下 运行时钩子 来扩展 Worker 处理程序。

• cloudflare:scheduled
• cloudflare:email
• cloudflare:queue
• cloudflare:tail
• cloudflare:trace

Cloudflare Pages

预设: cloudflare_pages

以下是将 Nitro 应用部署到 Cloudflare Pages 的示例 nitro.config.ts 文件。

export default defineNitroConfig({
    preset: "cloudflare_pages",
    cloudflare: {
      deployConfig: true,
      nodeCompat:true
    }
})

Nitro 将自动生成一个 _routes.json 文件，该文件控制来自文件的路由和来自 Worker 脚本的路由。通过配置选项 cloudflare.pages.routes 可以覆盖自动生成的路由文件 (了解更多)。

本地预览

您可以使用 Wrangler 在本地预览您的应用：

npm run build

npx wrangler pages dev

手动部署

构建应用程序后，您可以使用 Wrangler 手动部署它，首先确保您已登录到 Cloudflare 账户：

npx wrangler login

然后您可以用以下命令部署应用程序：

npx wrangler pages deploy

使用 GitHub Actions 在 CI/CD 中部署

无论您是使用 Cloudflare Pages 还是 Cloudflare Workers，您都可以使用 Wrangler GitHub actions 来部署您的应用。

环境变量

Nitro 允许您通过 process.env 或 import.meta.env 或运行时配置通用访问环境变量。

示例： 如果您设置了 SECRET 和 NITRO_HELLO_THERE 环境变量，您可以通过以下方式访问它们：

console.log(process.env.SECRET) // 请注意，这是在全局范围内！因此实际上它不起作用，变量是未定义的！

export default defineEventHandler((event) => {
  // 请注意，所有以下方式都是访问上述变量的有效方法
  useRuntimeConfig(event).helloThere
  useRuntimeConfig(event).secret
  process.env.NITRO_HELLO_THERE
  import.meta.env.SECRET
});

在开发模式中指定变量

在开发时，您可以使用 .env 文件指定环境变量：

NITRO_HELLO_THERE="captain"
SECRET="top-secret"

为本地预览指定变量

构建后，当您尝试在本地使用 wrangler dev 或 wrangler pages dev 测试项目时，为了访问环境变量，您需要在项目根目录中指定在 .dev.vars 文件中（如 Pages 和 Workers 文档中所示）。

如果您在开发时使用了 .env 文件，则您的 .dev.vars 应与之相同。

为生产环境指定变量

对于生产环境，请使用 Cloudflare 控制台或 wrangler secret 命令设置环境变量和机密。

使用 wrangler.toml/wrangler.json 指定变量

您可以指定自定义的 wrangler.toml/wrangler.json 文件，并在其中定义变量。

示例：

# 共享
[vars]
NITRO_HELLO_THERE="general"
SECRET="secret"

# 为 `--env production` 用法覆盖值
[env.production.vars]
NITRO_HELLO_THERE="captain"
SECRET="top-secret"

直接访问 Cloudflare bindings

绑定允许您与 Cloudflare 平台上的资源交互，这些资源的示例包括键值数据存储 (KVs) 和无服务器 SQL 数据库 (D1s)。

在运行时，您可以通过访问请求事件的 context.cloudflare.env 字段来访问绑定，例如，您可以这样访问 D1 绑定：

defineEventHandler(async (event) => {
  const { cloudflare } = event.context
  const stmt = await cloudflare.env.MY_D1.prepare('SELECT id FROM table')
  const { results } = await stmt.all()
})

在本地开发中访问绑定

为了在开发模式中访问绑定，我们首先定义绑定。您可以在 wrangler.toml/wrangler.json 文件中完成此操作，或在 Nitro 配置中的 cloudflare.wrangler 下直接完成（接受与 wrangler.json 相同的类型）。

例如，在 wrangler.toml 中定义变量和 KV 命名空间：

[vars]
MY_VARIABLE="my-value"

[[kv_namespaces]]
binding = "MY_KV"
id = "xxx"

或在您的 Nitro 配置中：

import nitroCloudflareBindings from "nitro-cloudflare-dev";

export default defineNitroConfig({
    cloudflare: {
      wrangler: {
        vars: {
          MY_VARIABLE: "my-value"
        },
        kv_namespaces: [
          {
            binding: "MY_KV",
            id: "xxx"
          }
        ]
      }
    }
});

接下来，我们安装 nitro-cloudflare-dev 模块和所需的 wrangler 包（如果尚未安装）：

npm i -D nitro-cloudflare-dev wrangler

然后定义模块：

import nitroCloudflareBindings from "nitro-cloudflare-dev";

export default defineNitroConfig({
  modules: [nitroCloudflareBindings],
});

从此时起，当运行

npm run dev

您将能够从请求事件访问 MY_VARIABLE 和 MY_KV，就像上面所示。