配置 · Cloudflare Pages docs

Pages Functions 可通过两种方式配置：通过 Cloudflare 仪表板 ↗ 或 Wrangler 配置文件（用于自定义 Workers 和 Pages Functions 开发与部署设置的文件）。

本页作为通过 Wrangler 配置文件配置 Pages 项目的参考。

若使用 Wrangler 配置文件，必须将其视为 Pages 项目配置的唯一来源（source of truth）。

使用 Wrangler 配置文件配置 Pages 项目可让你：

在源代码管理中存储配置文件：将配置与代码一起保存在仓库中。
通过代码编辑器编辑配置：无需在界面之间来回切换。
编写跨环境共享的配置：在一个文件中为本地开发、预览和生产定义绑定等配置。
确保更好的访问控制：通过在项目仓库中使用配置文件，可控制谁有权更改，而无需授予 Cloudflare 仪表板访问权限。

Wrangler 文件示例

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	"name": "my-pages-app",
	"pages_build_output_dir": "./dist",
	"kv_namespaces": [
		{
			"binding": "KV",
			"id": "<NAMESPACE_ID>"
		}
	],
	"d1_databases": [
		{
			"binding": "DB",
			"database_name": "northwind-demo",
			"database_id": "<DATABASE_ID>"
		}
	],
	"vars": {
		"API_KEY": "1234567asdf"
	}
}

"$schema" = "./node_modules/wrangler/config-schema.json"
name = "my-pages-app"
pages_build_output_dir = "./dist"

[[kv_namespaces]]
binding = "KV"
id = "<NAMESPACE_ID>"

[[d1_databases]]
binding = "DB"
database_name = "northwind-demo"
database_id = "<DATABASE_ID>"

[vars]
API_KEY = "1234567asdf"

要求

V2 构建系统

通过 Wrangler 配置文件进行 Pages Functions 配置需要 V2 构建系统或更高版本。若要从 V1 升级，请参阅 V2 构建系统迁移说明。

Wrangler

必须使用 Wrangler 3.45.0 或更高版本才能将 Wrangler 配置文件用于 Pages 项目配置。要检查 Wrangler 版本、更新或安装 Wrangler，请参阅安装/更新 Wrangler。

从仪表板配置迁移

目前没有 Wrangler 文件的 Pages 项目与已有 Wrangler 文件的 Pages 项目的迁移说明不同。请仔细阅读适合你情况的说明，以避免生产环境出错。

已有 Wrangler 文件的项目

在可以使用 Wrangler 配置文件定义预览和生产配置之前，Wrangler 文件可用于定义 Pages 项目在本地开发中可用的绑定。

若你一直使用 Wrangler 配置文件进行本地开发，Pages 项目中可能已有如下文件：

{
	"kv_namespaces": [
		{
			"binding": "KV",
			"id": "<NAMESPACE_ID>"
		}
	]
}

[[kv_namespaces]]
binding = "KV"
id = "<NAMESPACE_ID>"

若要将现有 Wrangler 文件用于 Pages 项目配置，必须：

添加 pages_build_output_dir 键，值为适当的构建输出目录（例如 pages_build_output_dir = "./dist"。）
部署前仔细审查现有 Wrangler 配置，确保与所需项目配置一致。

若向 Wrangler 配置文件添加 pages_build_output_dir 键并部署 Pages 项目，Pages 将使用为本地开发定义的任何配置，这很可能不是生产配置。在确认 Wrangler 配置文件已准备好用于生产之前，请勿部署。

你可以通过不添加 pages_build_output_dir 键，继续将 Wrangler 文件用于本地开发而不迁移到生产使用。若不添加 pages_build_output_dir 键并运行 wrangler pages deploy，将看到警告消息，提示缺少字段，文件将继续仅用于本地开发。

没有现有 Wrangler 文件的项目

若已有通过 Cloudflare 仪表板配置的 Pages 项目且项目中没有现有 Wrangler 文件，在 Pages 项目目录运行 wrangler pages download config 命令。该命令将下载现有 Cloudflare 仪表板配置并在 Pages 项目目录中生成有效的 Wrangler 文件。

npx wrangler pages download config <PROJECT_NAME>

yarn wrangler pages download config <PROJECT_NAME>

pnpm wrangler pages download config <PROJECT_NAME>

审查生成的 Wrangler 文件。若要开始使用 Wrangler 配置文件作为 Pages 项目配置，通过 Git 集成或 Direct Upload 创建新部署。

处理设置为 "Latest" 的兼容性日期

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

