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

シリーズ目次 前章: 11. AstroPaperでUI文言の翻訳と多言語対応

Table of contents

この章のねらい

最後に、手元で動いているサイトをインターネットへ出します。AstroPaperは静的サイトなので、やることはビルドして、できたファイルを置くだけ。ただし置く前に確かめておきたいことがいくつかあります。

ビルドの中身をもう一度

{
  "scripts": {
    "build": "astro check && astro build && pagefind --site dist && cp -r dist/pagefind public/"
  }
}package.json

&& は、前の処理が成功したら次へ進むという意味です。どこかで失敗すれば、その時点で止まります。

1番目の型チェックが最初に来ているのがミソです。フロントマターの書き間違いがあれば、ここで止まります。壊れたサイトが公開される事故を防ぐ設計になっています。

型チェックだけを実行する

記事を書き終えた段階で、素早く確認したいときに使えます。

pnpm astro check

エラーがあれば、ファイル名と行番号付きで表示されます。

ビルド結果を確認する

pnpm build
pnpm preview

pnpm preview は dist/ の中身をそのまま配信するので、公開後と同じ状態が見られます。検索機能を確かめられるのはこの方法だけです。

公開前のチェックリスト

site.url は正規URLにもサイトマップにもRSSにもOG画像にも効きます。公開直前に必ず見直してください。

項目を設定、同梱物、最終確認の3つに束ねておくと、抜け漏れが減ります。

デプロイの考え方

pnpm build で作られる dist/ の中身は、ただのHTML・CSS・JavaScript・画像です。特別な実行環境は不要で、静的ファイルを配信できる場所ならどこでも公開できます。

一般的な静的ホスティングサービスでは、次の3つを指定するだけで公開できます。

Gitリポジトリと連携させれば、push のたびに自動でビルドと公開が走ります。記事を書いてコミットするだけで公開される、という運用になります。

指定する3項目と、公開までの流れをまとめると次のとおりです。

サービス選びの観点

テンプレートにはCloudflare Pages向けの設定ファイルが同梱されていますが、他のサービスでも上の3項目を設定すれば動きます。

予約公開を使う場合

第5章で書いたとおり、静的サイトでは時刻が来ても勝手には公開されません。公開されるのは、その時刻より後にビルドしたときです。

予約公開を実際に機能させるには、次のいずれかが必要です。

• ホスティングサービスの定期ビルド機能を使う
• CIサービスのスケジュール実行でビルドを起動する
• 公開時刻の後に手動でビルドする

サブパスで公開する場合

https://example.com/blog/ のように、ドメイン直下ではない場所に置きたい場合は、Astroの base 設定を使います。

export default defineConfig({
  site: "https://example.com",
  base: "/blog",
  // ...
});astro.config.ts

AstroPaperには、この設定に対応するための補助関数が用意されています。

export function getAssetPath(path: string): string {
  const normalizedPath = path.replace(/^\/+/, "");

  if (!normalizedPath) {
    return base === "" ? "/" : base;
  }
  return baseRoot + normalizedPath;
}src/utils/withBase.ts

ファビコンやサイトマップのパスは、この関数を通して組み立てられます。だから base を設定しても、テーマ側のリンクは正しく解決されます。

ただし記事本文に直接書いた絶対パスは調整されません。サブパスで公開する予定があるなら、記事内のリンクの書き方に気をつけてください。

base が効く範囲と効かない範囲を分けておきます。

公開後の確認

デプロイが終わったら、次を実際にブラウザで確認します。

SNSでの見え方は、各サービスのカード検証ツールで確認できます。OGP情報を更新してもキャッシュが残って古い画像が出ることがあるので、検証ツールから再取得を指示してください。

継続的な運用

更新の流れ

1. src/content/posts/ に記事を追加する
2. pnpm dev で確認する
3. pnpm build が通ることを確認する
4. コミットして push する
5. 自動ビルドの結果を確認する

3番目を習慣にしておいてください。公開直前に型エラーが出ると、いちばん面倒です。

コードの整形と検査

テンプレートにはPrettierとESLintが同梱されています。

pnpm format        # 整形する
pnpm format:check  # 整形が必要か確認する
pnpm lint          # 問題のある書き方を検出する

Markdownファイルも整形の対象なので、表の桁がそろわないといった乱れも直ります。

テーマの更新を取り込む

AstroPaperは今後も更新されます。新機能や修正を取り込みたい場合は、リポジトリの変更履歴を確認して、必要な差分を手作業で反映するのが基本です。

このときテーマ本体のファイルをどれだけ書き換えたかが効いてきます。astro-paper.config.ts、theme.css、i18n/lang/ の範囲に収まっていれば、取り込みは楽です。コンポーネントを大きく改造していると、差分の突き合わせで泣きます。

カスタマイズするときは、まず設定で実現できないかを考える。長く付き合うならこれです。

改造がどこまで及んでいるかで、更新の取り込みやすさが変わります。

シリーズのまとめ

12章を通じて、AstroPaperの全体像を見てきました。

AstroPaperは、コードを読み切れる規模に収まっているテーマです。分からないことがあったら、このシリーズで紹介したソースファイルを開いてください。たいてい答えはそこに数十行で書いてあります。

要点

• pnpm build は型チェック・ビルド・索引生成・索引コピーの4段階で、型チェックが最初にあるため壊れた状態での公開を防げる。
• 公開前に site.url を実際の公開URLと一致させる。正規URL・サイトマップ・RSS・OG画像のすべてに影響する。
• デプロイは「ビルドコマンド pnpm build」「出力先 dist」「Node.js 22.12以上」の3点を指定すれば、多くの静的ホスティングで動く。
• 静的サイトのため予約公開は自動では反映されず、定期ビルドなどの仕組みが別途必要になる。
• カスタマイズは設定ファイル・配色・翻訳の範囲に留めておくと、テーマ更新の取り込みが容易になる。

参考資料

• AstroPaper リポジトリ README — コマンド一覧とデプロイ先
• テンプレート同梱ソース package.json — build スクリプトの構成
• テンプレート同梱ソース src/utils/withBase.ts — base 設定への対応
• Astro: Deploy your site — 各ホスティングサービスへの公開手順
• Astro: Configuration Reference — site と base の指定
• Astro: CLI Reference — astro check / build / preview
• Pagefind 公式サイト — 索引生成の実行

シリーズ目次 前章: 11. AstroPaperでUI文言の翻訳と多言語対応