バインディング

バインディングを使うと、Pages Functions から Cloudflare 開発者プラットフォーム上のリソースと連携できます。バインディングで、Pages Functions を KV、Durable Objects、R2、D1 などの Cloudflare リソースに統合できます。本番環境とプレビュー環境の両方にバインディングを設定できます。

このガイドでは、Pages Function 向けのバインディング設定手順を説明します。続けるには、Cloudflare Developer Platform のリソースをあらかじめ用意しておく必要があります。

KV namespaces

Workers KV は、Cloudflare のキーバリューストレージです。

KV namespace を Pages Function にバインドするには、Wrangler 設定ファイルまたは Cloudflare ダッシュボードで KV namespace バインディングを設定します。

Cloudflare ダッシュボードで KV namespace バインディングを設定するには、次の手順を実行します。

Cloudflare ダッシュボードで Workers & Pages ページを開きます。
Workers & Pages を開く ↗
Pages プロジェクトを選びます。
Settings > Bindings > Add > KV namespace を開きます。
Variable name にバインディング名を入力します。
KV namespace で、使いたい namespace を選びます。
バインディングを反映するために、プロジェクトを再デプロイします。

次は、Function で KV を使う例です。この例では KV namespace バインディング名は 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 namespaces を操作する

KV namespace バインディングをローカルで操作する方法は、次の 2 つです。

Pages プロジェクトの Wrangler ファイルを設定し、npx wrangler pages dev を実行する。
引数を wrangler pages dev に直接渡す。

Wrangler CLI に引数を渡してローカルで KV namespace バインディングを操作するには、wrangler pages dev コマンドに -k <BINDING_NAME> または --kv=<BINDING_NAME> を追加します。たとえば、Function が TODO_LIST バインディングで KV namespace に接続している場合、次のコマンドでローカル開発から KV namespace にアクセスできます。

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

Durable Objects

Durable Objects（DO）は、WebSockets の接続や状態の処理などの機能を支える、Cloudflare の強い一貫性を持つデータストアです。

Durable Object Worker を作成し、Cloudflare ダッシュボードまたは Pages プロジェクトの Wrangler 設定ファイルで Pages プロジェクトにバインドする必要があります。Pages プロジェクト内で Durable Object を作成してデプロイすることはできません。

Durable Object を Pages Function にバインドするには、Wrangler 設定ファイルまたは Cloudflare ダッシュボードで Durable Object バインディングを設定します。

Cloudflare ダッシュボードで Durable Object バインディングを設定するには、次の手順を実行します。

Cloudflare ダッシュボードで Workers & Pages ページを開きます。
Workers & Pages を開く ↗
Pages プロジェクトを選びます。
Settings > Bindings > Add > Durable Object を開きます。
Variable name にバインディング名を入力します。
Durable Object namespace で、使いたい namespace を選びます。
バインディングを反映するために、プロジェクトを再デプロイします。

次は、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 namespaces を操作する

Durable Object バインディングをローカルで操作する方法は、次の 2 つです。

Pages プロジェクトの Wrangler ファイルを設定し、npx wrangler pages dev を実行する。
引数を wrangler pages dev に直接渡す。

ローカル開発で Durable Object namespace を操作するには、Durable Object をエクスポートしている Worker のディレクトリで wrangler dev を実行します。別のターミナルで、Pages プロジェクトのディレクトリから wrangler pages dev を実行します。

Wrangler CLI でローカルの Durable Object namespace を操作するには、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（例: context.env.MY_DO）で MY_DO バインディングを操作します。

R2 buckets

R2 は、エグレス料金なしで大量の非構造化データを保存できる、Cloudflare のブロブストレージです。

R2 バケットを Pages Function にバインドするには、Wrangler 設定ファイルまたは Cloudflare ダッシュボードで R2 バケットバインディングを設定します。

Cloudflare ダッシュボードで R2 バケットバインディングを設定するには、次の手順を実行します。

Cloudflare ダッシュボードで Workers & Pages ページを開きます。
Workers & Pages を開く ↗
Pages プロジェクトを選びます。
Settings > Bindings > Add > R2 bucket を開きます。
Variable name にバインディング名を入力します。
R2 bucket で、使いたい R2 バケットを選びます。
バインディングを反映するために、プロジェクトを再デプロイします。

次は、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 バケットを操作する

R2 バケットバインディングをローカルで操作する方法は、次の 2 つです。