若使用 wrangler pages download 命令从配置为 "Latest" 的项目下载 Wrangler 配置文件，Wrangler 配置文件将包含下载时的最新兼容性日期。Wrangler 不支持与仪表板相同的 "Latest" 功能。使用 Wrangler 配置文件时必须显式设置兼容性日期。

有关兼容性日期及其工作原理的更多信息，请参阅此指南。

将 Wrangler 配置文件用于 Pages Functions 与 Workers 的差异

若你使用过 Workers，可能已熟悉 Wrangler 配置文件。在 Pages Functions 项目中使用此文件时，需注意以下关键差异：

配置字段在 Pages Functions Wrangler 文件与 Workers 等效文件之间 并不完全对应。例如，Workers 特有的 main 等配置键不适用于 Pages Function 的 Wrangler 配置文件。Workers 支持的某些功能（如模块别名）Cloudflare Pages 项目尚不支持。
Pages 的 Wrangler 配置文件引入新键 pages_build_output_dir，仅用于 Pages 项目。
此文件中的环境和配置继承概念与 Workers 不同。
使用后，此文件成为唯一来源（source of truth），意味着 无法在仪表板中编辑相同字段。

配置环境

使用 Wrangler 配置文件，可快速设置本地环境、预览部署和生产的配置。

本地开发

使用 wrangler pages dev 时，Wrangler 配置文件在本地生效。这意味着你可以快速测试配置更改，无需登录 Cloudflare 仪表板。以下配置文件为示例：

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	"name": "my-pages-app",
	"pages_build_output_dir": "./dist",
	// Set this to today's date
	"compatibility_date": "2026-08-17",
	"compatibility_flags": [
		"nodejs_compat"
	],
	"kv_namespaces": [
		{
			"binding": "KV",
			"id": "<NAMESPACE_ID>"
		}
	]
}

"$schema" = "./node_modules/wrangler/config-schema.json"
name = "my-pages-app"
pages_build_output_dir = "./dist"
# Set this to today's date
compatibility_date = "2026-08-17"
compatibility_flags = [ "nodejs_compat" ]

[[kv_namespaces]]
binding = "KV"
id = "<NAMESPACE_ID>"

此 Wrangler 配置文件为 Pages 项目添加了 nodejs_compat 兼容性标志和 KV namespace 绑定。在包含此 Wrangler 配置文件的 Pages 项目目录中运行 wrangler pages dev 时，将在本地应用 nodejs_compat 兼容性标志，并在 Pages Function 代码的 context.env.KV 处暴露 KV 绑定。

生产与预览部署

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

要将上述示例用作生产配置，请执行新的生产部署：

npx wrangler pages deploy

或更具体地：

npx wrangler pages deploy --branch <PRODUCTION BRANCH>

要部署预览部署的配置，可在已配置为支持预览部署的分支上运行上述相同命令。这将为所有预览部署设置配置，而不仅限于来自特定分支的部署。Pages 目前不支持基于分支的配置。

环境特定覆盖

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

请参阅以下 Wrangler 配置文件示例，了解如何覆盖预览部署配置：

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	"name": "my-pages-site",
	"pages_build_output_dir": "./dist",
	"kv_namespaces": [
		{
			"binding": "KV",
			"id": "<NAMESPACE_ID>"
		}
	],
	"vars": {
		"API_KEY": "1234567asdf"
	},
	"env": {
		"preview": {
			"kv_namespaces": [
				{
					"binding": "KV",
					"id": "<PREVIEW_NAMESPACE_ID>"
				}
			],
			"vars": {
				"API_KEY": "8901234bfgd"
			}
		}
	}
}

"$schema" = "./node_modules/wrangler/config-schema.json"
name = "my-pages-site"
pages_build_output_dir = "./dist"

[[kv_namespaces]]
binding = "KV"
id = "<NAMESPACE_ID>"

[vars]
API_KEY = "1234567asdf"

[[env.preview.kv_namespaces]]
binding = "KV"
id = "<PREVIEW_NAMESPACE_ID>"

[env.preview.vars]
API_KEY = "8901234bfgd"

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

若希望配置值应用于本地和预览，但覆盖生产，文件应如下所示：

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	"name": "my-pages-site",
	"pages_build_output_dir": "./dist",
	"kv_namespaces": [
		{
			"binding": "KV",
			"id": "<NAMESPACE_ID>"
		}
	],
	"vars": {
		"API_KEY": "1234567asdf"
	},
	"env": {
		"production": {
			"kv_namespaces": [
				{
					"binding": "KV",
					"id": "<PRODUCTION_NAMESPACE_ID>"
				}
			],
			"vars": {
				"API_KEY": "8901234bfgd"
			}
		}
	}
}

