前回の記事で公開した HTML だけのシンプルなサイトを、静的サイトジェネレーターの Astro へ移行しました。サイトの見た目や高速さを保ったまま、記事の追加やヘッダー・フッターの共通パーツ管理を劇的にラクにするのが目的です。

前回の記事Claude Code と Cloudflare でサンプルサイトを公開するまでClaude Code への1つの指示でサイトを生成し、GitHub 経由で Cloudflare Workers へ無料公開する最短手順と設定の勘所を解説します。

実際に移行作業を進める中でいくつかハマったポイントがあったため、最短でトラブルなく移行するための手順としてまとめました。つまずきやすい箇所には実体験を交えたヒントを添えています。

Cloudflare の画面やビルド環境のバージョンは、2026年9月時点のものです。

なぜ HTML サイトから静的サイトジェネレーター（SSG）へ移行するのか

HTML だけで作ったサイトはシンプルで分かりやすい反面、ページ数が増えてくると運用で地味に消耗します。

  • ヘッダー・フッター・<head> を全ページに直書きしているため、ナビゲーションを1箇所変えるだけで全 HTML ファイルの修正が必要になる
  • 記事を追加するたびに、トップページの新着記事一覧やリンクを手作業で書き足さなければならない

こうした手間を解消するのが静的サイトジェネレーター（SSG: Static Site Generator）です。共通のパーツ（ヘッダーやフッター）と、Markdown で書いた記事本文を組み合わせて、公開用の HTML ファイルを一括で自動生成してくれます。この HTML を生成する工程をビルドと呼びます。

公開フローの変化
移行前：public フォルダの素の HTML を、そのまま直接配信する
移行後：src 内のパーツと Markdown →（npm run build でビルド）→ dist フォルダに生成された HTML を配信する

最終的にできあがるのは軽量な HTML と CSS なので、Cloudflare Workers の高速な配信性能はそのまま活かせます。唯一の違いは、「配信前にビルドというひと手間が挟まる」という点だけです。

主要 SSG の比較と、Astro を選んだ理由

静的サイトジェネレーターには数多くの選択肢があります。自サイトの規模や用途に迷ったときは、現状の構成を Claude に伝えて比較してもらうと判断しやすくなります。

Claude への相談プロンプト例
現在は HTML/CSS だけで構成された静的サイトです。運用の効率化のためにジェネレーターを導入したいと考えています。
以下の4つの特徴と、当サイトに最もおすすめのツールを理由とともに教えてください。
候補：Astro、Next.js、Hugo、11ty

代表的な4つの特徴を整理すると、次のような違いがあります。

比較項目AstroNext.jsHugo11ty
生成の仕組み.astro コンポーネントと Markdown から HTML をビルドReact ベースのフルスタックフレームワーク（静的エクスポート機能あり）Go 言語で書かれた単体バイナリの高速ジェネレーターNode.js 製の軽量で柔軟な静的サイトジェネレーター
クライアント JS標準ではゼロ（必要な部分だけアイランドとして追加可能）React ランタイムが標準で同梱されるゼロゼロ
学習コスト素の HTML に近く、直感的に書き始められるReact やルーティング仕様の習得が必要独自の Go テンプレート構文に慣れが必要既存 HTML を流用しやすく、導入が容易
記事・コンテンツ管理Content Collections によりスキーマ検証が標準装備自前でデータ取得ロジックを組む必要がある標準で充実しており、大量記事に強い自由度が高い反面、自前設定が多い
ビルド速度高速普通（規模により重くなりやすい）最速（数千ページでも一瞬で完了）高速
Node.js 環境必須必須不要（単体で動作）必須
得意な用途コーポレートサイト・技術ブログ・ドキュメント会員機能やダッシュボードを持つ Web アプリケーション記事数が膨大な大規模ブログ・メディア小規模で素朴な Web サイト

