Pages から Workers へ移行する

Cloudflare Workers では、フロントエンドの静的アセットとバックエンド API、サーバーサイドレンダリング（SSR）を含むフルスタックアプリケーションをデプロイできます。

Pages と同様に、Workers 上の静的アセットへのリクエストは無料です。Pages Functions の呼び出しは Workers と同じ料金なので、同程度のコスト構成 になります。

Pages と異なり、Workers は使える機能の幅がはっきり広くなります（Durable Objects、Cron Triggers、より充実したオブザーバビリティなど）。一覧は このページの末尾 にあります。

Cloudflare Pages から Cloudflare Workers への移行は、多くの場合シンプルです。プロジェクトの移行でよく行う手順は次のとおりです。

Pages プロジェクトが よく使われるフレームワーク を使っている場合、ほとんどのフレームワークには Cloudflare Workers 向けのアダプターがあります。Pages 専用のアダプターを Workers 向けに差し替え、各アダプターの案内に従ってください。

プロジェクトにまだない場合は、プロジェクトのルートに Wrangler 設定ファイル（wrangler.jsonc、wrangler.json、または wrangler.toml）を作成します。必須フィールドは次の 2 つです。

• name

  デプロイ先の Worker 名を設定します。既存の Pages プロジェクト名と同じにできます。ただし Workers の名前制限（最大長など）に従う必要があります。

• compatibility_date.

  すでに Pages Functions を使っていた場合は、そこで設定した日付と同じにします。そうでなければ、現在の日付を設定します。

Pages では「ビルド出力ディレクトリ」を設定していました（Wrangler 設定ファイル または Cloudflare ダッシュボード）。Worker プロジェクトでは、代わりに assets.directory を設定します。

以前（Cloudflare Pages）:

{
	"name": "my-pages-project",
	"pages_build_output_dir": "./dist/client/"
}

name = "my-pages-project"
pages_build_output_dir = "./dist/client/"

現在（Cloudflare Workers）:

{
	"name": "my-worker",
	// Set this to today's date
	"compatibility_date": "2026-09-20",
	"assets": {
		"directory": "./dist/client/"
	}
}

name = "my-worker"
# Set this to today's date
compatibility_date = "2026-09-20"

[assets]
directory = "./dist/client/"

Pages は、デプロイしたプロジェクトの種類を自動で判断しようとしていました。404.html と index.html の有無を手がかりに、シングルページアプリケーション（SPA） か、カスタム 404 ページを配信するか を推測していました。

Workers では、誤設定を防ぐため、この動作は明示的で、手動で設定する 必要があります。

シングルページアプリケーション（SPA）の場合:

{
	"name": "my-worker",
	// Set this to today's date
	"compatibility_date": "2026-09-20",
	"assets": {
		"directory": "./dist/client/",
		"not_found_handling": "single-page-application"
	}
}

name = "my-worker"
# Set this to today's date
compatibility_date = "2026-09-20"

[assets]
directory = "./dist/client/"
not_found_handling = "single-page-application"

カスタム 404 ページの場合:

{
	"name": "my-worker",
	// Set this to today's date
	"compatibility_date": "2026-09-20",
	"assets": {
		"directory": "./dist/client/",
		"not_found_handling": "404-page"
	}
}

name = "my-worker"
# Set this to today's date
compatibility_date = "2026-09-20"

[assets]
directory = "./dist/client/"
not_found_handling = "404-page"

Pages は、node_modules、.DS_Store、.git など一部のファイルとフォルダーを静的アセットとしてアップロードしないようにしていました。Workers でもこれらのファイルをアップロードしたくない場合は、プロジェクトの静的アセットディレクトリに .assetsignore ファイル を作成します。

**/node_modules
**/.DS_Store
**/.git

Pages Functions で動くフルスタックフレームワークを使っている場合は、フレームワーク を Pages ではなく Workers 向けに更新してください。

"advanced mode" の _worker.js ファイル を使う Pages Functions の場合は、まずこのスクリプトが静的アセットとしてアップロードされないようにします。_worker.js を静的アセットディレクトリの外へ移す（推奨）か、静的アセットディレクトリに .assetsignore ファイル を作成して _worker.js を含めます。

_worker.js

次に、設定ファイルの main フィールドを、この Worker スクリプトの場所に向けます。

