Pages デプロイ

wrangler pages deploy による静的サイトのデプロイ

Pages プロジェクトの作成

初回デプロイの前に、プロジェクトを作成する：

npx wrangler@4 pages project create zudo-cloudflare --production-branch=main

--production-branch は明示的に渡す。省略すると project create は本番ブランチを必要とし、本来はインタラクティブに尋ねてくる。しかし CI には尋ねる相手の TTY がないため、そこで止まるのではなく Must specify a production branch. で即座に失敗する。

CI パイプラインでは、プロジェクトが既に存在していても再実行が失敗しないよう、作成ステップを冪等にする：

set +e
create_output=$(npx wrangler@4 pages project create zudo-cloudflare \
  --production-branch=main 2>&1)
create_exit=$?
set -e

if [ "$create_exit" -ne 0 ]; then
  if echo "$create_output" | grep -qiE "already exists|8000077|duplicate"; then
    echo "Project already exists, continuing."
  else
    echo "$create_output" >&2
    exit "$create_exit"
  fi
fi

許容するのは「既に存在する」系のシグネチャ（already exists、API エラーコード 8000077、duplicate）のみ。認証エラー、レート制限、アカウント ID のタイプミスなど、それ以外の失敗はパイプラインを失敗させたままにする。

デプロイコマンド

基本的なデプロイコマンドは以下の通りです：

npx wrangler@4 pages deploy <directory> \
  --project-name=<project-name> \
  --branch=<branch> \
  --commit-hash="${GITHUB_SHA}" \
  --commit-message="Production deploy: ${GITHUB_SHA}"

パラメータ

環境変数

デプロイコマンドには以下の環境変数が必要です：

CLOUDFLARE_API_TOKEN=<your-token>
CLOUDFLARE_ACCOUNT_ID=<your-account-id>

本番デプロイとプレビュー

• 本番: --branch=main でデプロイします。プライマリ URL が更新されます。

• プレビュー: その他のブランチ名（例：--branch=pr-42）でデプロイします。プレビュー URL が作成されます。

デプロイディレクトリの構造

デプロイディレクトリには、配信される最終的なファイルがそのまま含まれている必要があります。サイトがベースパス（例：/pj/my-site/）を使用する場合、ファイルを適切にネストする必要があります：

mkdir -p deploy/pj/my-site
cp -r dist/* deploy/pj/my-site/
echo '/ /pj/my-site/ 302' > deploy/_redirects
npx wrangler@4 pages deploy deploy --project-name=my-site --branch=main

詳細は ベースパスパターン を参照してください。

Pages CI のトラブルシューティング

CI で pages project create / pages deploy を実行したときによく出る失敗のシグネチャと、その実際の原因：