各ツールの所感

  • Astro：ヘッダーやフッターを Header.astro のような部品として切り出し、各ページで再利用できます。記事は Markdown（MDX）で書け、一覧ページも自動生成可能です。クライアント側に余計な JavaScript を出力しないため、素の HTML と同等の軽快さをキープできます。
  • Next.js：Web アプリケーション開発のデファクトスタンダードですが、静的書き出しを行うと画像最適化などの一部機能に制約が生じます。また、React のランタイムを読み込むためページがやや重くなります。動的なログイン機能や管理画面が不要なブログサイトには、オーバースペックと言えます。
  • Hugo：単一バイナリで動くため環境構築が容易で、ビルドは圧倒的に高速です。ただ、Go テンプレート特有の書き方にクセがあり、デザインを細かく作り込もうとするとハードルを感じやすい面があります。
  • 11ty（Eleventy）：既存の HTML を最小限の手間で移行でき、自由度が高いのが魅力です。ただし、コンポーネント設計や画像処理などの仕組みは自分で組み立てていく必要があります。

なぜこのサイトで Astro を採用したのか

いくつかの候補を検討した結果、以下の理由から Astro が最もバランスの良い選択肢でした。

  • 構文が HTML に極めて近いため、既存の HTML/CSS をほとんど手直しせずにコンポーネント化できた
  • 記事を Markdown で管理でき、トップページの新着記事一覧が自動更新されるようになった
  • 不要な JavaScript が出力されないため、移行前と変わらない表示速度を維持できる
  • Cloudflare との親和性が非常に高い（2026年1月、Astro 開発チームが Cloudflare に合流。今後もオープンソースとして継続開発）
  • お問い合わせフォームなどの動的な処理が必要になっても、Cloudflare Workers の機能をそのまま拡張できる

コンポーネントやコンテンツコレクションなど、Astro の標準機能をひととおり知りたい場合は、次の記事にまとめています。

あわせて読むAstro とは？サイトやブログ作りに役立つ標準機能を紹介静的サイトを作るフレームワーク Astro の特徴と、コンポーネント、ファイルベースルーティング、コンテンツコレクション、画像の最適化、RSS やサイトマップなど、サイトやブログを作るときに役立つ標準機能を、このサイトでの使い方とあわせて紹介します。

Claude Code への一括指示で Astro に移行する

実際のコード移行作業は、Claude Code に任せてしまえば一瞬です。ローカル環境に Node.js 22.12 以上が入っていることを確認し、以下のプロンプトを実行します。移行時の要件や出力先をあらかじめ明記しておくことで、後からの手戻りを防げます。

Claude への指示プロンプト例
現在の静的サイトを Astro に移行してください。
- デザインや各ページの URL（/privacy など）は変更しないこと
- ヘッダー、フッター、<head> 内の共通タグはコンポーネント・レイアウトに集約する
- 記事は Markdown（MDX）で執筆できるようにし、記事一覧はコレクションから自動生成する
- ビルド成果物は dist ディレクトリに出力し、wrangler.toml の公開先も dist に変更する
- package-lock.json は、Cloudflare のビルド環境に合わせて npm 10 系で生成する
- 移行前後で画面表示に差異がないか、ブラウザツールで確認する
- README.md を新しいディレクトリ構成と運用手順に更新する
- まだリモートへの push は行わないでください

指示を受けた Claude Code は、Astro のセットアップ、既存 HTML のコンポーネント分割、設定ファイルの更新を順次実行し、ローカルでビルド結果を検証してくれます。完成後のディレクトリ構成は以下のようになります。

移行後のディレクトリ構成
src/
├── pages/             固定ページ（トップ、プライバシーポリシー、404、記事動的ルート）
├── content/articles/  記事の本文データ（Markdown / MDX）
├── components/        ヘッダーやフッターなどの UI パーツ
└── layouts/           全ページ共通のベースレイアウト
public/                そのまま配信する静的アセット（CSS、_headers など）
astro.config.mjs       Astro の全体設定
package.json           依存パッケージと npm スクリプト定義
wrangler.toml          公開ディレクトリを dist に変更した設定ファイル

実体験ヒント：ローカルと Cloudflare の npm バージョン差異によるビルド失敗

