绑定（binding）

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

本指南将指导你为 Pages Function 配置绑定。继续之前，你必须已设置 Cloudflare Developer Platform 资源。

Workers KV 是 Cloudflare 的键值存储解决方案。

要将 KV 命名空间绑定到 Pages Function，可在 Wrangler 配置文件 或 Cloudflare 仪表板中配置 KV 命名空间绑定。

通过 Cloudflare 仪表板配置 KV 命名空间绑定：

1. 在 Cloudflare 仪表板中，前往 Workers & Pages 页面。

   Go to Workers & Pages ↗

2. 选择你的 Pages 项目。

3. 前往 Settings（设置） > Bindings > Add（添加） > KV namespace。

4. 在 Variable name（变量名） 下为绑定命名。

5. 在 KV namespace（KV 命名空间） 下，选择所需的命名空间。

6. 重新部署项目以使绑定生效。

以下是在 Function 中使用 KV 的示例。以下示例中，KV 命名空间绑定名为 TODO_LIST，可在 Function 代码中通过 context.env 访问该绑定：

export async function onRequest(context) {
	const task = await context.env.TODO_LIST.get("Task:123");
	return new Response(task);
}

interface Env {
	TODO_LIST: KVNamespace;
}

export const onRequest: PagesFunction<Env> = async (context) => {
	const task = await context.env.TODO_LIST.get("Task:123");
	return new Response(task);
};

可通过以下两种方式在本地与 KV 命名空间绑定交互：

• 配置 Pages 项目的 Wrangler 文件并运行 npx wrangler pages dev。
• 直接向 wrangler pages dev 传递参数。

若要通过向 Wrangler CLI 传递参数在本地与 KV 命名空间绑定交互，向 wrangler pages dev 命令添加 -k <BINDING_NAME> 或 --kv=<BINDING_NAME>。例如，若 KV 命名空间通过 TODO_LIST 绑定到 Function，运行以下命令在本地开发中访问 KV 命名空间：

npx wrangler pages dev <OUTPUT_DIR> --kv=TODO_LIST

Durable Objects（DO）是 Cloudflare 的强一致性数据存储，支持 WebSocket 连接和状态管理等能力。

你必须创建 Durable Object Worker，并使用 Cloudflare 仪表板或 Pages 项目的 Wrangler 配置文件 将其绑定到 Pages 项目。你无法在 Pages 项目内创建并部署 Durable Object。

要将 Durable Object 绑定到 Pages Function，可在 Wrangler 配置文件 或 Cloudflare 仪表板中配置 Durable Object 绑定。

通过 Cloudflare 仪表板配置 Durable Object 绑定：

1. 在 Cloudflare 仪表板中，前往 Workers & Pages 页面。

   Go to Workers & Pages ↗

2. 选择你的 Pages 项目。

3. 前往 Settings（设置） > Bindings > Add（添加） > Durable Object。

4. 在 Variable name（变量名） 下为绑定命名。

5. 在 Durable Object namespace（Durable Object 命名空间） 下，选择所需的命名空间。

6. 重新部署项目以使绑定生效。

以下是在 Function 中使用 Durable Objects 的示例。以下示例中，DO 绑定名为 DURABLE_OBJECT，可在 Function 代码中通过 context.env 访问该绑定：

export async function onRequestGet(context) {
	const id = context.env.DURABLE_OBJECT.newUniqueId();
	const stub = context.env.DURABLE_OBJECT.get(id);

	// Pass the request down to the durable object
	return stub.fetch(context.request);
}

interface Env {
	DURABLE_OBJECT: DurableObjectNamespace;
}

export const onRequestGet: PagesFunction<Env> = async (context) => {
	const id = context.env.DURABLE_OBJECT.newUniqueId();
	const stub = context.env.DURABLE_OBJECT.get(id);

	// Pass the request down to the durable object
	return stub.fetch(context.request);
};

可通过以下两种方式在本地与 Durable Object 绑定交互：

• 配置 Pages 项目的 Wrangler 文件并运行 npx wrangler pages dev。
• 直接向 wrangler pages dev 传递参数。

