SEOの基本である sitemap.xml。 Astroには公式の @astrojs/sitemap インテグレーションが用意されており、導入は npx astro add sitemap 一発で済む…はずでした。

しかし、実際に導入してみると、開発環境では確認できないという罠にハマりました。

開発環境（dev）には存在しない

Astroの sitemap インテグレーションは、ビルドプロセス（astro build）の最後に dist フォルダ内のHTMLを走査してXMLを生成します。 つまり、オンメモリで動く開発サーバー（astro dev / pnpm dev）では、サイトマップは生成されないのです。

# これは 404 Not Found になる
http://localhost:4321/sitemap-index.xml

これを知らずに「設定がおかしいのか？」「astro.config.mjs の site 設定が漏れているのか？」とデバッグに時間を費やしてしまいました。

正しい検証フロー

サイトマップを確認するには、必ず「ビルドしてプレビュー」する必要があります。

pnpm build
pnpm preview

こうすることで初めて dist/sitemap-index.xml が生成・配信され、ブラウザで確認可能になります。 「動的な機能ではないが、ビルド時に静的に生成されるもの」の検証は、Devサーバーでは完結しないという良い教訓でした。

Cloudflare Pages での挙動

さらに、Cloudflare Pages にデプロイした際も、wrangler コマンドで適切に dist ディレクトリを指定する必要がありました。 最終的には以下のフローで、ローカルと本番の整合性を担保しています。

  1. site: 'https://a3ro.cc' を astro.config.mjs に明記（必須）。
  2. customPages オプション等は使わず、デフォルト設定で全ページをリストアップさせる。
  3. デプロイ前に必ず pnpm preview でXMLの構造を目視確認する。

単純な機能ほど、ブラックボックス化されている部分の挙動理解が重要です。