Pages プロジェクトの Wrangler ファイルを設定し、npx wrangler pages dev を実行する。
引数を wrangler pages dev に直接渡す。

Wrangler CLI でローカルの R2 バケットを操作するには、wrangler pages dev コマンドに --r2=<BINDING_NAME> を追加します。Function が BUCKET バインディングで R2 バケットに接続している場合、次のコマンドでローカル開発からこの R2 バケットにアクセスできます。

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

このバインディングは context.env（例: context.env.BUCKET）で操作します。

D1 databases

D1 は、Cloudflare のネイティブサーバーレスデータベースです。

D1 データベースを Pages Function にバインドするには、Wrangler 設定ファイルまたは Cloudflare ダッシュボードで D1 データベースバインディングを設定します。

Cloudflare ダッシュボードで D1 データベースバインディングを設定するには、次の手順を実行します。

Cloudflare ダッシュボードで Workers & Pages ページを開きます。
Workers & Pages を開く ↗
Pages プロジェクトを選びます。
Settings > Bindings > Add> D1 database bindings を開きます。
Variable name にバインディング名を入力します。
D1 database で、使いたい D1 データベースを選びます。
バインディングを反映するために、プロジェクトを再デプロイします。

次は、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 データベースを操作する

D1 データベースバインディングをローカルで操作する方法は、次の 2 つです。

Pages プロジェクトの Wrangler ファイルを設定し、npx wrangler pages dev を実行する。
引数を wrangler pages dev に直接渡す。

ローカル開発中に Wrangler CLI で D1 データベースを操作するには、wrangler pages dev コマンドに --d1 <BINDING_NAME>=<DATABASE_ID> を追加します。

Pages Function が NORTHWIND_DB バインディングで D1 データベースに接続していて、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 indexes

Vectorize は、Cloudflare のネイティブベクトルデータベースです。

Vectorize インデックスを Pages Function にバインドするには、Wrangler 設定ファイルまたは Cloudflare ダッシュボードで Vectorize インデックスバインディングを設定します。

Cloudflare ダッシュボードで Vectorize インデックスバインディングを設定するには、次の手順を実行します。

Cloudflare ダッシュボードで Workers & Pages ページを開きます。
Workers & Pages を開く ↗
Production 環境と Preview 環境のどちらにバインディングを設定するかを選びます。
Pages プロジェクトを選び、Settings を開きます。
Bindings > Add > Vectorize index を開きます。
Variable name にバインディング名を入力します。
Vectorize index で、使いたい Vectorize インデックスを選びます。
バインディングを反映するために、プロジェクトを再デプロイします。

Vectorize インデックスバインディングを使う

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

Workers AI を使うと、サーバーレス GPU を使って、Cloudflare のグローバルネットワーク上で機械学習モデルを実行できます。

Workers AI を Pages Function にバインドするには、Wrangler 設定ファイルまたは Cloudflare ダッシュボードで Workers AI バインディングを設定します。

Wrangler でローカル開発する場合は、--ai フラグで AI バインディングを定義できます。wrangler pages dev --ai AI を実行して Wrangler を開発モードで起動すると、context.env.AI バインディングを公開できます。

Cloudflare ダッシュボードで Workers AI バインディングを設定するには、次の手順を実行します。

Workers & Pages ページを開きます。
Workers & Pages を開く ↗
Pages プロジェクトを選び、Settings を開きます。
Pages 環境を選び、Bindings > Add > Workers AI を開きます。
Variable name にバインディング名を入力します。
バインディングを反映するために、プロジェクトを再デプロイします。

Workers AI バインディングを使う

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 バインディングを操作する

Workers AI バインディングをローカルで操作する方法は、次の 2 つです。

Pages プロジェクトの Wrangler ファイルを設定し、npx wrangler pages dev を実行する。
引数を wrangler pages dev に直接渡す。

ローカル開発中に Wrangler CLI で Workers AI バインディングを操作するには、次のコマンドを実行します。

npx wrangler pages dev --ai=<BINDING_NAME>

Service bindings

Service bindings を使うと、Pages Function 内から Worker を呼び出せます。

Pages Function を Worker にバインドするには、Wrangler 設定ファイルまたは Cloudflare ダッシュボードで Service binding を設定します。

Cloudflare ダッシュボードで Service binding を設定するには、次の手順を実行します。

