Astro (AstroPaper) + Cloudflare Pages で技術ブログを構築した

概要

Astro のテーマ AstroPaper を使って個人技術ブログを構築した。ホスティングは Cloudflare Pages で、GitHub リポジトリへの push で自動デプロイされる構成にした。

環境

macOS
Node.js 22（Volta で管理）
Astro 5.x / AstroPaper 5.5.1
Cloudflare Pages（無料プラン）

手順

1. AstroPaper テンプレートを展開

既存ディレクトリに直接展開できないため、/tmp に作成してからコピーした。

cd /tmp
npx create-astro@latest astropaper-init --template satnaing/astro-paper --no-install --no-git
cp -r /tmp/astropaper-init/. /path/to/<repo-name>/

2. Volta で Node バージョンを固定

volta pin node@22

package.json に以下が追記される。

"volta": {
  "node": "22.22.2"
}

3. サンプル記事を削除

rm -rf src/data/blog/_releases src/data/blog/examples
rm src/data/blog/*.md

4. サイト設定を更新

src/config.ts の以下を変更した。

export const SITE = {
  website: "https://tyamac.dev/",
  author: "tyamac",
  lang: "ja",
  timezone: "Asia/Tokyo",
  // ...
};

5. pnpm-lock.yaml を削除して npm install

テンプレートは pnpm 前提だったが、プロジェクトでは npm を使うため差し替えた。

rm pnpm-lock.yaml
npm install

6. GitHub にリポジトリを作成して push

gh repo create <repo-name> --private --source . --remote origin --push

7. Cloudflare Pages に GitHub 連携でデプロイ

Cloudflare ダッシュボードで Workers & Pages → Create → Pages → Connect to Git からリポジトリを選択し、以下のビルド設定を入力した。

項目	値
フレームワークプリセット	Astro
ビルドコマンド	`npm run build`
ビルド出力ディレクトリ	`dist`
環境変数 `NODE_VERSION`	`22`

ハマったポイント

Wrangler CLI で作成したプロジェクトは GitHub 連携できない

最初に Wrangler CLI でプロジェクトを作成・デプロイした。

npx wrangler pages project create <project-name> --production-branch main
npx wrangler pages deploy dist --project-name <project-name> --branch main

デプロイ自体は成功したが、このプロジェクトは「Direct Upload」タイプになる。 Cloudflare の仕様として、Direct Upload タイプのプロジェクトには後から GitHub 連携を追加する UI が存在しない。

結果として Wrangler で作成したプロジェクトを削除し、ダッシュボードから作り直した。

npx wrangler pages project delete <project-name> --yes

GitHub 連携による自動デプロイを最初から目的とする場合は、Wrangler を使わずダッシュボードから「Connect to Git」でプロジェクトを作成するのが正しい手順。

Workers と Pages を混同しやすい

Cloudflare ダッシュボードの「Create」画面には Workers と Pages のタブがある。 Pages を作成する際に Workers タブのままビルド設定を入力しようとすると、フレームワークプリセットが表示されないなど設定項目が異なる。Pages タブを選択すること。

NODE_VERSION の指定が必要

Cloudflare Pages のデフォルト Node バージョンは古い。 NODE_VERSION=22 を環境変数に設定しないとビルドが失敗する可能性がある。

まとめ

Wrangler CLI でのデプロイと GitHub 連携デプロイはプロジェクトタイプが異なる。GitHub 連携を使いたい場合はダッシュボードから作成する
Cloudflare Pages のビルドには NODE_VERSION 環境変数の設定が必要
npm run build の中に pagefind が含まれているため、ビルドコマンドは astro build ではなく npm run build を指定する