Cloudflare

Cloudflare Pages

预设: cloudflare_pages

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

使用预设构建您的应用程序

该预设仅适用于应用程序的构建过程。

如果您使用 Cloudflare Pages GitHub/GitLab 集成，并且不需要在本地预览您的应用程序，那么 Nitro 不需要任何形式的配置。当您推送到您的存储库时，Cloudflare Pages 的 CI/CD 过程将自动构建您的项目，Nitro 会检测正确的环境并相应地构建您的应用程序。

如果您想要在本地预览您的应用程序和/或手动部署它，在构建应用程序时，您需要让 Nitro 知道目标环境是 Cloudflare Pages，您可以通过以下两种方式做到这一点：

• 在运行构建过程时定义 NITRO_PRESET 或 SERVER_PRESET 环境变量设置为 cloudflare_pages，如下所示：

  NITRO_PRESET=cloudflare_pages npm run build
  

• 或通过更新您的 Nitro 预设配置:

  "preset": "cloudflare_pages",
  

  
  然后运行标准构建命令：
  npmyarnpnpmbundeno

  npm run build

Wrangler

要在本地预览您的应用程序或手动部署它，您需要使用 wrangler CLI 工具，只需将其安装为节点依赖项：

npm i wrangler

在本地预览您的应用程序

构建完应用程序后，您可以通过运行以下命令使用 wrangler 在本地预览它：

npx wrangler pages dev dist

使用 wrangler 从本地机器部署

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

npx wrangler login

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

npx wrangler pages deploy dist

Cloudflare Module Workers

预设: cloudflare_module

使用 Workers 时，您需要一个位于根目录的 wrangler.toml 文件。对于使用 静态资产 (测试版的 限制) 的 Worker，您还需要在 wrangler.toml 文件和 nitro 配置文件中设置兼容性日期为 2024-09-19 或更高。

以下是 Nitro 应用程序的典型 wrangler.toml 文件和 nitro.config.ts 文件的示例：

export default defineNitroConfig({
    compatibilityDate: "2024-09-19",
})

name = "nitro-app"
compatibility_date = "2024-09-19"
main = "./.output/server/index.mjs"
assets = { directory = "./.output/public/", binding = "ASSETS" }

运行时钩子

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

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

在本地预览您的应用程序

您可以使用 wrangler 来在本地预览您的应用程序：

NITRO_PRESET=cloudflare npm run build

# 如果您在 project 根目录中添加了 'wrangler.toml' 文件，如上所示：
npx wrangler dev

# 如果您没有 'wrangler.toml'，直接使用：
npx wrangler dev .output/server/index.mjs --site .output/public

使用 wrangler 从本地机器部署

安装 wrangler 并登录到您的 Cloudflare 账户：

npm i wrangler
wrangler login

使用 cloudflare_module 预设生成您的应用程序：

NITRO_PRESET=cloudflare_module npm run build

然后，您可以在本地预览它：

# 如果您有一个 'wrangler.toml' 文件，如上所示：
npx wrangler dev

# 如果您没有 'wrangler.toml'：
npx wrangler dev .output/server/index.mjs --site .output/public

并发布它：

npx wrangler deploy

Cloudflare Service Workers

预设: cloudflare

该预设的工作方式与上面介绍的 cloudflare_module 相同，唯一的区别是该预设继承了所有该语法所带来的 缺点。

使用 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.toml 文件并在其中定义变量。

示例：

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

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

直接访问 Cloudflare 绑定

绑定允许您与 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 文件（以及 .dev.vars 文件）与 nitro-cloudflare-dev 模块 结合使用，如下所示。

为了在开发模式中访问绑定，我们首先在 wrangler.toml 文件中定义绑定，例如这样定义一个变量和一个 KV 命名空间：

[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，正如上面所示的那样。