"$schema" = "./node_modules/wrangler/config-schema.json"
name = "my-pages-site"
pages_build_output_dir = "./dist"

[[kv_namespaces]]
binding = "KV"
id = "<NAMESPACE_ID>"

[vars]
API_KEY = "1234567asdf"

[[env.production.kv_namespaces]]
binding = "KV"
id = "<PRODUCTION_NAMESPACE_ID>"

[env.production.vars]
API_KEY = "8901234bfgd"

你可以始终显式覆盖预览和生产：

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	"name": "my-pages-site",
	"pages_build_output_dir": "./dist",
	"kv_namespaces": [
		{
			"binding": "KV",
			"id": "<NAMESPACE_ID>"
		}
	],
	"vars": {
		"API_KEY": "1234567asdf"
	},
	"env": {
		"preview": {
			"kv_namespaces": [
				{
					"binding": "KV",
					"id": "<PREVIEW_NAMESPACE_ID>"
				}
			],
			"vars": {
				"API_KEY": "8901234bfgd"
			}
		},
		"production": {
			"kv_namespaces": [
				{
					"binding": "KV",
					"id": "<PRODUCTION_NAMESPACE_ID>"
				}
			],
			"vars": {
				"API_KEY": "6567875fvgt"
			}
		}
	}
}

"$schema" = "./node_modules/wrangler/config-schema.json"
name = "my-pages-site"
pages_build_output_dir = "./dist"

[[kv_namespaces]]
binding = "KV"
id = "<NAMESPACE_ID>"

[vars]
API_KEY = "1234567asdf"

[[env.preview.kv_namespaces]]
binding = "KV"
id = "<PREVIEW_NAMESPACE_ID>"

[env.preview.vars]
API_KEY = "8901234bfgd"

[[env.production.kv_namespaces]]
binding = "KV"
id = "<PRODUCTION_NAMESPACE_ID>"

[env.production.vars]
API_KEY = "6567875fvgt"

可继承键

可继承键可在顶层配置，并可通过环境特定配置继承（或覆盖）。

name stringrequired
- Pages 项目名称。仅允许字母数字和连字符。
pages_build_output_dir stringrequired
- 项目构建输出文件夹的路径。例如：./dist。
compatibility_date stringrequired
- 格式为 yyyy-mm-dd 的日期，用于确定使用哪个版本的 Workers 运行时。请参阅兼容性日期。
compatibility_flags string[] optional
- 启用 Workers 运行时即将推出功能的标志列表，通常与 compatibility_date 一起使用。请参阅兼容性日期。
send_metrics booleanoptional
- Wrangler 是否应为此项目向 Cloudflare 发送使用数据。默认为 true。更多信息请参阅我们的数据政策 ↗。
limits Limits optional
- 配置运行时执行限制。请参阅 Limits。
placement Placement optional
- 指定 Pages Functions 的放置方式以最小化往返时间。请参阅 Smart Placement。
upload_source_maps boolean
- 当 upload_source_maps 设置为 true 时，Wrangler 将上传 Pages 项目中所有服务端 source map，以便在日志中获得正确的堆栈跟踪。

不可继承键

不可继承键可在顶层配置，但若为任一环境覆盖了任一不可继承键（例如 [[env.production.kv_namespaces]]），则必须在环境配置中也指定所有不可继承键并进行覆盖。

例如，以下配置将无法工作：

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	"name": "my-pages-site",
	"pages_build_output_dir": "./dist",
	"kv_namespaces": [
		{
			"binding": "KV",
			"id": "<NAMESPACE_ID>"
		}
	],
	"vars": {
		"API_KEY": "1234567asdf"
	},
	"env": {
		"production": {
			"vars": {
				"API_KEY": "8901234bfgd"
			}
		}
	}
}

"$schema" = "./node_modules/wrangler/config-schema.json"
name = "my-pages-site"
pages_build_output_dir = "./dist"

[[kv_namespaces]]
binding = "KV"
id = "<NAMESPACE_ID>"

[vars]
API_KEY = "1234567asdf"

[env.production.vars]
API_KEY = "8901234bfgd"

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

这在本地开发中可用，但在尝试部署时将无法通过验证。

