Cloudflare

Cloudflare

Deploy Nitro apps to Cloudflare.

Cloudflare Pages

预设：cloudflare_pages

相关阅读：Cloudflare Pages

这是 Cloudflare 部署的推荐预设，如果您有特殊要求或需求，请考虑使用替代预设。

可以使用 零配置 与此提供商集成。

Nitro 自动生成一个 _routes.json 文件，该文件控制哪些路由从文件提供，哪些路由从 Worker 脚本提供。可以使用配置选项 cloudflare.pages.routes 覆盖自动生成的路由文件（阅读更多)。

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

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

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

如果您希望在本地预览应用程序和/或手动部署它，则在构建应用程序时，您需要让 Nitro 知道目标环境是 Cloudflare Pages，您可以通过两种方式执行此操作：

  1. 通过在运行构建过程时定义 NITRO_PRESET 或 SERVER_PRESET 环境变量并将其设置为 cloudflare-pages，如下所示：
bash
NITRO_PRESET=cloudflare-pages npm run build
  1. 或者通过更新您的 Nitro 预设配置：
json5
{ "preset": "cloudflare-pages" }

然后运行标准构建命令：

Wrangler

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

本地预览您的应用

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

使用 wrangler 从本地机器部署

构建应用程序后，您可以通过 wrangler 手动部署它，为此，首先请确保已登录到您的 Cloudflare 帐户：

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

Cloudflare Module Workers

预设：cloudflare_module

注意：此预设使用 module worker 语法 进行部署。

**注意：**不建议使用此预设。

使用 Workers 时，您需要在根目录中有一个 wrangler.toml 文件。

以下显示了 Nitro 应用程序的典型 wrangler.toml 文件：

ini
name = "playground"
main = "./.output/server/index.mjs"
workers_dev = true
compatibility_date = "2023-12-01"
# account_id = "<(optional) your Cloudflare account id, retrievable from the Cloudflare dashboard>"
# route = "<(optional) mainly useful when you want to setup custom domains>"

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

[site]
bucket = ".output/public"

在本地预览您的应用

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

bash
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 帐户：

bash
npm i wrangler
wrangler login

使用 cloudflare 预设生成您的应用：

bash
NITRO_PRESET=cloudflare_module npm run build

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

bash
# 如果您有像上面这样的 'wrangler.toml'：
npx wrangler dev

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

并发布它：

Cloudflare Service Workers

Preset: cloudflare

**注意：**此预设使用 service worker 语法 进行部署。

**注意：**此预设已弃用。

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

使用 GitHub Actions 在 CI/CD 内部署

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

**注意：**请记住 指示 Nitro 使用正确的预设（请注意，对于包括 cloudflare_pages 在内的所有预设，这都是必需的）。

环境变量

Nitro 允许您使用 process.env 或 import.meta.env 或运行时配置来普遍访问环境变量。

确保仅在事件生命周期内访问环境变量，而不是在全局上下文中访问，因为 Cloudflare 仅在请求生命周期内提供这些变量，而不是在此之前。

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

ts
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 文件来指定环境变量：

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

**注意：**请确保将 .env 添加到 .gitignore 文件中，以免提交该文件，因为该文件可能包含敏感信息。

为本地预览指定变量

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

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

**注意：**请确保将 .dev.vars 添加到 .gitignore 文件中，以免提交该文件，因为它可能包含敏感信息。

为生产指定变量

对于生产，使用 cloudflare 仪表板或 wrangler secret 命令设置环境变量和机密。

使用 wrangler.toml 指定变量

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

注意：wrangler.toml 不受 cloudflare 页面支持。

请注意，不建议对敏感数据使用此功能。

Example:

wrangler.toml
ini
# Shared
[vars]
NITRO_HELLO_THERE="general"
SECRET="secret"

# Override values for `--env production` usage
[env.production.vars]
NITRO_HELLO_THERE="captain"
SECRET="top-secret"

直接访问 cloudflare 绑定

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

有关绑定及其使用方法的更多详细信息，请参阅 Cloudflare Pages 和 Workers 文档。

!TIP Nitro 提供高级 API 来与 KV 存储 和 数据库 等原语交互，强烈建议您优先使用它们，而不是直接依赖低级 API 来确保使用稳定性。

相关阅读：Database Layer
相关阅读：KV Storage

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

ts
defineEventHandler((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 模块 结合使用，如下所示。

!NOTEnitro-cloudflare-dev 模块是实验性的。Nitro 团队正在研究一种更原生的集成，这可能会在不久的将来使该模块变得不再需要。

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

wrangler.toml
ini
[vars]
MY_VARIABLE="my-value"

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

!NOTE 仅识别默认环境中的绑定。

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

然后定义模块：

js
nitro.config.js
js
import nitroCloudflareBindings from 'nitro-cloudflare-dev'

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

从此刻起，当运行

时，您将能够从请求事件访问 MY_VARIABLE 和 MY_KV，如上所示。