本地开发时，要与 Durable Object 命名空间交互，在导出 Durable Object 的 Worker 目录中运行 wrangler dev。在另一个终端中，在 Pages 项目目录运行 wrangler pages dev。

若要通过 Wrangler CLI 在本地与 Durable Object 命名空间交互，向 wrangler pages dev 追加 --do <BINDING_NAME>=<CLASS_NAME>@<SCRIPT_NAME>。CLASS_NAME 表示 Durable Object 类名，SCRIPT_NAME 表示 Worker 名称。

例如，若 Worker 名为 do-worker 且声明了名为 DurableObjectExample 的 Durable Object 类，在 do-worker 目录运行 npx wrangler dev 访问此 Durable Object。同时，在 Pages 项目目录运行 npx wrangler pages dev <OUTPUT_DIR> --do MY_DO=DurableObjectExample@do-worker。在 Function 代码中通过 context.env 与此 MY_DO 绑定交互（例如 context.env.MY_DO）。

R2 是 Cloudflare 的对象存储解决方案，允许开发者存储大量非结构化数据，且无需支付出口流量费用。

要将 R2 存储桶绑定到 Pages Function，可在 Wrangler 配置文件 或 Cloudflare 仪表板中配置 R2 存储桶绑定。

通过 Cloudflare 仪表板配置 R2 存储桶绑定：

1. 在 Cloudflare 仪表板中，前往 Workers & Pages 页面。

   Go to Workers & Pages ↗

2. 选择你的 Pages 项目。

3. 前往 Settings（设置） > Bindings > Add（添加） > R2 bucket。

4. 在 Variable name（变量名） 下为绑定命名。

5. 在 R2 bucket（R2 存储桶） 下，选择所需的 R2 存储桶。

6. 重新部署项目以使绑定生效。

以下是在 Function 中使用 R2 存储桶的示例。以下示例中，R2 存储桶绑定名为 BUCKET，可在 Function 代码中通过 context.env 访问该绑定：

export async function onRequest(context) {
	const obj = await context.env.BUCKET.get("some-key");
	if (obj === null) {
		return new Response("Not found", { status: 404 });
	}
	return new Response(obj.body);
}

interface Env {
	BUCKET: R2Bucket;
}

export const onRequest: PagesFunction<Env> = async (context) => {
	const obj = await context.env.BUCKET.get("some-key");
	if (obj === null) {
		return new Response("Not found", { status: 404 });
	}
	return new Response(obj.body);
};

可通过以下两种方式在本地与 R2 存储桶绑定交互：

• 配置 Pages 项目的 Wrangler 文件并运行 npx wrangler pages dev。
• 直接向 wrangler pages dev 传递参数。

若要通过 Wrangler CLI 在本地与 R2 存储桶交互，向 wrangler pages dev 命令添加 --r2=<BINDING_NAME>。若 R2 存储桶通过 BUCKET 绑定到 Function，运行以下命令在本地开发中访问此 R2 存储桶：

npx wrangler pages dev <OUTPUT_DIR> --r2=BUCKET

通过 context.env 与此绑定交互（例如 context.env.BUCKET。）

D1 是 Cloudflare 的原生无服务器数据库。

要将 D1 数据库绑定到 Pages Function，可在 Wrangler 配置文件 或 Cloudflare 仪表板中配置 D1 数据库绑定。

通过 Cloudflare 仪表板配置 D1 数据库绑定：

1. 在 Cloudflare 仪表板中，前往 Workers & Pages 页面。

   Go to Workers & Pages ↗

2. 选择你的 Pages 项目。

3. 前往 Settings（设置） > Bindings > Add（添加） > D1 database bindings。

4. 在 Variable name（变量名） 下为绑定命名。

5. 在 D1 database（D1 数据库） 下，选择所需的 D1 数据库。

6. 重新部署项目以使绑定生效。

以下是在 Function 中使用 D1 的示例。以下示例中，D1 数据库绑定为 NORTHWIND_DB，可在 Function 代码中通过 context.env 访问该绑定：

