サーバー・インフラ公開日
連載「Cloudflare Pages で公開する」第1回

Astro × microCMS を Cloudflare Pages にデプロイする手順と、「is missing」エラー・ビルドなし公開の落とし穴

この回でやること

Astro と microCMS で作ったこのサイト（cyber-blow.com）を、Cloudflare Pages で公開するまでの手順をまとめます。連載「Cloudflare Pages で公開する」の第1回です。

後半では、公開作業で実際につまずいた次の2つを詳しく書いています。

  • ビルドされないままデプロイが「成功」し、リポジトリの中身がそのまま公開されていた
  • MICROCMS_API_KEY is missing でビルドが失敗した（原因は環境変数名の末尾の全角スペース）

前提

項目

このサイトの場合

Astro の出力

静的出力（アダプターなし）

コンテンツ

ビルド時に microCMS の API から取得

ソースコード

GitHub のリポジトリ（非公開）

環境変数

MICROCMS_SERVICE_DOMAIN と MICROCMS_API_KEY（astro:env で必須にしている）

サイトの作り方は連載「Astro × microCMS でブログを作る」に、astro:env で環境変数を検証する方法はその第1回に書いています。

デプロイの前に：microCMS 側を確認する

静的サイトは、ビルドのときに microCMS から記事を取ってきます。microCMS 側に API が無かったり、フィールド名がコードと食い違っていたりすると、Cloudflare でのビルドが失敗したり、表示が欠けたりします。そこで、Cloudflare の設定に入る前に microCMS 側を確認しました。

API を作り、0件でもビルドできることを確かめる

まず、コードが前提にしている4つの API（blogs・categories・series・tools）を、README にまとめたスキーマのとおりに作りました。

次に、コンテンツが1件も無い状態でビルドし、トップ・ブログ・ツール・プライバシーポリシーの4ページが生成されることを確認しました。公開した直後は記事が0件なので、この状態でビルドが通らないと、最初のデプロイができません。

microCMS は、綴りを間違えたフィールド名をエラーにしない

ここで気をつけたいのが、microCMS の API は fields・orders・filters に存在しないフィールド名を指定してもエラーにならないことです。

このサイトでは、一覧ページなどで fields を使い、取得するフィールドを絞っています。

src/lib/microcms.ts
// 関連記事は本文まで返ってくると重いので、id と title だけに絞る
const TOOL_FIELDS = ['id', 'name', 'description', 'url', 'thumbnail', 'relatedBlogs.id', 'relatedBlogs.title'];

この配列でフィールドIDの綴りを間違えても、ビルドは普通に通ります。試しに、series API に name を nmae と打ち間違えたクエリを送ると、次のようになりました。

クエリ

ステータス

返ってきたもの

fields=id,name

200

id と name

fields=id,nmae

200

id だけ（エラーにならない）

orders=-nmae

200

エラーにならず、一覧が返る

filters=nmae[equals]test

200

0件

fields の綴り違いは「そのフィールドが空」、filters の綴り違いは「該当なし」として返ってくるだけなので、ビルドのログを見ても気づけません。

そこで、各 API にダミーのコンテンツを1件ずつ公開し、API が返す JSON を見て、フィールド名と型がコードと合っていることを確かめました。あわせて、microCMS の画像API で WebP（記事・カード用）と 1200×630 の JPEG（OGP 用）が返ってくることも確認しています。

確認に使ったダミーは、あとで削除します。このとき削除が本番サイトに反映されなかった話は、第3回で書きます。

Cloudflare Pages の設定

Node.js のバージョンを .node-version で指定する

Cloudflare Pages のビルド環境には Node.js が入っていますが、ドキュメントによると既定のバージョンは 22.16.0 です（2026年10月時点）。一方、このサイトで使っている Astro 7 は Node.js 22.23.4 以上を要求します。

package.json
"engines": {
	"node": ">=22.23.4"
},

Node.js のバージョンは、環境変数 NODE_VERSION か、リポジトリ直下の .node-version（または .nvmrc）で変えられます。このサイトでは .node-version を置きました。中身はバージョンの数字だけです。

.node-version
24

参考：Build image | Cloudflare Pages docs

ビルド設定

Cloudflare ダッシュボードの Workers & Pages で Pages プロジェクトを作り、GitHub のリポジトリを接続します。ビルド設定は次のとおりです。

項目

値

フレームワークプリセット

Astro

ビルドコマンド

npm run build

ビルド出力ディレクトリ

dist

本番ブランチ

main

Cloudflare 公式の Astro 向けガイドでも、ビルドコマンドは npm run build、出力先は dist になっています。

参考：Astro · Cloudflare Pages docs

この設定を入れないまま GitHub を接続するとどうなるかは、このあとの「落とし穴①」で書きます。

環境変数

MICROCMS_SERVICE_DOMAIN と MICROCMS_API_KEY を、Pages プロジェクトの環境変数に追加します。APIキーは「暗号化」にしておきます。

手元では .env に書いていますが、.env は .gitignore で Git の管理から外しているので、GitHub 経由でビルドする Cloudflare には届きません。Cloudflare 側にも同じ変数を入れる必要があります。

.gitignore
# environment variables
.env
.env.production

ビルドで使うのは記事の取得（GET）だけなので、Cloudflare に入れる APIキーは GET 権限だけのものにしています。

プレビューデプロイ

main 以外のブランチを push すると、プレビュー用のデプロイが走ります。不要なら、設定 > ビルド > ブランチの制御 で、プレビューブランチを「なし」にします。

