通过 wrangler.toml 进行配置

页面功能有两种配置方式，一种是通过 Cloudflare 仪表板 Open external link ，另一种是 wrangler.toml，这是一个用于自定义 Workers 和页面功能的开发和部署设置的配置文件。

本页可作为如何通过 wrangler.toml 配置 Pages 项目的参考。

如果使用 wrangler.toml，则必须将 wrangler.toml 作为 Pages 项目配置的 source of truth。

使用 wrangler.toml 配置你的 Pages 项目，你可以

• 将配置文件保存在源代码控制中： 将配置与其他代码一起保存在版本库中。
• 通过代码编辑器编辑配置： 无需在界面之间来回切换。
• 编写跨环境共享的配置： 在一个文件中定义本地开发、预览和生产环境的配置，如 绑定。
• 确保更好的访问控制： 通过在项目仓库中使用配置文件，你可以控制谁有权进行更改，而无需提供 Cloudflare 控制面板的访问权限。

​​ wrangler.toml 文件示例

​​ 要求

​​ V2 构建系统

通过 wrangler.toml 进行页面功能配置需要 V2 构建系统 或更高版本。要从 V1 升级，请参阅 V2 构建系统迁移说明。

​​ Wrangler

要在 Pages 项目中使用 wrangler.toml 配置，你必须拥有 3.45.0 或更高版本的 Wrangler。要检查 Wrangler 版本、更新 Wrangler 或安装 Wrangler，请参阅 Install/Update Wrangler。

​​ 从仪表板配置迁移

当前没有 wrangler.toml 文件的 Pages 项目的迁移说明与已有 wrangler.toml 文件的 Pages 项目的迁移说明不同。请根据你的情况仔细阅读说明，以避免在生产中出现错误。

​​ 具有现有 wrangler.toml 文件的项目

在使用 wrangler.toml 定义预览和生产配置之前，可以使用 wrangler.toml 定义本地开发中 Pages 项目应使用的 绑定。

如果你一直使用 wrangler.toml 进行本地开发，你的 Pages 项目中可能已经有了一个类似的文件：

如果你想在 Pages 项目配置中使用现有的 wrangler.toml 文件，则必须这样做：

1. 将 pages_build_output_dir 键添加到构建输出目录的适当值(例如，pages_build_output_dir = "./dist".)
2. 在部署之前，仔细查看现有的 wrangler.toml 配置，确保其与所需的项目配置一致。

如果将 pages_build_output_dir 键添加到 wrangler.toml 并部署 Pages 项目，Pages 将使用为本地使用而定义的配置，而这很可能是非生产性的。在确信 wrangler.toml 可用于生产之前，请勿部署。

如果不添加 pages_build_output_dir 键，就可以继续将 wrangler.toml 文件用于本地开发，而无需将其迁移到生产环境中使用。如果不添加 pages_build_output_dir 键并运行 wrangler pages deploy，就会看到一条警告信息，告诉你缺少字段，该文件将继续仅用于本地开发。

​​ 没有wrangler.toml文件的项目

如果你有一个通过 Cloudflare 面板设置配置的现有 Pages 项目，但项目中没有现有的 wrangler.toml 文件，请在 Pages 项目目录中运行 wrangler pages download config 命令。wrangler pages download config 命令将下载现有的 Cloudflare 面板配置，并在 Pages 项目目录中生成有效的wrangler.toml文件。

查看生成的 wrangler.toml 文件。要开始在 Pages 项目的配置中使用 wrangler.toml 文件，请通过 Git 集成 或 直接上传 创建一个新的部署。

​​ 处理设置为 最新 的兼容性日期

在 Cloudflare 仪表板中，你可以将预览部署的兼容性日期设置为 Latest。这将确保你的项目始终使用最新的兼容性日期，而无需自己明确设置。

如果使用 wrangler pages download 命令从配置了 Latest 的项目中下载 wrangler.toml，你的 wrangler.toml 将具有下载配置文件时可用的最新兼容性日期。Wrangler 不支持像仪表盘那样的 Latest 功能。使用 wrangler.toml 时必须明确设置兼容性日期。