export async function onRequest(context) {
	// Create a prepared statement with our query
	const ps = context.env.NORTHWIND_DB.prepare("SELECT * from users");
	const data = await ps.first();

	return Response.json(data);
}

interface Env {
	NORTHWIND_DB: D1Database;
}

export const onRequest: PagesFunction<Env> = async (context) => {
	// Create a prepared statement with our query
	const ps = context.env.NORTHWIND_DB.prepare("SELECT * from users");
	const data = await ps.first();

	return Response.json(data);
};

可通过以下两种方式在本地与 D1 数据库绑定交互：

• 配置 Pages 项目的 Wrangler 文件并运行 npx wrangler pages dev。
• 直接向 wrangler pages dev 传递参数。

若要在 本地开发 时通过 Wrangler CLI 与 D1 数据库交互，向 wrangler pages dev 命令添加 --d1 <BINDING_NAME>=<DATABASE_ID>。

若 D1 数据库通过 NORTHWIND_DB 绑定到 Pages Function，且 Wrangler 文件中的 database_id 为 xxxx-xxxx-xxxx-xxxx-xxxx，运行以下命令在本地开发中访问此数据库：

npx wrangler pages dev <OUTPUT_DIR> --d1 NORTHWIND_DB=xxxx-xxxx-xxxx-xxxx-xxxx

通过 context.env 与此绑定交互（例如 context.env.NORTHWIND_DB。）

有关 D1 绑定上可用 API 方法，请参阅 D1 Workers Binding API 文档。

Vectorize 是 Cloudflare 的原生向量数据库。

要将 Vectorize 索引绑定到 Pages Function，可在 Wrangler 配置文件 或 Cloudflare 仪表板中配置 Vectorize 索引绑定。

通过 Cloudflare 仪表板配置 Vectorize 索引绑定：

1. 在 Cloudflare 仪表板中，前往 Workers & Pages 页面。

   Go to Workers & Pages ↗

2. 选择要在 Production（生产） 还是 Preview（预览） 环境中设置绑定。

3. 选择 Pages 项目 > Settings（设置）。

4. 前往 Bindings（绑定） > Add（添加） > Vectorize index（Vectorize 索引）。

5. 在 Variable name（变量名） 下为绑定命名。

6. 在 Vectorize index（Vectorize 索引） 下，选择所需的 Vectorize 索引。

7. 重新部署项目以使绑定生效。

要在 Pages Function 中使用 Vectorize 索引，可在 Pages Function 代码中访问 Vectorize 索引绑定。以下示例中，Vectorize 索引绑定名为 VECTORIZE_INDEX，可在 Pages Function 代码中通过 context.env 访问该绑定。

// Sample vectors: 3 dimensions wide.
//
// Vectors from a machine-learning model are typically ~100 to 1536 dimensions
// wide (or wider still).
const sampleVectors = [
	{
		id: "1",
		values: [32.4, 74.1, 3.2],
		metadata: { url: "/products/sku/13913913" },
	},
	{
		id: "2",
		values: [15.1, 19.2, 15.8],
		metadata: { url: "/products/sku/10148191" },
	},
	{
		id: "3",
		values: [0.16, 1.2, 3.8],
		metadata: { url: "/products/sku/97913813" },
	},
	{
		id: "4",
		values: [75.1, 67.1, 29.9],
		metadata: { url: "/products/sku/418313" },
	},
	{
		id: "5",
		values: [58.8, 6.7, 3.4],
		metadata: { url: "/products/sku/55519183" },
	},
];

export async function onRequest(context) {
	let path = new URL(context.request.url).pathname;
	if (path.startsWith("/favicon")) {
		return new Response("", { status: 404 });
	}

	// You only need to insert vectors into your index once
	if (path.startsWith("/insert")) {
		// Insert some sample vectors into your index
		// In a real application, these vectors would be the output of a machine learning (ML) model,
		// such as Workers AI, OpenAI, or Cohere.
		let inserted = await context.env.VECTORIZE_INDEX.insert(sampleVectors);

		// Return the number of IDs we successfully inserted
		return Response.json(inserted);
	}
}

