ユタラボ
⚙️ 業務自動化レシピ 2026.08.23 更新

Astro記事サイト運用完全ガイド｜Markdown・検品・SEO・Cloudflare配信を自動化する

AstroのMarkdown記事サイトを、Content Collections、内部リンク、SEO、GitHub Actions、Cloudflare Pages、監視まで一貫して運用するための総合ガイドです。

Astroで記事サイトを作るだけなら、MarkdownをHTMLへ変換して公開するところまで短時間で進められます。しかし、記事が増えると、frontmatter(記事の先頭に書く設定情報)の欠落、リンク切れ、重複URL、ビルド環境差、デプロイ失敗など、本文以外の問題が増えます。運用を安定させるには、執筆、型検査、ビルド、独自検算、配信、公開後確認を一つの流れにする必要があります。

この記事は、Astro記事サイトと自動化関連記事の柱となる総合ガイドです。書き方の説明だけでなく、「どの段階で」「何を証拠に」「合格・不合格を判定するか」を、公式ドキュメントの記述と結び付けて説明します。この記事の手順はAstro 5系(このサイトは ^5.16.0)を前提にしています。公式ドキュメントには新しい版の記述も含まれるため、実装前に導入済みの版と照合してください。

Astro記事サイト運用の全体像

Astroの記事サイトは、原稿ファイルとテンプレートから、ビルド時に静的HTMLを作る構成に向いています。公開時点で本文が決まっている記事なら、読者のブラウザで本文生成用JavaScriptを動かさずに配信できます。

運用は次の七段階で考えます。

  1. 記事のfrontmatterと本文を書く。
  2. Content Collectionsのschema(型の設計図)で項目と型を検査する。
  3. URL、内部リンク、画像、見出しを独自検算する。
  4. Astroで静的HTMLをビルドする。
  5. 生成HTMLのcanonical、主要ページ、リンクを確認する。
  6. すべて成功した場合だけ配信する。
  7. 公開後に404、クロール、表示速度を観測する。

ここで大切なのは、生成と公開を同じ成功条件にしないことです。「原稿が書けた」「ビルドが通った」「本番URLで読めた」「検索エンジンが扱える状態になった」は、それぞれ別の状態です。段階ごとに残す証拠を決めておくと、失敗したときにどこへ戻ればよいかがすぐ分かります。

段階何を確認するか残す証拠
原稿frontmatterと本文記事ファイルそのもの
型検査schemaの合格ビルド・型検査のログ
独自検算出典・内部リンク・文字数検査スクリプトの結果
ビルド静的HTMLの生成dist フォルダ
生成物検査canonical・sitemap・リンク検査ログ
配信本番への反映デプロイの記録(ID・日時)
公開後確認本番URL・404・速度確認日を付けたメモ

最小構成から理解したい場合はAstroでMarkdown記事サイトを作る最小構成が先です。記事制作は、原稿・検品・配信を別工程として扱います。

MarkdownとContent Collectionsで入力を固定する

記事ファイルには、タイトル、説明、カテゴリ、公開日、下書き状態などをfrontmatterとして持たせます。本文はMarkdownで書き、サイト共通のレイアウトや関連記事はテンプレート側で扱います。記事ごとに同じHTMLをコピーしないことで、デザイン変更と原稿編集を分離できます。

AstroのContent Collectionsは、共通の構造を持つコンテンツをまとめて整理・照会・描画する仕組みです。公式ドキュメントによると、コレクションにはloader(どこから何を読むかの指定)が必須で、公式の例では src/content.config.ts にloaderとZod schemaを定義します。glob() loaderはMarkdownなどのファイルをフォルダから読み込み、schemaはfrontmatterの項目と型をビルド時に検査します。エディター上の型検査やTypeScriptの型安全性も得られます。

schemaで確認したい項目の例は次の通りです。

項目役割検査例
titleページ見出し、一覧表示空文字でない、長過ぎない
description検索結果や一覧の要約必須、本文と一致
category分類ページ許可値だけ
pubDate公開順日付型
draft公開可否真偽値
tags関連記事配列、表記ゆれ確認