落とし穴①：ビルドされずに「成功」し、リポジトリの中身が公開された

何が起きたか

GitHub のリポジトリを接続した直後に、最初のデプロイが自動で走りました。GitHub のコミットに付く Cloudflare Pages のチェックも「Deploy successful!」です。

ところが、公開された URL でトップページを開くと 404 でした。

原因は、ビルドコマンドが未設定のままだったことです。ビルドが行われず、リポジトリの中身がそのまま配信されていました。リポジトリ直下には index.html が無いので、トップは 404 になります。一方で、README.md や src/ 以下のソースコードは、パスを指定すれば誰でも開ける状態でした。

何が見えていて、何が見えていなかったか

GitHub のリポジトリは非公開にしていますが、それとは関係なく、Pages で配信されたファイルは誰でも見られます。見えていたのは、README やソースコードなど、リポジトリに入っているファイルです。

APIキーを書いた .env は、前の節のとおり Git に含めていません。リポジトリに入っていないので配信もされず、APIキーが見える状態にはなっていませんでした。

対処

  1. ダッシュボードから、このデプロイを削除する
  2. ビルド設定（プリセット Astro、npm run build、出力先 dist）と環境変数を入れる
  3. もう一度デプロイする

3 は、コードに変更が無いので空のコミットを push してデプロイのきっかけにしました。

git commit --allow-empty -m "Cloudflare Pages のデプロイを実行"
git push

いまは、リポジトリのファイルの URL を開いても 404 が返ります。

$ curl -s -o /dev/null -w '%{http_code}\n' https://<PROJECT>.pages.dev/README.md
404

確認のしかた

デプロイが「成功」と表示されても、意図どおりにビルドされたとは限りません。最初のデプロイのあとは、次の2つを開いて確かめるのがおすすめです。

  • トップページが表示されるか
  • /README.md や /package.json など、リポジトリにあるファイルのパスが 404 になるか

落とし穴②：「MICROCMS_API_KEY is missing」でビルドが失敗する

エラーの内容

ビルド設定と環境変数を入れて再デプロイすると、今度はビルドが失敗しました。ログに出ていたのは MICROCMS_API_KEY is missing です。

Astro の astro:env は、env.schema で必須にした変数が無いと、次の形式のエラーでビルドを止めます（インストールされている Astro のソースで確認した形式です）。

The following environment variables defined in `env.schema` are invalid:

- MICROCMS_API_KEY is missing

このサイトの astro.config.mjs では、2つの変数を必須にしています。

astro.config.mjs
env: {
	// 未設定のままビルドすると、ここで分かりやすいエラーになる
	schema: {
		MICROCMS_SERVICE_DOMAIN: envField.string({ context: 'server', access: 'secret' }),
		MICROCMS_API_KEY: envField.string({ context: 'server', access: 'secret' }),
	},
},

参考：Invalid Environment Variables | Astro Docs

原因：変数名の末尾の全角スペース

環境変数は確かに入れたはずなのに「無い」と言われる。原因は、Cloudflare 側で入力した変数名の末尾に、全角スペースが入っていたことでした。

MICROCMS_API_KEY の後ろに全角スペースが付いた名前は、MICROCMS_API_KEY とは別の変数です。そのため Astro からは、MICROCMS_API_KEY が無いように見えます。管理画面の一覧では、末尾の全角スペースは見た目で区別がつきません。

日本語入力をオンにしたままスペースキーを押すと、全角スペースが入ります。変数名を入力するときは注意が必要です。

対処

Cloudflare 側で変数名を半角で入れ直し、再デプロイしたらビルドが通りました。

同じエラーが出たときの確認ポイント

  1. 変数名の前後に空白（特に全角スペース）が入っていないか。見た目では分からないので、入れ直すのが確実です
  2. 変数名の綴りが、コードや .env.example と一致しているか。コピーして貼り付けると間違いが減ります
  3. 変数を直したあとに再デプロイしたか。静的サイトは、ビルドした時点の値で作られます

astro:env で必須の変数を宣言しておくと、足りない変数の名前がエラーメッセージにそのまま出ます。「入れたはずの変数が無いと言われる」なら、名前が食い違っている、と切り分けられます。

デプロイの経過

GitHub のコミットに付いた Cloudflare Pages のチェックの記録（日本時間）を並べると、次のようになります。

時刻

出来事

結果

11:42

GitHub 接続直後のデプロイ（ビルドなし）

成功（中身はリポジトリそのもの）

13:42

ビルド設定と環境変数を入れて再デプロイ

失敗（MICROCMS_API_KEY is missing）

13:48

変数名を直して再デプロイ

成功

まとめ

  • デプロイ前に、microCMS の API を作って、0件でもビルドが通ることを確かめる
  • microCMS は綴りを間違えたフィールド名をエラーにしないので、ダミーデータで実際の返却値を確かめる
  • Cloudflare Pages の Node.js の既定は 22.16.0。Astro 7 には足りないので、.node-version で指定する
  • ビルド設定（プリセット Astro、npm run build、dist）を入れずに接続すると、リポジトリの中身がそのまま公開される。「成功」でも、公開された中身を確かめる
  • 〇〇 is missing が出たら、Cloudflare 側の変数名に空白（全角スペース）が紛れていないかを疑う

次回は、存在しない URL にトップページが 200 で返る「ソフト404」の対処と、独自ドメインの設定を扱います。