プレビュー URL を使うと、本番にデプロイせずに Worker の新しいバージョンを確認できます。
プレビュー URL には 2 種類あります。
- バージョン付きプレビュー URL: Worker の新しいバージョンごとに自動生成される一意の URL です。
- エイリアス付きプレビュー URL: Worker バージョンに手動で割り当てる、固定の読みやすいエイリアスです。
どちらのプレビュー URL も、形式は <VERSION_PREFIX OR ALIAS>-<WORKER_NAME>.<SUBDOMAIN>.workers.dev です。
プレビュー URL は次のように使えます。
- CI/CD パイプラインに組み込み、プルリクエストごとにプレビュー環境を自動生成する。
- チーム間で連携し、ライブ環境でコード変更をテストして更新内容を確認する。
- 新しい API エンドポイントのテスト、データ形式の検証、既存サービスとの後方互換性の確認。
バージョンに対してゾーンレベルのパフォーマンス機能やセキュリティ機能をテストする場合は、ゾーンのパフォーマンス設定とセキュリティ設定が適用されるよう、バージョンオーバーライド の利用を推奨します。
Worker の新しい バージョン を作成するたびに、一意の静的なバージョンプレビュー URL が自動生成されます。これらの URL はバージョンプレフィックスを使い、形式は <VERSION_PREFIX>-<WORKER_NAME>.<SUBDOMAIN>.workers.dev です。
Worker の新しいバージョンは、次のいずれかを実行したときに作成されます。
wrangler deploywrangler versions upload- Cloudflare ダッシュボードでの編集
プレビュー URL が有効な場合、バージョン作成直後から公開され、すぐに利用できます。
wrangler versions upload コマンドは、Worker の新しい バージョン をアップロードし、アップロードした各バージョンのプレビュー URL を返します。
-
Cloudflare ダッシュボードで Workers & Pages ページを開きます。
Workers & Pages を開く ↗ -
Worker を選びます。
-
Deployments タブを開き、確認したいバージョンを探します。
エイリアス付きプレビュー URL では、特定の Worker バージョンに、持続する読みやすいエイリアスを割り当てられます。多くのバージョンをまたいで安定したプレビューへリンクしたい場合に便利です（例: 開発中の新機能を共有する）。よくある流れは、作業中のブランチにエイリアスを割り当てることです。この種類のプレビュー URL も、ほかのプレビュー URL と同じパターンです。
<ALIAS>-<WORKER_NAME>.<SUBDOMAIN>.workers.dev
エイリアスは versions upload の実行時に作成できます。有効なエイリアス名を --preview-alias フラグで指定します。
wrangler versions upload --preview-alias staging作成したエイリアスはこのバージョンに結び付き、次の URL ですぐに利用できます。
staging-<WORKER_NAME>.<SUBDOMAIN>.workers.dev
- エイリアスは、バージョンのアップロード時にだけ作成できます。
- エイリアスに使える文字は、小文字、数字、ハイフンだけです。
- エイリアスは小文字で始める必要があります。
- エイリアスと Worker 名をハイフンでつないだ長さは、DNS ラベル制限のため 63 文字以下である必要があります。
- 保持されるのは、直近にデプロイした 1000 個のエイリアスだけです。この上限を超えて新しいエイリアスを作成すると、最も古いエイリアスが削除されます。
有効にすると、プレビュー URL は公開されます。訪問者にサインインを必須にするには、Cloudflare Access を使います。
Access は、1 つの Worker のプレビュー、またはアカウント内のすべての Worker のプレビューを保護できます。本番デプロイとプレビューデプロイの両方を保護することもできます。
サインインしたユーザーの情報を Worker 内で使うには、検証済み JWT、または /cdn-cgi/access/get-identity エンドポイントから ユーザーの ID を読み取ります。
次の点に注意してください。
workers_devが有効な場合、プレビュー URL はデフォルトで有効です。workers_devが無効な場合、プレビュー URL はデフォルトで無効です。- プレビュー URL を無効にすると、バージョン付きプレビュー URL とエイリアス付きプレビュー URL の両方へのルーティングが無効になります。
Worker のプレビュー URL を切り替えるには、次の手順を行います。
-
Cloudflare ダッシュボードで Workers & Pages ページを開きます。
Workers & Pages を開く ↗ -
Overview で Worker を選びます。
-
Settings > Domains & Routes を開きます。
-
Preview URLs で Enable または Disable を選びます。
-
操作を確認します。
Worker のプレビュー URL を切り替えるには、Worker の Wrangler ファイルに次のいずれかを含めます。
{
"preview_urls": true
}preview_urls = true{
"preview_urls": false
}preview_urls = false指定しない場合のデフォルトは preview_urls = workers_dev です。
- Durable Object を実装している Worker（Containers および Sandbox Worker を含む）では、プレビュー URL は生成されません。Containers のテスト方法は、Containers のデプロイ を参照してください。
- Workers for Platforms の user Workers では、現時点でプレビュー URL は生成されません。一時的な制限であり、解消に向けて作業中です。
- プレビュー URL を
workers.dev以外のサブドメインで動かす設定は、現時点ではできません。 - 現時点では、プレビュー URL のログは確認できません。Workers Logs、Wrangler tail、Logpush も対象です。