export interface Env {
	// This makes our vector index methods available on context.env.VECTORIZE_INDEX.*
	// For example, context.env.VECTORIZE_INDEX.insert() or query()
	VECTORIZE_INDEX: VectorizeIndex;
}

// Sample vectors: 3 dimensions wide.
//
// Vectors from a machine-learning model are typically ~100 to 1536 dimensions
// wide (or wider still).
const sampleVectors: Array<VectorizeVector> = [
	{
		id: "1",
		values: [32.4, 74.1, 3.2],
		metadata: { url: "/products/sku/13913913" },
	},
	{
		id: "2",
		values: [15.1, 19.2, 15.8],
		metadata: { url: "/products/sku/10148191" },
	},
	{
		id: "3",
		values: [0.16, 1.2, 3.8],
		metadata: { url: "/products/sku/97913813" },
	},
	{
		id: "4",
		values: [75.1, 67.1, 29.9],
		metadata: { url: "/products/sku/418313" },
	},
	{
		id: "5",
		values: [58.8, 6.7, 3.4],
		metadata: { url: "/products/sku/55519183" },
	},
];

export const onRequest: PagesFunction<Env> = async (context) => {
	let path = new URL(context.request.url).pathname;
	if (path.startsWith("/favicon")) {
		return new Response("", { status: 404 });
	}

	// You only need to insert vectors into your index once
	if (path.startsWith("/insert")) {
		// Insert some sample vectors into your index
		// In a real application, these vectors would be the output of a machine learning (ML) model,
		// such as Workers AI, OpenAI, or Cohere.
		let inserted = await context.env.VECTORIZE_INDEX.insert(sampleVectors);

		// Return the number of IDs we successfully inserted
		return Response.json(inserted);
	}
};

Workers AI 允许你在 Cloudflare 全球网络上使用无服务器 GPU 运行机器学习模型。

要将 Workers AI 绑定到 Pages Function，可在 Wrangler 配置文件 或 Cloudflare 仪表板中配置 Workers AI 绑定。

使用 Wrangler 本地开发时，可通过 --ai 标志定义 AI 绑定。运行 wrangler pages dev --ai AI 启动开发模式以暴露 context.env.AI 绑定。

通过 Cloudflare 仪表板配置 Workers AI 绑定：

1. 前往 Workers & Pages 页面。

   Go to Workers & Pages ↗

2. 选择 Pages 项目 > Settings（设置）。

3. 选择 Pages 环境 > Bindings > Add（添加） > Workers AI。

4. 在 Variable name（变量名） 下为绑定命名。

5. 重新部署项目以使绑定生效。

要在 Pages Function 中使用 Workers AI，可在 Pages Function 代码中访问 Workers AI 绑定。以下示例中，Workers AI 绑定名为 AI，可在 Pages Function 代码中通过 context.env 访问该绑定。

export async function onRequest(context) {
	const input = { prompt: "What is the origin of the phrase Hello, World" };

	const answer = await context.env.AI.run(
		"@cf/meta/llama-3.1-8b-instruct",
		input,
	);

	return Response.json(answer);
}

interface Env {
	AI: Ai;
}

export const onRequest: PagesFunction<Env> = async (context) => {
	const input = { prompt: "What is the origin of the phrase Hello, World" };

	const answer = await context.env.AI.run(
		"@cf/meta/llama-3.1-8b-instruct",
		input,
	);

	return Response.json(answer);
};

可通过以下两种方式在本地与 Workers AI 绑定交互：

• 配置 Pages 项目的 Wrangler 文件并运行 npx wrangler pages dev。
• 直接向 wrangler pages dev 传递参数。

要在本地开发时通过 Wrangler CLI 与 Workers AI 绑定交互，运行：

npx wrangler pages dev --ai=<BINDING_NAME>

Service 绑定 使你可以从 Pages Function 内调用 Worker。

要将 Pages Function 绑定到 Worker，在 Pages Function 中使用 Wrangler 配置文件 或 Cloudflare 仪表板配置 Service 绑定。