注意したいのは、型検査だけでは内容の妥当性まで分からないことです。schemaの合格は「形と型が正しい」証明であって、出典の有無、内部リンクの本数、本文の最低量、見出し構成までは保証しません。そこは独自検算で補います。frontmatterの区切りや値を確認しても直らないときは、Astro Content Collectionsの型エラーを直すへ進みます。

下書きの扱いも決め打ちにしません。draft: true を付ければサイト全体から自動で消える、と思い込まないでください。取得処理、記事ページ、一覧、RSS、sitemapのそれぞれで除外されているかを、生成物を見て確認します。どこか一つだけ除外すると、「一覧には出ないのにURLを直接叩くと読める」といった不一致が起きます。RSSの下書き除外はAstroでRSSフィードを作る方法で確認できます。

ローカル検品とGitHub Actionsを同じ順序にする

ローカルでは成功するのにCI(自動検査の仕組み)で失敗する問題を減らすには、実行順、Node.jsの版、依存導入の方法、環境変数をそろえます。ローカルとCIで別のコマンドを使うと、公開直前だけ別の条件が発生します。

検品の順序はこう固定します。

  1. npm ci で依存をlockfile(依存の固定リスト)どおりに導入する。
  2. 回帰テストを実行する。
  3. npm run build でAstroの静的HTMLを作る。
  4. 記事の独自検算(出典・内部リンク・文字数・見出し)を実行する。
  5. 生成HTML(dist)のcanonicalとsitemapを検査する。
  6. すべて成功した場合だけ配信する。

依存導入に npm ci を使うのは、ずれを黙って直さないためです。npm公式ドキュメントによると、npm ci はlockfileが必須で、package.json と食い違うとlockfileを更新せずエラーで止まり、既存の node_modules は開始前に削除されます。つまり「手元とCIで違う依存が入っていた」という事故を、配信前にエラーとして表に出せます。

この順序をGitHub Actionsへそのまま移します。公式ドキュメントによると、workflowはリポジトリの .github/workflows に置くYAMLで定義し、pushなどのイベント、手動操作、スケジュールをきっかけに実行できます。YAMLの組み立て方はGitHub Actionsで記事サイトを自動検品するで確認してください。

もう一つ大事なのが終了コード(プログラムが最後に返す成否の数字)です。Cloudflare Pagesの公式ドキュメントによると、Pagesはビルドコマンドの終了コードで成否を判定します。非0なら失敗、0なら標準エラー出力に警告が出ていても成功として成果物をアップロードします。つまり「警告文を表示するだけの検査」は配信を止められません。重大なNGを見つけたら検査スクリプト自身が非0で終了することを、一度わざと失敗させて実測しておきます。

同時実行にも境界を作ります。GitHub Actionsのconcurrencyによると、Actionsは既定で複数のworkflowやjobを同時に実行できます。本番配信では、古いコミットと新しいコミットの配信が競合しないよう、concurrency で同じグループの実行を制御します。既定のconcurrencyグループでは保留中の実行は1件で、新しい保留実行が以前の保留実行を取り消します。細かい挙動は変わる可能性があるため、実装時点の公式案内と自分のYAMLを照合してください。

失敗したときは、workflow全体を何度も再実行する前に、どの段階で落ちたかを確認します。

失敗段階最初に見るもの関連記事
workflow読込前YAMLのインデント、式、イベントYAMLエラーの直し方
依存導入lockfile、Node.js、registryNode.jsの版違い
ローカルとの差OS、環境変数、パス、生成物ローカルだけ成功する原因
長時間停止timeout、待機、二重実行timeoutと同時実行数を確認する
Secrets不足イベント種別、権限、environmentSecretsが使えない原因

キャッシュは高速化には役立ちますが、正しさの代わりではありません。キャッシュを外した実行と比べ、壊れたキャッシュか処理本体の失敗かを切り分けます。失敗を誰も見なければ自動検品は公開を止めるだけで復旧につながらないので、担当者が確認できる通知先も用意します。

canonical・内部リンク・sitemapを生成物で検品する