{
	"name": "my-worker",
	// Set this to today's date
	"compatibility_date": "2026-09-20",
	"main": "./dist/client/_worker.js", // or some other location if you moved the script out of the static asset directory
	"assets": {
		"directory": "./dist/client/"
	}
}

name = "my-worker"
# Set this to today's date
compatibility_date = "2026-09-20"
main = "./dist/client/_worker.js"

[assets]
directory = "./dist/client/"

フォルダーの functions/ を使う Pages Functions の場合は、まず wrangler pages functions build コマンドで、これらの関数を 1 つの Worker スクリプトにコンパイルします。

npx wrangler pages functions build --outdir=./dist/worker/

yarn wrangler pages functions build --outdir=./dist/worker/

pnpm wrangler pages functions build --outdir=./dist/worker/

このコマンドはいつでも実行できますが、ファイルベースのルーティングを続けたい場合は、別のフレームワークの利用を検討してください。HonoX ↗ はよく使われる選択肢の 1 つです。

Worker スクリプトをコンパイルしたら、設定ファイルの main フィールドを、ビルド先の場所に向けます。

{
	"name": "my-worker",
	// Set this to today's date
	"compatibility_date": "2026-09-20",
	"main": "./dist/worker/index.js",
	"assets": {
		"directory": "./dist/client/"
	}
}

name = "my-worker"
# Set this to today's date
compatibility_date = "2026-09-20"
main = "./dist/worker/index.js"

[assets]
directory = "./dist/client/"

Pages プロジェクトで _routes.json ファイル を書いた場合、または Pages Functions で ミドルウェア を使っていた場合は、Worker スクリプトの設定に注意してください。Pages はデフォルトで静的アセットより先に Pages Functions を配信し、_routes.json と Pages Functions のミドルウェアでこの動作をカスタマイズできました。

一方 Workers は、assets.run_worker_first を設定しない限り、Worker スクリプトより先に静的アセットを配信します。静的アセットを配信する前に認証チェックやリクエストのログを行う場合などには、このオプションが必要です。

{
	"name": "my-worker",
	// Set this to today's date
	"compatibility_date": "2026-09-20",
	"main": "./dist/worker/index.js",
	"assets": {
		"directory": "./dist/client/",
		"run_worker_first": true
	}
}

name = "my-worker"
# Set this to today's date
compatibility_date = "2026-09-20"
main = "./dist/worker/index.js"

[assets]
directory = "./dist/client/"
run_worker_first = true

希望すれば、新しい Worker スクリプトをゼロから書き、Wrangler と最新ランタイムの機能（例: WorkerEntrypoint、TypeScript 対応、バンドル など）を活かせます。

import { WorkerEntrypoint } from "cloudflare:workers";

export default class extends WorkerEntrypoint {
	async fetch(request) {
		return new Response("Hello, world!");
	}
}

import { WorkerEntrypoint } from "cloudflare:workers";

export default class extends WorkerEntrypoint {
	async fetch(request: Request) {
		return new Response("Hello, world!");
	}
}

{
	"name": "my-worker",
	// Set this to today's date
	"compatibility_date": "2026-09-20",
	"main": "./worker/index.ts",
	"assets": {
		"directory": "./dist/client/"
	}
}

name = "my-worker"
# Set this to today's date
compatibility_date = "2026-09-20"
main = "./worker/index.ts"

[assets]
directory = "./dist/client/"

Pages は、Pages Functions から静的アセットへアクセスするための ASSETS バインディング を自動で提供していました。Workers では、このバインディング名はカスタマイズでき、手動で設定する必要があります。

{
	"name": "my-worker",
	// Set this to today's date
	"compatibility_date": "2026-09-20",
	"main": "./worker/index.ts",
	"assets": {
		"directory": "./dist/client/",
		"binding": "ASSETS"
	}
}

name = "my-worker"
# Set this to today's date
compatibility_date = "2026-09-20"
main = "./worker/index.ts"

[assets]
directory = "./dist/client/"
binding = "ASSETS"

Pages プロジェクトで 配置 をカスタマイズしていた場合、または compatibility date や compatibility flags を設定していた場合は、Wrangler 設定ファイルで同じ内容を定義できます。

{
	"name": "my-worker",
	// Set this to today's date
	"compatibility_date": "2026-09-20",
	"compatibility_flags": ["nodejs_compat"],
	"main": "./worker/index.ts",
	"placement": {
		"mode": "smart"
	},
	"assets": {
		"directory": "./dist/client/",
		"binding": "ASSETS"
	}
}