通过 Cloudflare 仪表板配置 Service 绑定：

1. 在 Cloudflare 仪表板中，前往 Workers & Pages 页面。

   Go to Workers & Pages ↗

2. 选择你的 Pages 项目。

3. 前往 Settings（设置） > Bindings > Add（添加） > Service binding。

4. 在 Variable name（变量名） 下为绑定命名。

5. 在 Service（服务） 下，选择所需的 Worker。

6. 重新部署项目以使绑定生效。

以下是在 Function 中使用 Service 绑定的示例。以下示例中，Service 绑定名为 SERVICE，可在 Function 代码中通过 context.env 访问该绑定：

export async function onRequestGet(context) {
	return context.env.SERVICE.fetch(context.request);
}

interface Env {
	SERVICE: Fetcher;
}

export const onRequest: PagesFunction<Env> = async (context) => {
	return context.env.SERVICE.fetch(context.request);
};

可通过以下两种方式在本地与 Service 绑定交互：

• 配置 Pages 项目的 Wrangler 文件并运行 npx wrangler pages dev。
• 直接向 wrangler pages dev 传递参数。

要在本地开发时与 Service 绑定 交互，通过 wrangler dev 运行要绑定的 Worker，同时运行 wrangler pages dev 并附加 --service <BINDING_NAME>=<SCRIPT_NAME>，其中 SCRIPT_NAME 表示 Worker 名称。例如，若 Worker 名为 my-worker，在 Worker 目录通过 npx wrangler dev 运行该 Worker，同时在 Pages 目录运行 npx wrangler pages dev <OUTPUT_DIR> --service MY_SERVICE=my-worker。通过 context.env 与此绑定交互（例如 context.env.MY_SERVICE）。

若通过 Cloudflare 仪表板设置 Service 绑定，需向 wrangler pages dev 附加 --service <BINDING_NAME>=<SCRIPT_NAME>，其中 BINDING_NAME 是 Service 绑定名称，SCRIPT_NAME 是 Worker 名称。

例如，若 Worker 名为 my-worker，在 my-worker 目录运行 npx wrangler dev 进行本地开发。在另一个终端中，在 Pages 项目目录运行 npx wrangler pages dev <OUTPUT_DIR> --service MY_SERVICE=my-worker。通过 context.env 与此 Service 绑定交互（例如 context.env.MY_SERVICE）。

Wrangler 还支持用一个命令在同一开发会话中运行 Pages 项目和绑定的 Workers。要试用，向 Wrangler 传递多个 -c 标志，例如：wrangler pages dev -c wrangler.jsonc -c ../other-worker/wrangler.jsonc。第一个参数必须指向 Pages 配置文件，后续配置可通过 Pages 项目的 Service 绑定访问。

Queue Producers 使你可以在 Pages Function 内向队列发送消息。

要将队列绑定到 Pages Function，在 Pages Function 中使用 Wrangler 配置文件 或 Cloudflare 仪表板配置队列 producer 绑定：

通过 Cloudflare 仪表板配置队列 producer 绑定：

1. 在 Cloudflare 仪表板中，前往 Workers & Pages 页面。

   Go to Workers & Pages ↗

2. 选择你的 Pages 项目。

3. 前往 Settings（设置） > Bindings > Add（添加） > Queue。

4. 在 Variable name（变量名） 下为绑定命名。

5. 在 Queue（队列） 下，选择所需的队列。

6. 重新部署项目以使绑定生效。

以下是在 Function 中使用队列 producer 绑定的示例。此示例中，绑定名为 MY_QUEUE，可在 Function 代码中通过 context.env 访问该绑定：

export async function onRequest(context) {
	await context.env.MY_QUEUE.send({
		url: request.url,
		method: request.method,
		headers: Object.fromEntries(request.headers),
	});

	return new Response("Sent!");
}

interface Env {
	MY_QUEUE: Queue<any>;
}

export const onRequest: PagesFunction<Env> = async (context) => {
	await context.env.MY_QUEUE.send({
		url: request.url,
		method: request.method,
		headers: Object.fromEntries(request.headers),
	});

	return new Response("Sent!");
};

