12. Astroのビルドとデプロイ

シリーズ目次 ／ 前章: 11. Astroの画像最適化とView Transitions

Table of contents

この章のねらい

作ったサイトは、公開して初めて意味を持ちます。最後に、ビルドからデプロイまでの流れと、公開前に見ておきたい設定を押さえます。

ビルドの流れ

公開用のファイルを作るには astro build を実行します。多くのプロジェクトでは package.json に登録されているため、次のコマンドになります。

npm run build

処理の流れは次のとおりです。

生成物は既定で dist/ ディレクトリに出力されます（outDir オプションで変更可能です）。

ビルド前に検証する

ビルドの前に astro check を実行しておくと、次のような問題を事前に検出できます。

• .astro ファイル内の型エラー
• コンテンツコレクションのスキーマ違反（フロントマターの誤り）
• 存在しないプロパティの参照

npx astro check

package.json のビルドスクリプトに組み込んでおくのが定番です。

{
  "scripts": {
    "build": "astro check && astro build"
  }
}

こうしておけば、検証を通らないコードが公開されることを防げます。

ビルド結果を確認する

astro preview で、ビルド後のファイルをローカルサーバーで確認できます。

npm run preview

開発サーバー（astro dev）とは挙動が違います。公開前には必ずプレビューで確認してください。画像の最適化結果とパスの解決は、ビルド後でないと正確なところが分かりません。

公開前に必要な設定

site：公開URL

site には、実際に公開されるURLを設定します。

export default defineConfig({
  site: "https://example.com",
});

これはサイトマップの生成、RSSフィードの絶対URL、正規URL（canonical）の出力に使われます。未設定だと、これらの機能が正しく動作しません。

base：サブディレクトリ公開

https://example.com/docs/ のように、サブディレクトリ配下で公開する場合は base を設定します。

export default defineConfig({
  site: "https://example.com",
  base: "/docs",
});

設定後は、リンクやアセットのパスを組み立てる際に import.meta.env.BASE_URL を使ってください。ハードコードしたパスは、この設定によって壊れます。

build.format：URLの形

出力するファイルの構成を選べます。

末尾スラッシュの扱いはホスティングサービスによって異なるため、リダイレクトの設定と合わせて確認しておくと安全です。

環境変数

APIキーなどの秘密の値は、コードに直接書かず環境変数として扱います。.env ファイルに書き、リポジトリには含めません（.gitignore に登録します）。

API_SECRET=<YOUR_API_KEY>
PUBLIC_ANALYTICS_ID=<YOUR_ANALYTICS_ID>

PUBLIC_ で始まる変数はブラウザに送られるという規則を必ず覚えてください。秘密の値には絶対に PUBLIC_ を付けないでください。

---
// サーバー側でのみ参照できる
const secret = import.meta.env.API_SECRET;

// クライアントからも参照できる
const analyticsId = import.meta.env.PUBLIC_ANALYTICS_ID;
---

astro.config.mjs の env.schema を使うと、環境変数の型と必須／任意を宣言でき、設定漏れをビルド時に検出できます。

名前の先頭によって、値が届く範囲が変わります。

インテグレーションで機能を足す

Astroの機能は、インテグレーション（統合）で拡張します。追加は astro add コマンドが最も簡単で、パッケージのインストールと設定ファイルの更新を同時に行ってくれます。

npx astro add sitemap

複数をまとめて追加することもできます。

npx astro add react sitemap

公開サイトでよく使われるものを挙げます。

手動で追加する場合は、パッケージをインストールしてから設定に書き加えます。

import { defineConfig } from "astro/config";
import sitemap from "@astrojs/sitemap";

export default defineConfig({
  site: "https://example.com",
  integrations: [sitemap()],
});

デプロイする

静的サイトの場合

ビルド結果は dist/ に出力されたただのHTML・CSS・JavaScriptです。静的ファイルを配信できる場所であれば、どこにでも置けます。

公式ドキュメントでは、Netlify、Vercel、Cloudflare、GitHub Pages、GitLab Pages、AWS、Firebaseなど30以上のサービス向けの手順が用意されています。

多くのサービスでは、Gitリポジトリを連携し、次の2点を指定するだけで公開できます。

• ビルドコマンド: npm run build
• 公開ディレクトリ: dist

以降はプッシュのたびに自動でビルド・公開されます。

オンデマンドレンダリングを使う場合

09. Astroのレンダリングモードとアダプターで扱ったとおり、アダプターの導入が必要です。デプロイ先を決めてから、対応するアダプターを追加してください。

npx astro add vercel

デプロイ先とアダプターは対で決まります。後から乗り換えるとアダプターごと差し替えになるので、早めに候補を絞ってください。

2つの経路を並べると、次のようになります。

公開後に確認したいこと

公開したら、次の項目をひととおり確認しておくと安心です。

特に最後の項目は、Astroを使う意味に直結します。ネットワークタブでJavaScriptの転送量を確認し、想定より多ければ、client:* の指定を見直してください。

シリーズのまとめ

全12章を通じて、次のことを見てきました。

• Astroは「読ませるサイト」に最適化され、サーバー側でHTMLを完成させる（第1〜2章）
• .astro コンポーネントとレイアウトで構造を組み立てる（第3〜4章）
• ファイルの置き場所がURLになり、コンテンツはスキーマで守られる（第5〜7章）
• 対話性は島として、動的処理は必要な範囲だけ追加する（第8〜10章）
• 画像と遷移を整え、検証してから公開する（第11〜12章）

全体を通して一貫しているのは、既定は最小限にしておき、必要なものだけを足すという方針です。ここさえ掴んでおけば、今後Astroに新しい機能が加わっても、使うかどうかを自分で決められます。

次は、公式ドキュメントのチュートリアルで小さなブログを一本作ってみてください。ここまで読んだ内容は、手を動かすまでは結びつきません。

要点

• astro check で検証してから astro build を実行し、結果は dist/ に出力される。
• 公開前に astro preview でビルド後の挙動を確認する。
• site は必須級の設定であり、サイトマップやRSSの生成に使われる。サブディレクトリ公開には base を設定する。
• 環境変数は PUBLIC_ を付けるとブラウザに送られる。秘密の値に付けてはならない。
• 静的サイトは dist/ を配信するだけで公開でき、オンデマンドレンダリングにはデプロイ先に対応したアダプターが必要である。

参考資料

• Deploy your Astro Site — Astro Docs
• Configuration Reference — Astro Docs
• Integrations Guide — Astro Docs
• Environment Variables — Astro Docs
• CLI Reference — Astro Docs

シリーズ目次 ／ 前章: 11. Astroの画像最適化とView Transitions