请参阅 本指南 了解有关兼容日期及其工作方式的更多信息。

​​ 页面函数和 Worker 使用 wrangler.toml 的区别

如果你使用过 Workers，那么你可能已经熟悉 wrangler.toml。在 Pages Functions 项目中使用 [wrangler.toml]时，需要注意几个关键的区别：

• 页面功能的wrangler.toml文件和 Workers 的对应文件之间的配置字段不完全匹配。例如，main 等特定于 Workers 的配置键不适用于页面函数的 wrangler.toml。
• Pages wrangler.toml 引入了一个新键 pages_build_output_dir，仅用于 Pages 项目。
• 该文件中的 environments 和配置继承概念与 Workers 不同。
• 使用该文件后，该文件将成为source of truth，这意味着使用该文件后，无法编辑仪表板中的相同字段。

​​ 配置环境

使用 wrangler.toml 可以在本地环境、预览部署和生产环境中快速设置配置。

​​ 本地开发

使用 wrangler pages dev 时，wrangler.toml 可在本地运行。这意味着你可以快速测试配置更改，而无需登录 Cloudflare 控制面板。请参考以下配置文件示例：

此 wrangler.toml 配置文件会在 Pages 项目中添加 nodejs_compat 兼容性标志和 KV 命名空间绑定。使用此 wrangler.toml 配置文件在 Pages 项目目录下运行 wrangler pages dev 将在本地应用 nodejs_compat 兼容性标志，并在 context.env.KV 中的 Pages 功能代码中公开 KV 绑定。

​​ 生产和预览部署

准备好部署项目后，可通过创建包含 wrangler.toml 文件的新部署，为生产和预览部署设置配置。

要将上述示例用作生产配置，请使用以下命令创建新的生产部署：

或者更具体地说

要为预览部署部署配置，可以在配置为使用 preview deployments 的分支上运行与上述相同的命令。这将为所有预览部署设置配置，而不仅仅是特定分支的部署。Pages 目前不支持基于分支的配置。

​​ 特定环境overrides

有时，你可能希望在本地、预览部署和生产部署中使用不同的配置。可以使用 [env.production] 或 [env.preview]，覆盖生产部署和预览部署的配置。

有关如何覆盖预览部署配置的示例，请参阅下面的 wrangler.toml 配置文件：

如果通过 wrangler pages deploy 部署此文件，name、pages_build_output_dir、kv_namespaces 和 vars 将把配置应用于本地和生产，而 env.preview 将覆盖预览部署中的 kv_namespaces 和 vars。

如果你想让配置值应用于本地和预览，但覆盖生产配置，你的文件应该是这样的：

你总是可以明确地覆盖预览和制作：

​​ 继承键

可继承键可在顶层进行配置，并可被特定环境配置继承(或覆盖)。

​​ 非继承密钥

非继承键可在顶层进行配置，但如果在任何环境中覆盖了任何一个非继承键(例如，[[env.production.kv_namespaces]])，则必须在环境配置中指定并覆盖所有非继承键。

例如，这种配置将不起作用：

[[env.production.vars]]被设置为覆盖[vars]。因此，也必须通过定义 [[env.production.kv_namespaces]]来覆盖 [[kv_namespaces]]。

这将适用于本地开发，但在尝试部署时将无法验证。

​​ Limits

你可以用与 Workers 相同的方式为 Pages 项目配置限制。详情请阅读 本指南。

​​ 绑定

绑定 使你的页面函数能够与 Cloudflare 开发者平台上的资源交互。使用绑定将你的页面功能与 Cloudflare 资源(如 KV、Durable Objects、R2 和 D1)集成。你可以为生产环境和预览环境设置绑定。

​​ D1 数据库

D1 是 Cloudflare 的无服务器 SQL 数据库。通过为 D1 的客户端 API创建与每个数据库的绑定，功能可以查询 D1 数据库(或多个数据库)。

• 通过 wrangler.toml文件配置 D1 数据库绑定，配置方式与 Cloudflare Workers 相同。
• 与D1 数据库绑定互动。