vars objectoptional
- 部署 Function 时设置的环境变量映射。请参阅环境变量。
d1_databases objectoptional
- Function 应绑定的 D1 数据库列表。请参阅 D1 数据库。
durable_objects objectoptional
- Function 应绑定的 Durable Objects 列表。请参阅 Durable Objects。
hyperdrive objectoptional
- 指定 Function 应绑定的 Hyperdrive 配置。请参阅 Hyperdrive。
kv_namespaces objectoptional
- Function 应绑定的 KV namespace 列表。请参阅 KV namespace。
queues.producers objectoptional
- 指定绑定到此 Function 的 Queues Producer。请参阅 Queues Producer。
r2_buckets objectoptional
- Function 应绑定的 R2 存储桶列表。请参阅 R2 存储桶。
vectorize objectoptional
- Function 应绑定的 Vectorize 索引列表。请参阅 Vectorize 索引。
services objectoptional
- Function 应绑定的 service binding 列表。请参阅 service binding。
analytics_engine_datasets objectoptional
- 指定绑定到此 Function 的 Analytics Engine 数据集。请参阅 Workers Analytics Engine。
ai objectoptional
- 指定绑定到此 Function 的 AI binding。请参阅 Workers AI。

Limits

你可以像配置 Workers 一样为 Pages 项目配置限制。更多详情，请参阅此指南。

绑定

绑定（binding）使 Pages Functions 能够与 Cloudflare Developer Platform 上的资源交互。使用绑定将 Pages Functions 与 KV、Durable Objects、R2 和 D1 等 Cloudflare 资源集成。你可以为生产和预览环境设置绑定。

D1 数据库

D1 是 Cloudflare 的无服务器 SQL 数据库。Function 可通过为每个数据库创建绑定（binding）来查询 D1 数据库（或数据库），以使用 D1 Workers Binding API。

通过 Wrangler 文件配置 D1 数据库绑定，方式与 Cloudflare Workers 相同。
与 D1 数据库绑定交互。

Durable Objects

Durable Objects 为 Workers 平台提供低延迟协调和一致存储。

通过 Wrangler 文件配置 Durable Object namespace 绑定，方式与 Cloudflare Workers 相同。

与 Durable Object namespace 绑定交互。

环境变量

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

通过 Wrangler 文件配置环境变量，方式与 Cloudflare Workers 相同。
与环境变量交互。

Hyperdrive

Hyperdrive 绑定允许你在 Pages Function 内与任意 Postgres 数据库交互和查询。

通过 Wrangler 文件配置 Hyperdrive 绑定，方式与 Cloudflare Workers 相同。

KV 命名空间

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

通过 Wrangler 文件配置 KV namespace 绑定，方式与 Cloudflare Workers 相同。
与 KV namespace 绑定交互。

Queues Producer

Queues 是 Cloudflare 的全球消息队列服务，提供保证交付和消息批处理。Queue Producer 使你可以在 Pages Function 内向队列发送消息。

通过 Wrangler 文件配置 Queues Producer 绑定，方式与 Cloudflare Workers 相同。
与 Queues Producer 绑定交互。

R2 存储桶

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

通过 Wrangler 文件配置 R2 存储桶绑定，方式与 Cloudflare Workers 相同。
与 R2 存储桶绑定交互。

Vectorize 索引

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

通过 Wrangler 文件配置 Vectorize 绑定，方式与 Cloudflare Workers 相同。

服务绑定

Service binding 允许你在 Pages Function 内调用 Worker。将 Pages Function 绑定到 Worker 后，你可以向 Worker 发送 HTTP 请求，而无需经过互联网。请求会立即调用下游 Worker，与向第三方服务发送请求相比延迟更低。请参阅关于 Service binding。

通过 Wrangler 文件配置 service binding，方式与 Cloudflare Workers 相同。
与 service binding 交互。

Analytics Engine 数据集

Workers Analytics Engine 为 Pages Functions 提供分析、可观测性和数据日志记录。在 Pages Function 绑定中写入数据点，然后使用 SQL API 查询数据。

通过 Wrangler 文件配置 Analytics Engine 数据集绑定，方式与 Cloudflare Workers 相同。
与 Analytics Engine 数据集交互。

Workers AI

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

与其他绑定不同，此绑定每个 Pages Function 项目仅限一个 AI binding。

通过 Wrangler 文件配置 Workers AI 绑定，方式与 Cloudflare Workers 相同。
与 Workers AI 绑定交互。

本地开发设置

Pages Functions 和 Cloudflare Workers 可配置的本地开发设置相同。更多详情，请参阅此指南。

唯一来源（source of truth）

在 Pages Functions 项目中使用时，Wrangler 文件是唯一来源（source of truth）。登录 Cloudflare 仪表板后，你可以查看但无法编辑相同字段。

若决定不使用 Wrangler 配置文件进行配置，可以安全删除它并创建新部署。上次部署的配置值仍将生效，你可以从仪表板进行编辑。