[Astro] GitHub Pagesデプロイ

概要

前回の記事レイアウトとコンポーネントアーキテクチャでブログの構造を解説しました。今回の記事では、完成したブログをGitHub Pagesにデプロイする過程を説明します。

JekyllはコードをpushするとGitHubサーバーで自動的にビルド/デプロイしてくれましたが、Astroはローカルでビルドした成果物を直接デプロイする必要があります。一段階増えることになりますが、その代わりビルド環境を完全に制御でき、すべてのプラグインを自由に使用できるという利点があります。

ビルドパイプラインを理解する

デプロイ前にビルド過程がどのように進むか理解しておくと良いでしょう。npm run deployの一行を実行すると、内部的に複数の段階が自動的に連鎖実行されます。

npm run deploy
    ↓
1. predeploy: npm run share:sync
    ↓
2. preshare:sync: npm run build
    ↓
3. build: astro build && npx pagefind --site dist
    ↓
4. share:sync: node scripts/share.mjs sync
    ↓
5. deploy: gh-pages -d dist -r ...

この流れはnpmのpreスクリプト機能を活用したものです。deployを実行すると自動的にpredeployが先に実行され、share:syncを実行すると自動的にpreshare:syncが先に実行されるという仕組みです。おかげでnpm run deployの一行だけで、ビルド → 検索インデックス生成 → 共有同期 → デプロイまでのすべての過程が自動的につながります。

各段階の説明

各段階の役割をまとめると以下の通りです。

段階	スクリプト	役割
1	`astro build`	Astroプロジェクトを静的HTML/CSS/JSにビルドして`dist/`ディレクトリを生成
2	`npx pagefind --site dist`	ビルドされたHTMLから検索インデックスを生成
3	`share:sync`	RSSフィードに基づいてソーシャル共有状態を同期
4	`gh-pages -d dist`	`dist/`ディレクトリをGitHub Pagesにデプロイ

gh-pagesでデプロイする

インストール

gh-pagesはビルドされた静的ファイルをGitHub Pagesブランチ（gh-pages）に自動的にpushしてくれるパッケージです。ビルド時にのみ使用するので開発依存としてインストールします。

npm install -D gh-pages

デプロイスクリプト

package.jsonに以下のようにデプロイスクリプトを設定します。

{
  "scripts": {
    "deploy": "gh-pages -d dist -r [email protected]:posstree/deku.posstree.com.git -t"
  }
}

オプションの説明

各オプションの意味は以下の通りです。

オプション	値	説明
`-d dist`	`dist`	デプロイするディレクトリ。`Astro`のビルド出力ディレクトリ
`-r`	`git@personal:...`	デプロイ先のリモートリポジトリ。SSHキーエイリアス（`personal`）を使用
`-t`	-	隠しファイル（`.nojekyll`など）も含めてデプロイ

特に-tオプションが重要です。このオプションがないと.nojekyllのようなドット（.）で始まるファイルがデプロイに含まれず、サイトが正常に動作しません。

デプロイの実行

設定が終わったら、以下のコマンド一行でビルドからデプロイまでのすべての過程が自動的に実行されます。

npm run deploy

カスタムドメインの設定

CNAMEファイル

GitHub Pagesでusername.github.ioの代わりにカスタムドメインを使用するにはCNAMEファイルが必要です。public/CNAMEファイルに使用するドメインを一行で記載します。

deku.posstree.com

public/ディレクトリのファイルはビルド時にdist/ディレクトリにそのままコピーされるため、別途の設定なしにデプロイ時に自動的に含まれます。

DNS設定

ドメイン管理者（例：Cloudflare、Route53）でCNAMEレコードを設定して、カスタムドメインがGitHub Pagesを指すようにします。

CNAME  deku.posstree.com  →  username.github.io

.nojekyllファイルの役割

GitHub PagesでAstroを使用する際に必ず知っておくべきファイルです。

public/.nojekyll

GitHub PagesはデフォルトでアップロードされたファイルをJekyllで処理します。しかしAstroでビルドすると_astro/というディレクトリが生成されますが、Jekyllは_で始まるディレクトリを無視します。結果的にCSSとJavaScriptファイルが読み込まれず、サイトが壊れて見えます。

.nojekyllファイルをルートに配置すると、GitHub PagesがJekyll処理をスキップして、アップロードされたファイルをそのままサーブします。空のファイルですがないとサイトが正常に動作しないため、必ず含める必要があります。

Jekyllデプロイとの比較

JekyllからAstroに移行して、デプロイ方式がどのように変わったか比較します。

項目	Jekyll	Astro
ビルド場所	GitHub Pagesサーバーでビルド	ローカルでビルド後に成果物をデプロイ
ビルド時間	~209秒（サーバー）	~30秒（ローカル）
プラグイン制限	GitHub Pagesが許可するプラグインのみ使用	すべてのプラグインを自由に使用
ビルド制御	GitHubに依存	ローカルで完全制御
.nojekyll	不要	必須
デプロイツール	git pushだけで自動デプロイ	`gh-pages`パッケージを使用

Jekyllはgit pushするだけでよいので最初は楽でしたが、ビルド環境を制御できないため使用できるプラグインが限られていました。Astroはローカルビルドという一段階が追加されますが、カスタムrehypeプラグインやSharp画像変換のような高度な機能を自由に使用できるようになりました。

以前のJekyllデプロイ方法についてはGitHub Pagesデプロイのポストを参照してください。