name = "my-worker"
# Set this to today's date
compatibility_date = "2026-09-20"
compatibility_flags = [ "nodejs_compat" ]
main = "./worker/index.ts"

[placement]
mode = "smart"

[assets]
directory = "./dist/client/"
binding = "ASSETS"

変数 と バインディング は Wrangler 設定ファイル で設定でき、Worker の環境（env）から使えます。シークレット は Wrangler でアップロードするか、Cloudflare ダッシュボードで 本番用 に定義し、ローカル開発では .dev.vars を使います。

Workers Builds を使っている 場合は、ビルド環境に関連する変数もそこで設定 してください。Pages と異なり、Workers はランタイム変数とビルド時変数を同じセットでは共有しません。

以前は wrangler pages dev と wrangler pages deploy を使っていました。代わりに wrangler dev と wrangler deploy を使います。加えて、Vite ベースのフレームワークを使っている場合は、新しい Vite plugin で開発体験をさらにシンプルにできることがあります。

Pages 組み込みの CI/CD を使っている場合は、まず リポジトリを Workers Builds に接続 し、次に Pages プロジェクトの自動デプロイを無効化 して、Workers Builds に切り替えられます。

Pages はプロジェクトごとにプレビュー環境を自動作成し、独立して設定できます。

Workers で近い体験を得るには、次を行います。

1. プレビュー URL が有効であることを確認します（デフォルトでオンです）。

   {
   	"name": "my-worker",
   	// Set this to today's date
   	"compatibility_date": "2026-09-20",
   	"main": "./worker/index.ts",
   	"assets": {
   		"directory": "./dist/client/"
   	},
   	"preview_urls": true
   }

   name = "my-worker"
   # Set this to today's date
   compatibility_date = "2026-09-20"
   main = "./worker/index.ts"
   preview_urls = true
   
   [assets]
   directory = "./dist/client/"

2. Workers Builds で 非本番ブランチのビルドを有効 にします。

任意で、これらのプレビュー URL を Cloudflare Access で保護 することもできます。

_headers と _redirects ファイルは、静的アセット付きの Workers でネイティブに使えます。Pages と同様に、これらのファイルをプロジェクトの静的アセットディレクトリに含めてください。

以前は Pages プロジェクトに pages.dev サブドメインが提供されていました。現在は、すべての Worker プロジェクト向けに、個人用の workers.dev サブドメインを設定できます。このサブドメインは Cloudflare ダッシュボードで設定 でき、設定ファイルの workers_dev オプション で利用を選択できます。

{
	"name": "my-worker",
	// Set this to today's date
	"compatibility_date": "2026-09-20",
	"main": "./worker/index.ts",
	"workers_dev": true
}

name = "my-worker"
# Set this to today's date
compatibility_date = "2026-09-20"
main = "./worker/index.ts"
workers_dev = true

ドメインのネームサーバーが Cloudflare 管理なら、Pages と同様に Worker へ カスタムドメイン を設定できます。一部のパスだけを Worker で配信したい場合は、ルート も設定できます。

Worker の動作を確認し、開発ワークフローに納得し、本番トラフィックをすべて移行したら、Cloudflare ダッシュボードまたは Wrangler で Pages プロジェクトを削除できます。

npx wrangler pages project delete

yarn wrangler pages project delete

pnpm wrangler pages project delete

好みのコーディングアシスタント（例: Claude Code、Cursor）に、次の 実験的なプロンプト ↗ を追加すると、プロジェクトを Workers 向けにできます。

https://developers.cloudflare.com/workers/prompts/pages-to-workers.txt

コーディングアシスタントで Cloudflare ドキュメントの MCP server ↗ を使うと、Workers での構築時に LLM へよりよいコンテキストを渡せます。Pages から Workers への移行を依頼すると、このプロンプトが含まれます。

この互換性マトリクスは、Workers と Pages の機能を比較します。以下に特記がない限り、Pages で動くものは Workers でも動き、Workers で動くものは Pages でも動きます。この一覧に不足があると思ったら、プルリクエストを開く ↗ か GitHub issue を作成 ↗ してください。

凡例
✅: 対応
⏳: 近日対応
🟡: 非対応（回避策あり）
❌: 非対応