← ./articles-ja

Cloudflare PagesはGit連携かDirect Uploadかを作成前に決める

cloudflare-pageswranglerdeploymentcistatic-site

Cloudflare Pagesには、大きく2つのデプロイ方法があります。

1つはGitHub/GitLabと連携してCloudflare側でbuildする方法。もう1つは、手元やCIでbuildした静的ファイルをWranglerでDirect Uploadする方法です。

どちらも静的サイトを公開できます。ただし、運用の性質はかなり違います。プロジェクト作成前に決めておいたほうが安全です。

2つの方式

Git連携では、repositoryへpushするとCloudflareがbuildします。branch previewも自動化しやすいです。

Direct Uploadでは、先に自分の環境でbuildし、出力ディレクトリだけをCloudflareへ送ります。

npx wrangler pages deploy out --project-name my-site

Next.jsのstatic exportなら、out/ をアップロードします。Viteなら多くの場合 dist/ です。

Git連携が向く場合

Git連携は、次のような場合に向きます。

  • buildが単純
  • Cloudflareのbuild環境で問題なく動く
  • branch previewを簡単に使いたい
  • dashboard上の設定管理で十分

一方で、Node version、build command、output directory、環境変数、monorepo rootなどがCloudflare側の設定に依存します。失敗すると、ローカルでは通るのにCloudflareだけ落ちる、という調査になります。

Direct Uploadが向く場合

Direct Uploadは、buildを自分で制御したい時に向きます。

  • GitHub Actionsでbuildしたい
  • Node/npm versionを固定したい
  • build前に独自scriptを走らせたい
  • out/ や dist/ を検査してから公開したい
  • Cloudflareには静的ファイルの配信だけ任せたい

流れはこうです。

Cloudflare外でbuild
出力ディレクトリを検証
Wranglerでupload

Direct Uploadのproductionとpreview

WranglerでDirect Uploadする時は、branch指定に注意します。

productionへ出すなら、基本はこれです。

npx wrangler pages deploy out --project-name my-site

previewを明示したい時だけbranchを付けます。

npx wrangler pages deploy out --project-name my-site --branch preview

意図せず --branch を付けると、production domainが更新されず、previewだけ更新されたように見えることがあります。

選び方

Git連携を選ぶ条件:

  • 構成が単純
  • Cloudflare上でbuildして問題ない
  • branch previewを簡単に使いたい
  • dashboard設定中心で運用したい

Direct Uploadを選ぶ条件:

  • build再現性を重視する
  • 独自の前処理や検証がある
  • static export成果物を確認してから出したい
  • CIでbuild済みartifactをそのまま上げたい

まとめ

Cloudflare Pagesの選択は、ホスティング方法だけではなくbuild責任の置き場所の選択です。

Git連携は便利です。Direct Uploadは明示的です。Next.js static exportのように、out/ を確認してから出したいプロジェクトでは、Wrangler Direct Uploadのほうが原因切り分けしやすいことがあります。

参考