筆者が実際に移行した際、ローカル環境で生成された package-lock.json が原因で Cloudflare 側のビルドが落ちるというトラブルを経験しました。ローカル環境の npm が 11 だったのに対し、Cloudflare 側のビルドコンテナが npm 10（2026年9月時点では Node.js 24.18.0 / npm 10.9.2）だったため、ロックファイルの仕様差分によって npm ci がエラーを吐いてしまったのが原因です。

発生したビルドエラーの例
npm error `npm ci` can only install packages when your package.json and package-lock.json or npm-shrinkwrap.json are in sync.
npm error Missing: @emnapi/runtime@1.11.3 from lock file

ローカル側では普通にビルドが通ってしまうため、少し気づきにくい罠です。最初のプロンプトで「npm 10 で生成して」と伝えておくか、もしエラーが出た場合は次のように Claude Code に修正を依頼すると一発で解決します。

Claude へのリカバリー指示例
Cloudflare のビルドで npm ci が失敗しました。ビルド環境と同じ npm 10 系で package-lock.json を再生成してください。

実体験ヒント：Markdown の「」付き太字が効かない現象への対処

Markdown で **「Claude への指示の例」**は のようにカギカッコごと太字にして後ろに文字を続けると、Markdown パーサーの仕様によって太字判定が外れ、アスタリスク ** がそのまま画面に出てしまうことがあります。

この場合は素直に <strong>「Claude への指示の例」</strong>は と HTML タグで記述するのが確実です。Claude Code に「移行前後の画面を目視比較して」と指示しておくと、こうした細かなレンダリング崩れも自律的に検知して直してくれます。

push する前に Cloudflare のビルド設定を変更しておく

Astro 導入後は、配信前に HTML を生成するビルド工程が必須になります。GitHub へ push する前に、Cloudflare のダッシュボード側でビルドコマンドを登録しておきましょう。

  1. Cloudflare 管理画面の「Workers & Pages」から、該当の Worker（例：mysite）を開きます。
  2. 「設定」タブ →「ビルド」メニューを選択します。
  3. ビルド設定を以下の表のとおりに変更して保存します。
設定項目変更内容補足
ビルドコマンド空欄 → npm run buildAstro のビルドを実行するスクリプトを指定
デプロイコマンドnpx wrangler deployデフォルトのまま維持
ルートディレクトリ（Path）（空欄のまま）リポジトリ直下を参照させるため未入力

なお、依存パッケージのインストール（npm install）はビルド前に Cloudflare 側で自動実行されるため、コマンドに追加する必要はありません。

注意点：ビルド設定を変更する前に push するとデプロイが失敗する

ビルドコマンドが空欄のまま push してしまうと、静的ファイルの出力先である dist ディレクトリが生成されないため、デプロイエラーになります。ただし、デプロイが失敗しても直前に公開されていたバージョンがそのまま配信され続けるため、サイトが消えて閲覧不可になる心配はありません。

もし先に push して失敗した場合は、ダッシュボードでコマンドを npm run build に変更した後、Claude Code に「空のコミットを作って push して」と依頼すれば再デプロイが走ります。

技術的な補足：wrangler.toml の [build] 設定は GitHub 連携では使えない

wrangler.toml に [build] command = “npm run build” と記述しておけば自動でビルドが走るように思えますが、Cloudflare の公式ドキュメントによると、GitHub 連携による自動デプロイ（Workers Builds）ではこの設定が無視される仕様になっています。設定ファイル任せにせず、ダッシュボード画面から直接指定する必要があります。

運用のコツ：ダッシュボードの設定変更は手動が一番手軽

Cloudflare のダッシュボード設定はコードファイルから直接変更できないため、ブラウザから自分でポチポチ設定してしまうのが一番手っ取り早いです。

もし AI に画面操作まで任せたい場合は、Chrome 拡張機能「Claude in Chrome」を使う手もあります。ログイン済みの Chrome ブラウザを Claude に操作させ、変更内容を確認した上で承認する、という運用も可能です。

GitHub へ push して本番公開を確認する

ダッシュボード側のビルド設定が整ったら、いよいよ GitHub へのプッシュです。Claude Code に指示を出して作業ブランチをリモートへ反映してもらいましょう。