若 Pages Function 使用队列 producer 绑定，可在本地向队列发送事件。但无法使用 Pages Function 从队列消费事件。你必须创建带 队列 consumer 处理器 的独立 consumer Worker 来消费队列中的事件。Wrangler 尚不支持在本地将独立的 producer Function 和 consumer Worker 绑定到同一队列。

Hyperdrive 是一项服务，用于从 Cloudflare Workers 和 Pages Functions 连接现有数据库。

要将 Hyperdrive 配置绑定到 Pages Function，可在 Wrangler 配置文件 或 Cloudflare 仪表板中配置 Hyperdrive 绑定。

通过 Cloudflare 仪表板配置 Hyperdrive 绑定：

1. 在 Cloudflare 仪表板中，前往 Workers & Pages 页面。

   Go to Workers & Pages ↗

2. 选择你的 Pages 项目。

3. 前往 Settings（设置） > Bindings > Add（添加） > Hyperdrive。

4. 在 Variable name（变量名） 下为绑定命名。

5. 在 Hyperdrive configuration（Hyperdrive 配置） 下，选择所需配置。

6. 重新部署项目以使绑定生效。

以下是在 Function 中使用 Hyperdrive 的示例。以下示例中，Hyperdrive 配置名为 HYPERDRIVE，可在 Function 代码中通过 context.env 访问该绑定：

import postgres from "postgres";

export async function onRequest(context) {
	// create connection to postgres database
	const sql = postgres(context.env.HYPERDRIVE.connectionString);

	try {
		const result = await sql`SELECT id, name, value FROM records`;

		return Response.json({result: result})
	} catch (e) {
		return Response.json({error: e.message, {status: 500}});
	}
}

import postgres from "postgres";

interface Env {
	HYPERDRIVE: Hyperdrive;
}

type MyRecord = {
	id: number;
	name: string;
	value: string;
};

export const onRequest: PagesFunction<Env> = async (context) => {
	// create connection to postgres database
	const sql = postgres(context.env.HYPERDRIVE.connectionString);

	try {
		const result = await sql<MyRecord[]>`SELECT id, name, value FROM records`;

		return Response.json({result: result})
	} catch (e) {
		return Response.json({error: e.message, {status: 500}});
	}
};

要在本地与 Hyperdrive 绑定交互，必须提供 Pages 项目将直接连接的数据库的本地连接字符串。可设置环境变量 CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_<BINDING_NAME> 为数据库连接字符串，或在 Wrangler 文件中按 Hyperdrive 本地开发文档 为 Hyperdrive 绑定配置 localConnectionString。然后运行 npx wrangler pages dev <OUTPUT_DIR>。

Analytics Engine 绑定使你可以在 Pages Function 内写入分析数据。

要将 Analytics Engine 数据集绑定到 Pages Function，必须使用 Wrangler 配置文件 或 Cloudflare 仪表板配置 Analytics Engine 绑定：

通过 Cloudflare 仪表板配置 Analytics Engine 绑定：

1. 在 Cloudflare 仪表板中，前往 Workers & Pages 页面。

   Go to Workers & Pages ↗

2. 选择你的 Pages 项目。

3. 前往 Settings（设置） > Bindings > Add（添加） > Analytics engine。

4. 在 Variable name（变量名） 下为绑定命名。

5. 在 Dataset（数据集） 下，输入所需数据集。

6. 重新部署项目以使绑定生效。

以下是在 Function 中使用 Analytics Engine 绑定的示例。以下示例中，绑定名为 ANALYTICS_ENGINE，可在 Function 代码中通过 context.env 访问该绑定：

export async function onRequest(context) {
	const url = new URL(context.request.url);

	context.env.ANALYTICS_ENGINE.writeDataPoint({
		indexes: [],
		blobs: [url.hostname, url.pathname],
		doubles: [],
	});

	return new Response("Logged analytic");
}

interface Env {
	ANALYTICS_ENGINE: AnalyticsEngineDataset;
}