​​ Durable Objects

耐用对象 为 Workers 平台提供低延迟协调和一致的存储。

• 通过 wrangler.toml 文件配置持久对象命名空间绑定，配置方式与 Cloudflare Workers 相同。

• 与你的耐用对象命名空间绑定交互。

​​ 环境变量

环境变量 是一种绑定类型，允许你将文本字符串或 JSON 值附加到页面函数。

• 通过 wrangler.toml文件配置环境变量，配置方式与 Cloudflare Workers 相同。
• 与 [环境变量] 交互(/pages/functions/bindings/#environment-variables)。

​​ Hyperdrive

通过Hyperdrive绑定，你可以在 Pages 函数中与任何 Postgres 数据库进行交互和查询。

• 通过 wrangler.toml文件配置 Hyperdrive 绑定，配置方式与 Cloudflare Workers 相同。

​​ KV 命名空间

Workers KV是一个全球性、低延迟、键值数据存储。它在少量集中式数据中心存储数据，然后在访问后将数据缓存到 Cloudflare 的数据中心。

• 通过 wrangler.toml文件配置 KV 命名空间绑定，配置方式与 Cloudflare Workers 相同。
• 与你的 KV 命名空间绑定 进行交互。

​​ Queues Producers

队列 是 Cloudflare 的全局消息队列服务，提供保证交付 和消息批处理。队列生产者可让你在页面功能中将消息发送到队列中。

• 通过 wrangler.toml 文件配置队列生产者绑定，配置方式与 Cloudflare Workers 相同。
• 与你的 Queues Producer binding互动。

​​ R2 存储桶

Cloudflare R2 Storage允许开发人员存储大量非结构化数据，而无需支付与典型云存储服务相关的昂贵出口带宽费用。

• 通过 wrangler.toml文件配置 R2 存储桶绑定，配置方式与 Cloudflare Workers 相同。
• 与 [R2 存储桶绑定] 进行交互(/pages/functions/bindings/#r2-buckets)。

​​ Vectorize indexes

矢量化索引允许你插入和查询矢量嵌入，用于语义搜索、分类和其他矢量搜索用例。

• 通过 wrangler.toml文件配置 Vectorize 绑定，配置方式与 Cloudflare Workers 相同。

​​ Service bindings

服务绑定允许你在 Pages 函数中调用 Worker。将 Pages 函数绑定到 Worker 后，你就可以向 Worker 发送 HTTP 请求，而无需通过互联网。请求会立即调用下游 Worker，与请求第三方服务相比减少了延迟。请参阅 关于服务绑定。

• 通过 wrangler.toml文件配置服务绑定，配置方式与 Cloudflare Workers 相同。
• 与服务绑定互动。

​​ 分析引擎数据集

Workers 分析引擎 通过页面函数提供分析、可观察性和数据记录功能。在 Pages 函数绑定中写入数据点，然后使用 SQL API 查询数据。

• 通过 wrangler.toml文件配置分析引擎数据集绑定，配置方式与 Cloudflare Workers 相同。
• 与 Analytics Engine Dataset 交互。

​​ Works人工智能

Workers AI允许你在 Cloudflare 网络上通过自己的代码运行机器学习模型，无论是通过 Workers、Pages 还是通过 REST API。

与其他绑定不同的是，这种绑定仅限于每个 Pages Function 项目使用一种 AI 绑定。

• 通过 wrangler.toml 文件配置 Workers AI 绑定，配置方式与 Cloudflare Workers 相同。
• 与你的 Workers AI 绑定互动。

​​ 本地开发设置

你可以配置的本地开发设置对于页面功能和 Cloudflare Workers 都是一样的。详情请阅读 本指南。

​​ Source of truth

在你的 Pages Functions 项目中使用时，你的 wrangler.toml 文件是最开始的来源。登录 Cloudflare 控制面板后，你可以看到相同的字段，但无法编辑。

如果你决定不使用 wrangler.toml 进行配置，可以安全地删除它并创建新的部署。上次部署中的配置值仍将适用，你可以在仪表板上对其进行编辑。