記事URLは、一度公開すると外部リンクや検索履歴に残ります。slug(URLの記事名部分)は内容を表し、既存記事と重複せず、後でカテゴリを変えても使える形にします。そして、ファイル名、生成ルート、canonical、内部リンク、sitemapで同じURL規則を使います。末尾スラッシュ、www の有無、HTTPとHTTPSが混在しないよう、サイト全体で方針を固定します。

canonical(そのページの代表URLを検索エンジンへ示す目印)の効き方は、Google検索セントラルの公式ドキュメントに整理されています。Googleは、リダイレクトと rel="canonical" を強いシグナル、sitemapへの掲載を弱いシグナルとしています。あわせて、自己参照canonical(そのページ自身のURLを指すcanonical)を入れること、絶対URLを使うこと、サイト内リンクもcanonical URLへ統一することが案内されています。canonicalは希望を伝えるシグナルであって、指定どおりに選ばれる保証ではない点も押さえておきます。実装確認はcanonical URLの書き方へ進んでください。

sitemapは、クロールしてほしい正規URLの一覧です。Astroの公式統合@astrojs/sitemapは、ビルド時にページからsitemapを生成し、getStaticPaths() で作った動的ルートも対象にします。一方、SSR(サーバー側でその都度HTMLを作る方式)の動的ルートの項目は生成できません。また、Googleのsitemap公式ドキュメントは、sitemapがURLの発見を助ける一方で、掲載した全項目がクロール・インデックス登録される保証はないと明記しています。「sitemapが生成できた」と「検索結果に載った」は別の状態として扱ってください。

生成物検査の合格条件は、たとえば次のように置きます。

  1. dist 内の代表HTMLに、自己参照canonicalが絶対URLで入っている。
  2. sitemapのURLがすべて正規URL(末尾スラッシュ等の規則が統一済み)である。
  3. draft: true の記事が、記事ページ・一覧・RSS・sitemapのどれにも出ていない。
  4. 内部リンクの先が実在し、リンク切れが0本である。

内部リンクの自動検査はAstroサイトのリンク切れを自動検査する、検索エンジンに見つからないときの確認順はrobots.txtとsitemapのトラブル解決とクロール済み・インデックス未登録の対処法にあります。

表示品質も公開条件に含めます。画像は用途に合う寸法と形式を選び、幅と高さ(またはアスペクト比)を指定して、読み込み前後で本文が動かないようにします。実装の選択肢はAstro画像最適化の基本、レイアウトのずれ対策はCLSが悪い原因と直し方を確認してください。記事一覧が長くなったら静的ページネーションも検討します。

検品済みのdistをCloudflareへ配信し、戻せるようにする

このサイトの現行方式は、GitHub Actionsで検品を通した dist を、WranglerというCloudflare公式の道具でCloudflare Pagesへ直接アップロードする形です。Cloudflare Pagesの公式ドキュメントは、事前ビルド済みの成果物をCIから wrangler pages deploy でアップロードする手順(Direct Upload)を掲載しており、pull requestごとにビルド・テストし、マージ後に本番配信する構成も説明されています。配信工程の境界はこう作ります。

  • pull requestではビルドと検品まで行い、配信しない。
  • 本番配信は対象ブランチを限定し、資格情報(Secrets)は最小権限にする。
  • 同じ環境への二重デプロイを concurrency で制御する。
  • 配信後に、トップ、記事一覧、代表記事、404、sitemap、robots.txtを実際の配信URLで確認する。

具体的な流れはAstroをCloudflare Pagesへデプロイするへ進んでください。再読み込み時だけ404になる場合は、生成物のパスと配信側のルーティング設定を分けて確認します。

一つ、混ぜてはいけない話があります。Astro公式のCloudflare配信ガイドは、現在、新規プロジェクトにはCloudflare Workersを推奨すると明記しています。既存のPagesプロジェクトについては、Cloudflareの移行ガイドと互換性表を参照するよう案内されています。つまり「既存Pagesをすぐ捨てる」話ではありません。既存Pagesの継続運用と、新規プロジェクトでの選定と、将来の移行は、別々の判断です。移行するなら、出力先の設定(Workersでは assets.directory)や404の配信動作などの構成差を再検証する別作業として計画してください。料金枠や上限も変わりやすいため、2026年8月23日時点の公式案内で確認してください。