Cloudflare ダッシュボードで Workers & Pages ページを開きます。
Workers & Pages を開く ↗
Pages プロジェクトを選びます。
Settings > Bindings > Add > Service binding を開きます。
Variable name にバインディング名を入力します。
Service で、使いたい Worker を選びます。
バインディングを反映するために、プロジェクトを再デプロイします。

次は、Function で Service bindings を使う例です。この例では Service binding 名は 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 bindings を操作する

Service bindings をローカルで操作する方法は、次の 2 つです。

Pages プロジェクトの Wrangler ファイルを設定し、npx wrangler pages dev を実行する。
引数を wrangler pages dev に直接渡す。

ローカル開発中に Service binding を操作するには、バインド先の Worker を wrangler dev で実行し、並行して wrangler pages dev を --service <BINDING_NAME>=<SCRIPT_NAME> 付きで実行します。SCRIPT_NAME は Worker の名前です。たとえば Worker 名が my-worker の場合、（Worker のディレクトリで）npx wrangler dev を実行し、同時に（Pages のディレクトリで）npx wrangler pages dev <OUTPUT_DIR> --service MY_SERVICE=my-worker を実行して接続します。このバインディングは context.env（例: context.env.MY_SERVICE）で操作します。

Cloudflare ダッシュボードで Service binding を設定した場合は、wrangler pages dev に --service <BINDING_NAME>=<SCRIPT_NAME> を付ける必要があります。BINDING_NAME は Service binding の名前、SCRIPT_NAME は Worker の名前です。

たとえばローカル開発では、Worker 名が my-worker の場合、my-worker ディレクトリで npx wrangler dev を実行します。別のターミナルで、Pages プロジェクトのディレクトリから npx wrangler pages dev <OUTPUT_DIR> --service MY_SERVICE=my-worker も実行します。この Service binding は context.env（例: context.env.MY_SERVICE）で操作します。

Wrangler は、1 つのコマンドで Pages プロジェクトとバインドした Worker を同じ開発セッションで実行することもできます。試すには、次のように複数の -c フラグを Wrangler に渡します。wrangler pages dev -c wrangler.jsonc -c ../other-worker/wrangler.jsonc。最初の引数は Pages の設定ファイルを指す必要があり、それ以降の設定は Pages プロジェクトから Service binding 経由でアクセスできます。

Queue Producers

Queue Producers を使うと、Pages Function 内からキューへメッセージを送信できます。

キューを Pages Function にバインドするには、Wrangler 設定ファイルまたは Cloudflare ダッシュボードで queue producer バインディングを設定します。

Cloudflare ダッシュボードで queue producer バインディングを設定するには、次の手順を実行します。

Cloudflare ダッシュボードで Workers & Pages ページを開きます。
Workers & Pages を開く ↗
Pages プロジェクトを選びます。
Settings > Bindings > Add > Queue を開きます。
Variable name にバインディング名を入力します。
Queue で、使いたいキューを選びます。
バインディングを反映するために、プロジェクトを再デプロイします。

次は、Function で queue 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!");
};

ローカルで Queue Producer バインディングを操作する

Pages Function で queue producer バインディングを使う場合、ローカルからキューへイベントを送信できます。ただし、Pages Function でキューからイベントを消費することはできません。キューからイベントを消費するには、queue consumer ハンドラーを持つ別の consumer Worker を作成する必要があります。Wrangler は、同じキューにバインドした producer Function と consumer Worker をローカルで別々に実行することには、まだ対応していません。

Hyperdrive configs

Note

Postgres.js ↗ のような PostgreSQL ドライバーは Node.js API に依存します。Hyperdrive バインディングを使う Pages Functions は、Node.js 互換モードでデプロイする必要があります。

{
	"compatibility_flags": [
		"nodejs_compat"
	],
	// Set this to today's date
	"compatibility_date": "2026-09-20"
}

compatibility_flags = [ "nodejs_compat" ]
# Set this to today's date
compatibility_date = "2026-09-20"

Hyperdrive は、既存のデータベースへ Cloudflare Workers と Pages Functions から接続するためのサービスです。

Hyperdrive 設定を Pages Function にバインドするには、Wrangler 設定ファイルまたは Cloudflare ダッシュボードで Hyperdrive バインディングを設定します。

Cloudflare ダッシュボードで Hyperdrive バインディングを設定するには、次の手順を実行します。

Cloudflare ダッシュボードで Workers & Pages ページを開きます。
Workers & Pages を開く ↗
Pages プロジェクトを選びます。
Settings > Bindings > Add > Hyperdrive を開きます。
Variable name にバインディング名を入力します。
Hyperdrive configuration で、使いたい設定を選びます。
バインディングを反映するために、プロジェクトを再デプロイします。

