Cloudflare Pages へのデプロイ

ドキュメントを書き上げたら、公開してチームやユーザーがアクセスできるようにします。EpoCanvas Docs は Cloudflare Pages でのホスティングを推奨しています。サーバーを購入する必要も Nginx を設定する必要もなく、静的ファイルをそのままアップロードするだけで、HTTPS 証明書も自動で取得できます。このサイト自身（docs.epocanvas.com）もこの記事の方法で公開したもので、以下のコンソール画面のスクリーンショットはすべて実際のデプロイ作業中に撮影したものです。

---

準備作業

必要なもの

項目	説明
Cloudflare アカウント	dash.cloudflare.com で無料登録できます。Pages サービスに有料プランは不要です
ローカルでビルドが通ること	まず pnpm run build を実行して dist/ ディレクトリが正常に生成されることを確認します。クイックスタート を参照
Node.js + pnpm	デプロイコマンドはローカル開発環境に依存します。バージョン要件はクイックスタートの章と同じです

2 つのデプロイ方法の選び方

図: Cloudflare Pages の 2 つのデプロイ経路の比較。左はローカルでビルドしてから Wrangler でエッジに直接アップロードする方法（本サイトが実際に採用）、右は GitHub Webhook でクラウド側の自動ビルドをトリガーする方法。

比較項目	方法 1: コマンドライン直接アップロード	方法 2: Git 自動ビルド
操作方法	ローカルで pnpm run deploy を実行	GitHub にコードをプッシュすると自動でトリガー
取りかかりの難易度	低い。コマンド 2 つ	中。コンソールでの設定が 1 回必要
向いている場面	初回公開、一人での保守、素早い更新	複数人での協業、「コミットしたら即公開」したい場合
本サイトの採用	✅ はい（コンソールで確認可能）	未使用。いつでも追加可能

ヒント

2 つの方法は併用できます。普段は Git 自動ビルドを使い、緊急の修正のときはローカルの pnpm run deploy で直接上書き公開できます。

コマンドをまったく打ちたくない場合

クイックスタート のページでは、Cloudflare・Vercel・Netlify の 3 社のワンクリックデプロイボタンを紹介しています。クリックしてアカウントを認可し、設定を確認するだけで、ドキュメントサイトが自分のクラウドアカウントに公開されます。詳しくはワンクリックデプロイを参照してください。なお Cloudflare のボタンは Workers の静的ホスティングを使うもので、このページで紹介する Pages 方式とは別の独立した経路です。静的ドキュメントサイトであれば閲覧体験は同じなので、どちらか一方を選んで進めてください。

---

方法 1: ローカルコマンドラインからの直接アップロード（初回におすすめ）

この方法はローカルでビルドしてから Cloudflare へ直接アップロードするもので、本サイトが実際に採用しているデプロイ方式です。

ステップ 1: Cloudflare アカウントにログインする

プロジェクトには Wrangler（Cloudflare 公式の CLI ツール）がプリセットされています。初回利用時はブラウザで認可してログインします:

npx wrangler login

実行するとターミナルに Opening a link in your default browser... と表示され、ブラウザで Cloudflare の認可ページが開きます。Allow をクリックすると、ターミナルにログイン成功が表示されます。次のコマンドでログイン状態を確認できます:

npx wrangler whoami

注意

ログインをスキップして直接デプロイを実行すると、ターミナルに You are not authenticated. Please run 'wrangler login'. と表示され、デプロイは一切行われません。

ステップ 2: ワンクリックでビルドとアップロード

プロジェクトの package.json にはワンクリック公開コマンドがプリセットされています:

pnpm run deploy

これは次の 2 ステップを順に実行するのと同じです。まず astro build でサイト全体を dist/ ディレクトリにコンパイルして検索インデックスを生成し、次に wrangler pages deploy dist を呼び出して成果物を Cloudflare に直接アップロードします。ビルド時の実際の出力は次のとおりです:

23:54:01 [build] 181 page(s) built in 20.78s
23:54:01 [build] Complete!

アップロードが完了すると、Wrangler は今回のデプロイのプレビュー URL を出力します。プロジェクト名は deploy スクリプトが --project-name epocanvas-docs として事前に指定しているため、デプロイ中に対話形式で尋ねられることはありません。

ステップ 3: コンソールでプロジェクトを見つける

dash.cloudflare.com を開き、左メニューの Compute (Workers & Pages) をクリックするとプロジェクト一覧が表示されます。次の図には 3 つの重要な位置を注記しています:

図: Workers & Pages のプロジェクト一覧。① 左メニューから Workers & Pages へ移動する。② Create application ボタンで新規プロジェクトを作成する。③ 自分たちの epocanvas-docs プロジェクト。アクセス用ドメイン epocanvas-docs.pages.dev と最新のデプロイ時刻が表示される。

プロジェクト名をクリックして詳細ページに入ると、Deployments タブにデプロイ履歴の全体が表示されます:

図: デプロイ履歴ページ。① プロジェクト名。② Deployments タブ。③ 本番ドメインには docs.epocanvas.com（カスタムドメイン）と epocanvas-docs.pages.dev（デフォルトドメイン）の両方がバインドされている。④ 各デプロイ記録にはブランチとコミット情報が付いている。⑤ ステータスとデプロイ時刻。

ノート

pnpm run deploy を実行するたびに、一覧の先頭に新しいデプロイ記録が追加され、自動的に現在の本番バージョンになります。履歴は一覧に残るため、問題が起きたときはいつでもロールバックできます。