本番で問題が起きたときは、追加デプロイを繰り返す前に一度止まります。Cloudflare Pagesのロールバックを使うと、以前の本番デプロイへ即時に戻せます。対象になるのは成功ビルド済みの本番デプロイで、プレビューデプロイは対象外です。戻した後は、トップ、代表記事、404ページ、canonical、sitemapを再確認し、原因を直してから通常の配信に戻します。ロールバックは公開状態を変える操作なので、実行の判断条件と権限は事前に決めておきます。

よくある質問

npm ciとnpm installはどう使い分けますか？

依存を追加・更新してlockfileを作る作業は npm install、確定済みのlockfileをCIでクリーンに再現する工程は npm ci が基本です。npm公式ドキュメントのとおり、npm ci は定義が食い違うとlockfileを書き換えずエラーで止まります。この「黙って直さない」性質が、配信前の検出器として働きます。

schema(型検査)に合格すれば記事を公開してよいですか？

いいえ。schemaが確認するのは、定義したデータの形と型だけです。本文の事実、出典、リンク、生成HTML、canonical、本番での表示までは保証しません。独自検算、ビルド、生成物検査、公開後確認を別の段階として通してください。

sitemapを作れば検索結果に載りますか？

載る保証はありません。Googleの公式ドキュメントは、sitemapがURLの発見を助ける一方、全項目のクロールやインデックス登録を保証しないと明記しています。sitemapの生成成功と検索掲載は、別の状態として観測します。

Cloudflare PagesとWorkersのどちらを選べばよいですか？

既存のPagesサイトは、現行の検品・Direct Upload・ロールバックの手順をそのまま維持できます。新規プロジェクトは、Astro公式ガイドがWorkersを推奨している現状を確認した上で選定してください。既存サイトの移行は、構成差の検証計画を用意した別作業として判断します。

まとめ

安全な自動運用とは、AIや道具に作らせること自体ではなく、「入力の契約(schema)」「再現できる検品」「配信の条件」「復旧の手段」「公開後の観測」がつながった状態のことです。ビルド成功と公開可否を同じ合格証明にせず、段階ごとに証拠を残せば、失敗しても直す場所がすぐ分かります。

次にやることは、この3つです。

  • ローカルの検品コマンドとGitHub Actionsのstepを、同じ順序・同じコマンドにそろえる。
  • 検査スクリプトを一度わざと失敗させ、非0終了で配信が止まることを実測する。
  • 最後に成功したデプロイの記録(ID・日時)を残し、ロールバックで戻れる状態か確認する。

公式一次情報

著者・作成方法・確認日・広告開示: ユタラボ編集部が、このサイトの package.json と既存の検算順を公式資料へ照合し、原稿から公開後確認までの証拠を7段階へ整理して作成しました。主要仕様の確認日は2026-08-23です。本文内に広告・アフィリエイトリンクはありません。

確認日: 2026-08-23

続き（結論と実データ）はnoteに置いています

ここでは手順のところまで書きました。実際に出た数字、うまくいかなかった条件、そのまま使える設定ファイルは、 note の記事にまとめてあります。

noteで続きを読む Xをフォローする

⚙️ 自動化

AstroをCloudflare Pagesへデプロイする｜静的サイトの最短手順と詰まりどころ

Astroの静的サイトをCloudflare PagesへGitHub Actionsから配信する手順を、設定、権限分離、404・canonical・sitemapの検査まで順に解説します。
⚙️ 自動化

Astro画像最適化の基本｜表示速度を落とさずMarkdown記事へ載せる

Astroの記事画像が重いときに、publicとsrcの使い分け、Imageコンポーネント、幅・形式、遅延読み込み、Markdownでの記法、実測までを順番に解説します。
⚙️ 自動化

AstroでMarkdown記事サイトを作る最小構成｜静的HTMLとContent Collections

AstroでMarkdown記事を管理し、Content Collectionsの型検査、動的ルートの静的生成、canonical、sitemap、生成HTMLの検証までを最小構成で解説します。