次は、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 バインディングを操作する

Hyperdrive バインディングをローカルで操作するには、Pages プロジェクトが直接接続するデータベースのローカル接続文字列を指定する必要があります。環境変数 CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_<BINDING_NAME> にデータベースの接続文字列を設定するか、Hyperdrive のローカル開発ドキュメントの手順どおり Wrangler ファイルで Hyperdrive バインディングに localConnectionString を設定します。そのあと、npx wrangler pages dev <OUTPUT_DIR> を実行します。

Analytics Engine

Analytics Engine バインディングを使うと、Pages Function 内で分析データを書き込めます。

Analytics Engine データセットを Pages Function にバインドするには、Wrangler 設定ファイルまたは Cloudflare ダッシュボードで Analytics Engine バインディングを設定する必要があります。

Cloudflare ダッシュボードで Analytics Engine バインディングを設定するには、次の手順を実行します。

Cloudflare ダッシュボードで Workers & Pages ページを開きます。
Workers & Pages を開く ↗
Pages プロジェクトを選びます。
Settings > Bindings > Add > Analytics engine を開きます。
Variable name にバインディング名を入力します。
Dataset に、使いたいデータセットを入力します。
バインディングを反映するために、プロジェクトを再デプロイします。

次は、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 バインディングを操作する

Analytics Engine バインディングはローカルでは使えません。

環境変数

環境変数は、Functions からアクセスできる注入値です。環境変数はバインディングの一種で、テキスト文字列や JSON 値を Pages Function に付けられます。平文で保存されます。本番環境とプレビュー環境の両方について、ランタイム時とビルド時の環境変数を Cloudflare ダッシュボードで直接設定します。

Pages プロジェクトに環境変数を追加するには、Wrangler 設定ファイルまたは Cloudflare ダッシュボードを使えます。

Cloudflare ダッシュボードで環境変数を設定するには、次の手順を実行します。

Cloudflare ダッシュボードで Workers & Pages ページを開きます。
Workers & Pages を開く ↗
Pages プロジェクトを選びます。
Settings > Variables and Secrets > Add を開きます。
変数名と値を設定したあと、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");
	}
};

ローカルで環境変数を操作する

環境変数をローカルで操作する方法は、次の 2 つです。

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（シークレット）

Secrets はバインディングの一種で、暗号化されたテキスト値を Pages Function に付けられます。設定後に Secrets の内容は確認できず、context.env からプログラムでアクセスするだけです。Secrets は、API キーや認証トークンなどの機密情報の保存に使います。

Pages プロジェクトに Secrets を追加するには、次の手順を実行します。

Cloudflare ダッシュボードで Workers & Pages ページを開きます。
Workers & Pages を開く ↗
Pages プロジェクトを選びます。
Settings > Variables and Secrets > Add を開きます。
変数名と値を設定します。
Encrypt を選び、Secret を作成します。
Save を選びます。

Secrets の使い方は環境変数と同じです。Wrangler または Cloudflare ダッシュボードで Secrets を設定する場合は、その Secrets を使うデプロイより前に行う必要があります。詳細は環境変数を参照してください。

Secrets を使ったローカル開発

ローカル開発で使うシークレットは、Wrangler 設定ファイルと同じディレクトリの .dev.vars または .env に置きます。

これらのファイルは dotenv ↗ の構文で記述します。例:

.dev.vars / .envbash

SECRET_KEY="value"
API_TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9"

Cloudflare 環境ごとに異なるシークレットを設定するには、.dev.vars.<environment-name> または .env.<environment-name> という名前のファイルを作成します。

ローカル開発で Cloudflare 環境を選ぶと、対応する環境固有のファイルが、汎用の .dev.vars（または .env）より先に読み込まれます。

.dev.vars.<environment-name> を使う場合、すべてのシークレットを環境ごとに定義する必要があります。.dev.vars.<environment-name> が存在すると、そのファイルだけが読み込まれ、.dev.vars は読み込まれません。
一方、一致する .env ファイルはすべて読み込まれ、値がマージされます。各変数には、もっとも具体的なファイルの値が使われます。優先順位は次のとおりです。
- .env.<environment-name>.local（もっとも具体的）
- .env.local
- .env.<environment-name>
- .env（もっとも汎用）