ゼロからのデプロイ

リポジトリベースの Worker をゼロからプロビジョニングする -- ダッシュボードウィザードの罠、wrangler deploy、.assetsignore、CI トークン権限

既存のリポジトリから新しい Cloudflare アカウントに Worker を立ち上げるのは一見単純だが、ゼロから始める道のりには、どこにもまとまって書かれていない落とし穴が点在している。このページではライフサイクルを順に辿り -- Worker の作成とデプロイ、バインディングのプロビジョニング、フレームワークのビルド出力の配信、そして CI によるデプロイ自動化 -- 各ステップの罠を指摘する。

このメモは 2 つの Worker（アプリ Worker + 別個のドキュメント Worker）をゼロからプロビジョニングした経験に基づく。内容はすべて一般的な Workers の知識であり、特定のスタック固有のものではない。

ダッシュボードから Worker を作らない

これが最大の罠。コードがすでにリポジトリにある場合でも、人は反射的にダッシュボードの 「Create a Worker」ウィザード（"Ship something new" -- git リポジトリのインポート、テンプレート、Hello World、アップロード）に手を伸ばす。リポジトリベースの Worker にとって、これらの経路はすべて間違いだ：

• テンプレート / Hello World / アップロードの経路は、リポジトリとは無関係の空の別 Worker を作ってしまう。

• 「git リポジトリのインポート」経路は、本来動かしたい CI と競合する Cloudflare の git ビルドパイプラインを配線してしまう。

正しい経路はリポジトリからの wrangler deploy。これは作成と更新が一体になっている：

npx wrangler deploy

• 初回デプロイ：Worker が誕生する。名前は wrangler 設定の name フィールドから取られる。ダッシュボードでの手順は不要 -- まだ存在しない名前をデプロイすることこそが Worker の作成方法だ。

• 以降のデプロイ：同じコマンドが更新になる。

長期的なベストセットアップは、main への push で CI に wrangler deploy を実行させること。コミット済みの設定が唯一の真実になる。ワークフローは本番デプロイを参照。

workers.dev の URL フォーマットは固定

すべての Worker には、正確にこの形の無料 URL が付与される：

<worker-name>.<account-subdomain>.workers.dev

その配下に任意のサブドメインをでっち上げることはできない -- doc.app.<account-subdomain>.workers.dev のような URL は存在しえない。アプリとドキュメントに別々の URL を持たせる方法は、単純に Worker を 2 つにすること：それぞれが自動的に自分の <name>.<account-subdomain>.workers.dev を得る。

app.example.com / doc.example.com のようなきれいなサブドメインには、本物のカスタムドメイン -- アカウント内のゾーン -- が必要で、wrangler 設定の routes（またはダッシュボード）で配線する：

{
  "routes": [{ "pattern": "app.example.com", "custom_domain": true }]
}

Wrangler の「Add It on Your Behalf?」プロンプトは断る

CLI からのストレージのプロビジョニング（wrangler d1 create、wrangler kv namespace create）は、対話的な申し出で終わる：

Would you like Wrangler to add it on your behalf?

断る（N）。 yes と答えると、wrangler 設定に対して 2 つの悪いことが起きる：

• 間違ったバインディング名で重複したバインディングエントリを追記し、コードが実際に使うバインディング（DB、STATE など）はプレースホルダーの id のまま放置される。

• ファイル全体を再フォーマットする -- 2 スペースインデントがタブになり、配列が展開され、末尾の改行が削られる。

代わりに、コマンドが出力した id / database_id をコピーして、既存のバインディングに手で貼り付ける：