export const onRequest: PagesFunction<Env> = async (context) => {
	const url = new URL(context.request.url);

	context.env.ANALYTICS_ENGINE.writeDataPoint({
		indexes: [],
		blobs: [url.hostname, url.pathname],
		doubles: [],
	});

	return new Response("Logged analytic");
};

无法在本地使用 Analytics Engine 绑定。

环境变量 是 Function 可访问的注入值。环境变量是一种绑定，允许你将文本字符串或 JSON 值附加到 Pages Function。它以纯文本存储。在 Cloudflare 仪表板中为生产和预览环境在运行时和构建时直接设置环境变量。

要向 Pages 项目添加环境变量，可使用 Wrangler 配置文件 或 Cloudflare 仪表板。

通过 Cloudflare 仪表板配置环境变量：

1. 在 Cloudflare 仪表板中，前往 Workers & Pages 页面。

   Go to Workers & Pages ↗

2. 选择你的 Pages 项目。

3. 前往 Settings（设置） > Variables and Secrets > Add（添加）。

4. 设置变量名和值后，选择 Save（保存）。

以下是在 Function 中使用环境变量的示例。此示例中的环境变量为 ENVIRONMENT，可在 context.env 上访问该环境变量：

export function onRequest(context) {
	if (context.env.ENVIRONMENT === "development") {
		return new Response("This is a local environment!");
	} else {
		return new Response("This is a live environment");
	}
}

interface Env {
	ENVIRONMENT: string;
}

export const onRequest: PagesFunction<Env> = async (context) => {
	if (context.env.ENVIRONMENT === "development") {
		return new Response("This is a local environment!");
	} else {
		return new Response("This is a live environment");
	}
};

可通过以下两种方式在本地与环境变量交互：

• 配置 Pages 项目的 Wrangler 文件并运行 npx wrangler pages dev。
• 直接向 wrangler pages dev 传递参数。

若要通过 Wrangler CLI 在本地与环境变量交互，向 wrangler pages dev 命令添加 --binding=<ENVIRONMENT_VARIABLE_NAME>=<ENVIRONMENT_VARIABLE_VALUE>：

npx wrangler pages dev --binding=<ENVIRONMENT_VARIABLE_NAME>=<ENVIRONMENT_VARIABLE_VALUE>

Secrets 是一种绑定，允许你将加密文本值附加到 Pages Function。设置后无法查看 secrets，只能通过 context.env 以编程方式访问。Secrets 用于存储 API 密钥和 auth token 等敏感信息。

要向 Pages 项目添加 secrets：

1. 在 Cloudflare 仪表板中，前往 Workers & Pages 页面。

   Go to Workers & Pages ↗

2. 选择你的 Pages 项目。

3. 前往 Settings（设置） > Variables and Secrets > Add（添加）。

4. 设置变量名和值。

5. 选择 Encrypt（加密） 创建 secret。

6. 选择 Save（保存）。

使用 secrets 的方式与环境变量相同。使用 Wrangler 或在 Cloudflare 仪表板中设置 secrets 时，必须在部署使用这些 secrets 之前完成。更多指导请参阅 环境变量。

将本地开发使用的 secrets 放在 .dev.vars 文件或 .env 文件中，与 Wrangler 配置文件位于同一目录。

这些文件应使用 dotenv ↗ 语法格式化。例如：

SECRET_KEY="value"
API_TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9"

要为每个 Cloudflare 环境设置不同的 secrets，请创建名为 .dev.vars.<environment-name> 或 .env.<environment-name> 的文件。

在本地开发中选择 Cloudflare 环境时，会先加载对应的环境特定文件，再加载通用的 .dev.vars（或 .env）文件。

• 使用 .dev.vars.<environment-name> 文件时，每个环境必须定义所有 secrets。如果存在 .dev.vars.<environment-name>，则只会加载该文件；不会加载 .dev.vars 文件。
• 相比之下，所有匹配的 .env 文件都会被加载，值会被合并。对于每个变量，使用最特定文件中的值，优先级如下：
  • .env.<environment-name>.local（最特定）
  • .env.local
  • .env.<environment-name>
  • .env（最不特定）