---

直接アップロードプロジェクトのビルド設定

Settings タブを開くと、直接アップロードプロジェクトと Git プロジェクトの違いがわかります:

図: Settings タブ。① Settings の入口。② Git repository の項目に Connect（未接続）と表示されている。直接アップロードプロジェクトには Git ビルド設定が不要で、ビルドは完全にローカルで完結する。

ヒント

これが直接アップロード方式の強みでもあります。ビルド環境はあなたのローカル PC そのものなので、Cloudflare のビルドキューの影響を受けません。代わりに、更新のたびにデプロイを行うその PC でコマンドを実行する必要があります。

---

方法 2: Git リポジトリを接続して自動ビルド（任意）

「コードをコミットしたら自動で公開される」ようにしたい場合は、プロジェクトを GitHub リポジトリに接続し、Cloudflare がクラウド側で自動ビルドするよう設定できます。

ステップ 1: 作成フローに入る

Workers & Pages のプロジェクト一覧ページで右上の Create application ボタンをクリックし（方法 1 のステップ 3 の図の注記 ② を参照）、Pages タブを選択します。

ステップ 2: Git リポジトリを接続する

1. 作成画面で Connect to Git を選択します。
2. Cloudflare に GitHub アカウントへのアクセスを認可します。
3. リポジトリ一覧からドキュメントのリポジトリ epocanvas-docs を選択します。
4. セットアップを開始 をクリックします。

ステップ 3: ビルド設定を入力する

「ビルドとデプロイの設定」で次の内容を入力します:

設定項目	入力値
フレームワーク プリセット	Astro
ビルドコマンド	pnpm run build
ビルド出力ディレクトリ	dist

ステップ 4: 自動ビルドを確認する

保存してデプロイ をクリックすると、Cloudflare が初回ビルドを自動で行います。以後、main ブランチにコードをプッシュするたびに、Cloudflare が自動で取得・ビルド・公開します。各デプロイのビルドログは、プロジェクトの Deployments タブで該当するデプロイをクリックして確認できます。

注意

Git 連携プロジェクトの Settings ページには、ビルド設定のブロック（フレームワーク プリセット、ビルドコマンドなど）が追加で表示されます。これは直接アップロードプロジェクトの画面とは異なります。Settings にビルド設定が見つからない場合、そのプロジェクトは直接アップロード方式であり、正常な動作です。

---

カスタムドメインをバインドする

Cloudflare がデフォルトで割り当てる epocanvas-docs.pages.dev ドメインはそのまま使えます。自分のドメイン（例: docs.epocanvas.com）をバインドする場合も、数分で完了します。

ステップ 1: カスタムドメイン設定を開く

プロジェクト詳細ページで Custom domains タブを開き、Set up a custom domain をクリックします:

図: Custom domains タブ。① タブの入口。② Set up a custom domain ボタン。③ バインド済みの docs.epocanvas.com。ステータスは Active で SSL enabled。

ステップ 2: ドメインを追加して反映を待つ

1. Set up a custom domain をクリックし、あなたのサブドメイン（例: docs.epocanvas.com）を入力します。
2. ドメインの DNS がすでに Cloudflare で管理されている場合は、CNAME レコードが自動で追加されます。他社で管理しているドメインの場合は、<プロジェクト名>.pages.dev を指す CNAME レコードを手動で 1 件追加する必要があります。
3. 証明書の発行を待ちます（通常 2〜5 分）。ステータスが Active に変われば（上の図の ③）、新しいドメインでアクセスできます。

HTTPS 証明書は Cloudflare が自動で発行・更新するため、手動での申請や設定は不要です。

---

デプロイ結果を検証する

コマンドラインで HTTP ステータスを確認

curl -sI https://epocanvas-docs.pages.dev

実際の応答結果:

HTTP/2 200
date: Fri, 11 Sep 2026 15:32:39 GMT
content-type: text/html; charset=utf-8

200 が見えればサイトは正常です。カスタムドメインをバインドしたら、URL を自分のドメインに替えてもう一度テストします。

ブラウザで項目ごとに確認

確認項目	期待される結果
トップページと任意のドキュメントページが開ける	ページが完全にレンダリングされ、白い画面にならない
変更した内容が反映されている	編集したばかりの章の内容が公開サイトで見える
Ctrl+K のサイト全体検索	最新の記事がヒットする（インデックスはビルド時に生成される）
light/dark モードの切替	切替が正常に動作し、リロード後も保持される

---

よくあるデプロイの問題

デプロイ後に公開内容が更新されない？

ブラウザの強制リロード（Ctrl+F5 / Cmd+Shift+R）でキャッシュを排除します。それでも更新されない場合は、コンソールの Deployments ページで最新の記録の時刻を確認し、curl -sI でデプロイのプレビュードメインと比較します。

カスタムドメインで SSL ハンドシェイク失敗 (Error 525) と表示される？

証明書の発行には、全世界に反映されるまで 2〜5 分ほどかかります。待ってから強制リロードしてください。それまでは epocanvas-docs.pages.dev のデフォルトドメインでアクセスできます。

pnpm run deploy が Project not found エラーになる？

まず npx wrangler whoami を実行してログイン済みか確認します。次に、package.json の deploy スクリプトの --project-name と、コンソール上のプロジェクト名が一致しているか確認します。

その他のチェック項目はよくある質問とトラブルシューティングを参照してください。