{
  "d1_databases": [
    {
      "binding": "DB",
      "database_name": "my-app-db",
      "database_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    }
  ]
}

続くプロンプト「For local dev, connect to the remote resource?」も N にする -- ローカル開発はローカルストレージに対して行うのがデフォルトとして正しい。

アセットディレクトリに _worker.js を出力するアダプター

フレームワークのアダプター（例：@takazudo/zfb-adapter-cloudflare）は、Worker エントリ dist/_worker.js を、静的アセットとして配信されるのと同じ dist/ ディレクトリに書き出すことがある。すると wrangler deploy はハードエラーになる：

Uploading a Pages _worker.js file as an asset

修正は、Wrangler から見たアセットディレクトリのルートに .assetsignore ファイルを置き、Worker エントリと、アセットと同じ場所に出力される静的インポートされたサーバーモジュールを列挙すること：

_worker.js
_zfb_inner.mjs

フレームワークがビルドのたびに public/ ディレクトリを dist/ にコピーするなら、.assetsignore は public/ に置く -- 自動的にデプロイされるアセットルートに配置されるので、ローカルデプロイと CI の両方で修正が永続する（次のビルドで消されることがない）。

CI トークン：「Edit Cloudflare Workers」では足りない

CI デプロイ用に API トークンを作る際、ダッシュボードは 「Edit Cloudflare Workers」 トークンテンプレートを提示する。罠：このテンプレートには D1:Edit が含まれていない。それがないと wrangler d1 migrations apply --remote が認可エラーで失敗する（code: 7403、given account is not valid or is not authorized to access this service）。

同じテンプレートは Vectorize:Read と Workers AI:Read も、D1:Edit とまったく同じように欠けている。ただし症状は違って見える：GET /accounts/{id}/vectorize/v2/indexes/{name} のような REST アサートは、素の HTTP 403 で失敗する -- D1 の 7403 のような Cloudflare エラーコードのラッパーがない。（Vectorize の Edit でもこのチェックは通る。読み取り専用のアサートなら Read で十分だ。）

診断の経験則（正確なコードは変わりうる -- シグナルとして扱うのはメッセージの方）：

• D1 コマンドでの認可エラー（例：7403）→ トークンに D1 権限が欠けている。

• 「アカウントが見つからない」系のエラー（例：7404）→ 間違っているのはアカウント id であって、トークンではない。

• REST アサートでの素の HTTP 403（エラーコードのラッパーなし）→ トークンにそのサービスの Read 権限が欠けている（Vectorize、Workers AI など）-- D1 のラップされた 7403 とはシグネチャが違う。

• トークンは認証を通るが何も見つからない→ CLOUDFLARE_ACCOUNT_ID がそのトークンを発行したのと同じアカウントに属しているか確認する。アカウント A のトークンとアカウント B のアカウント id を組み合わせると認証はすんなり通り、その後すべてのルックアップが失敗する -- 権限バグに見えるが実際は違う。

• 汎用の Authentication error [code: 10000]→ それぞれ別の対処が必要な、3 つの異なる原因がある：

Workers + D1 + KV + Vectorize + Workers AI スタックで動作する権限セット（実際に使うものに絞ってよい）：

より大規模で、実際に検証済みのスタック -- Workers + D1 + R2 + Queues + Vectorize + Workers AI、routes に custom_domain: true を指定してデプロイする場合 -- で動作した完全な権限セットは次の通り：

トークンとアカウント id は GitHub Actions のシークレット CLOUDFLARE_API_TOKEN と CLOUDFLARE_ACCOUNT_ID として保存する。

割り当て直後のカスタムドメインはすぐには使えない

wrangler deploy はルートを作成した時点でカスタムドメインを報告する：

Deployed my-worker triggers (1.12 sec)
  my-worker.example.com (custom domain)

この行が意味するのはルートが存在することであって、ホスト名が動作することではない。その後 1 分ほどは、レコードと証明書が落ち着くまでエッジが Cloudflare 自身のエラーページ（error code: 1104 や 5xx）を返しうる。数秒後に走るデプロイ後チェックは、サイトではなくこのウィンドウと競走している。

現れる失敗は 2 種類あり、どちらもアプリのバグと誤診しやすい：

AAAA が A より先に来る。 Cloudflare は IPv6 レコードを先に公開する。GitHub Actions のランナーには IPv6 の経路がないため、その隙間の接続はすべて ENETUNREACH で失敗する — Worker 自体は完全に正常なのに。*.workers.dev の URL は影響を受けないので、そちらが 200 を返すなら Worker は正常で、見ているのは伝播の問題だと確認できる。

Node はこれを Happy Eyeballs 経由で AggregateError として報告するが、その集約エラー自体は code を持たないことがある — 実際のアドレスごとのコードは .errors[] にぶら下がる。.cause チェーンだけを辿る分類器は、これを完全に見逃す：

function codes(error) {
  const out = [];
  for (let e = error; e; e = e.cause) {
    if (e.code) out.push(e.code);
    if (Array.isArray(e.errors)) out.push(...e.errors.flatMap(codes)); // <- 必須
  }
  return out;
}

オリジンが繋がる前にエッジが 5xx を返す。 ホスト名は解決し TLS も完了するが、Cloudflare が自前のエラーページを返す。割り当て直後のドメインへの最初のプローブで 5xx を受けたら「まだ準備できていない」と扱い、成功レスポンスとして扱ってはいけない。

CI はコミット済みの設定からデプロイする

CI は main への push で、コミット済みの wrangler.jsonc / wrangler.toml を使って再デプロイする -- ファイルをローカルで編集するだけでは足りない。コミット済みの設定に REPLACE_WITH_* プレースホルダーが残っていれば、ローカルのファイルがどれだけ正しくても CI は失敗し続ける。このハードな失敗はデフォルトの挙動であって、プラットフォーム側の要件ではない -- テンプレートやフォークのリポジトリなら、代わりに優雅に失敗させる選択肢を取れる。セルフスキップ・プリフライトパターンについてはテンプレートリポジトリの CIを参照。

動作確認チェックリスト

プロビジョニング完了と呼ぶ前に確認する：

• Worker は wrangler deploy で作成された（孤児のダッシュボード Worker も、競合する git ビルドパイプラインもない）

• wrangler.jsonc / wrangler.toml に最終的な Worker name と本物のバインディング id が入っていて -- REPLACE_WITH_* プレースホルダーがなく -- コミット済みである

• .assetsignore が出力されるアセットルートに存在する（フレームワークがビルド出力にコピーするなら public/ 経由で）

• D1 マイグレーションがデプロイと同じ CLOUDFLARE_ACCOUNT_ID で実行される

• CI トークンに、D1 を使うなら D1:Edit、Vectorize を使うなら（デプロイ前アサートを含め）Vectorize:Read、Workers AI を使うなら（デプロイ前アサートを含め）Workers AI:Read が含まれている -- さらに必要に応じて KV / R2 / Queues / Routes 権限も -- 「Edit Cloudflare Workers」テンプレートのままではない

• シークレットは wrangler secret put / GitHub シークレットで設定されている -- コミット済み設定の中には 1 つもない

関連ページ：設定フォーマットは Wrangler 設定、アセットモデルは Workers Static Assets、CI ワークフローは本番デプロイ。