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",
  

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

  npm run build

Wrangler

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

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 文件。

以下是一个 Nitro 应用程序的典型 wrangler.toml 文件示例：

name = "playground"
main = "./.output/server/index.mjs"
workers_dev = true
compatibility_date = "2023-12-01"
# account_id = "<(可选) 您的 Cloudflare 账户 ID，可从 Cloudflare 仪表板获取>"
# route = "<(可选) 主要在您想设置自定义域名时使用>"

rules = [
  { type = "ESModule", globs = ["**/*.js", "**/*.mjs"]},
]

[site]
bucket = ".output/public"

在本地预览您的应用

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

NITRO_PRESET=cloudflare npm run build

# 如果您在项目根目录中添加了类似上述的 '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，就像上面所示的那样。