Claude への指示プロンプト例
Cloudflare ダッシュボードでビルドコマンドを npm run build に変更しました。GitHub の main ブランチへ push してください。

GitHub の main ブランチに push されると、Cloudflare 上で自動的にビルドとデプロイが開始されます。進行状況や合否結果は GitHub のコミット履歴（Workers Builds ステータス）にも連携されるため、Claude Code に「デプロイが通ったか確認して」と頼めば成否を判定してくれます。

無事にデプロイが完了したら、公開 URL（https://mysite.<サブドメイン>.workers.dev）へアクセスし、以下の動作をチェックします。

  • トップページ、プライバシーポリシー、個別記事がデザイン崩れなく表示されるか
  • 意図しない URL（例：/invalid-path）を開いた際に、カスタム 404 ページが正しく返るか
  • コードブロック右上の「コピー」ボタンなどの対話パーツが正常に動くか

トラブルシューティング：ビルドログの確認方法

万が一ビルドが失敗した場合、GitHub のコミット画面上には「失敗」というステータスしか表示されません。詳細なエラーログを確認するには、Cloudflare ダッシュボードの「ビルドログ」を開くか、GitHub のステータスリンクから Cloudflare 側へジャンプします。

ログ末尾のエラー箇所をコピーして Claude Code に渡せば、原因の特定と修正までスムーズに対応してくれます。

Claude へのエラー調査依頼プロンプト例
Cloudflare のビルドでエラーが出ました。ログの末尾を共有するので、原因を特定してコードを修正してください。
（ダッシュボードのビルドログ末尾数行を貼り付け）

移行後の記事追加：Markdown を置くだけで自動反映

Astro に移行した最大の恩恵が、このコンテンツ運用の快適さです。

記事を新しく書きたいときは、src/content/articles/ ディレクトリに Markdown（または MDX）ファイルを1つ追加するだけで済みます。ファイル名がそのまま公開 URL になり（例：hello.mdx → /articles/hello）、トップページの新着記事リストにも自動で並びます。

src/content/articles/hello.mdx
---
title: 記事のタイトル
description: 記事一覧や検索結果に表示する概要文
pubDate: 2026-10-01
readingTime: 10分
---

ここから本文を Markdown で執筆します。

記事の執筆も、構成案やメモを Claude Code に渡してファイル作成からプッシュまで丸投げできます。

Claude への記事執筆・追加指示例
「〇〇」について解説する記事を新設してください。ファイル名は /articles/〇〇 とし、ローカルで表示を確認した上で GitHub へ反映をお願いします。

実体験ヒント：記事の URL を変更した際のリダイレクト設定（_redirects）

サイト構造の整理などで記事の URL を変更すると、過去のブックマークや検索経由のアクセスが 404 になってしまいます。当サイトでも、初期に公開していた /guide を /articles/publish-with-cloudflare へ整理・移動しました。

Cloudflare Workers では、public/_redirects というファイルを用意して転送ルールを書いておくだけで、エッジ側で即座に 301 リダイレクト（恒久的な転送）を処理してくれます。SEO 評価を引き継ぐためにも、URL を変えた際は忘れずに記述しておきましょう。

public/_redirects
/guide /articles/publish-with-cloudflare 301

移行の勘所：事前のビルドコマンド設定と npm バージョンの一致

手書き HTML から Astro への移行でつまずかないためのポイントは、実質的に次の2点だけです。

  1. Cloudflare のビルド環境に合わせて、npm 10 系で package-lock.json を生成すること
  2. GitHub へ push する前に、ダッシュボードでビルドコマンドに npm run build を登録しておくこと

この2点さえクリアしていれば、残りのコード分割やレイアウト設計は Claude Code がきれいに仕上げてくれます。

移行が完了してしまえば、あとは Markdown ファイルをポイッと放り込むだけで記事がどんどん増やせる環境が手に入ります。サイトの運用が驚くほど身軽になるので、HTML の手作業に少しでも限界を感じてきたらぜひ挑戦してみてください。