Back to posts

NetlifyからCloudflare Pagesへ移すときのチェックリスト

Published
CATEGORIES
Cloudflare
Tags
#Cloudflare Pages #Netlify #移行

このサイトは、Gatsbyで作っていた頃からNetlifyで公開してきました。ビルド方法も netlify.toml に yarn build と書いて、そのまま何年も運用していたものです。今回のリニューアルでAstroに作り替えるのにあわせて、公開先もCloudflare Pagesへ移すことにしました。フレームワーク側を載せ替えた判断については、GatsbyからAstroへ移行した理由：判断軸の整理に書きました。

ホスティングの移行は、作業自体は「設定の引っ越し」でしかありません。ただ、漏れた設定は本番で静かに壊れます。ビルドが通ってトップページが表示されても、リダイレクトが1件落ちていたり、計測タグが旧サービスのままだったりする。移行作業そのものはまだ進行中なので、この記事は「移す前に洗い出したチェックリスト」として、確認した項目をそのまま公開しておきます。同じ組み合わせで移行する人の下ごしらえになれば、という気持ちもあります。

1. ビルド設定は「書き直し」になる

Netlifyの設定ファイルはCloudflare Pagesでは読まれません。当たり前ですが、ここが全ての出発点です。

設定項目の対応だけ先に並べると、こうなります。

項目Netlify（移行前）Cloudflare Pages（移行先）
ビルドコマンドyarn build（netlify.toml に記述）npm run build（Astroの公式プリセット）
出力ディレクトリpublic（Gatsby時代）dist
Node.jsの指定方法旧構成の設定はPagesに引き継がれないNODE_VERSION 環境変数か .nvmrc / .node-version で明示（package.json の engines は読まれない）
  • ビルドコマンドと出力ディレクトリをPages側に登録する。Astroなら公式プリセットで、ビルドコマンドは npm run build、出力は dist です。Gatsby時代の出力は public だったので、古い感覚のまま設定すると初回からずれる
  • Node.jsのバージョンを固定する。現行のビルドイメージ（v3）のデフォルトはNode.js 22系ですが、デフォルトのバージョンは更新されていく前提のものです。しかも package.json の engines はPagesのビルドでは読まれません（公式ドキュメントに制限事項として明記されています）。NODE_VERSION 環境変数か、.nvmrc / .node-version ファイルで明示しておく
  • パッケージマネージャのバージョンも必要なら明示する。旧サイトはYarn 1系の前提で、バージョン指定もNetlify側に持っていました。Pages側のYarnのデフォルトは4系で、yarn.lock からバージョンを判別する機能もありません。条件が合わない場合は YARN_VERSION で固定する
  • モノレポ構成ならルートディレクトリの指定が要るか確認する
  • いきなり本番ドメインを切り替えず、まず *.pages.dev のURLでデプロイして、ビルドと表示を確認する

2. 環境変数は引き継がれない

  • Netlifyの管理画面に登録していた環境変数を一覧にして、Pagesの Settings → Environment variables に登録し直す。自動移行の仕組みはありません
  • ProductionとPreviewで値を分ける。Pagesでは環境ごとに変数を分けられるので、プレビュー側に本番用トークンを流さない
  • 設定ファイルに直書きしていた値があれば、この機会に変数側へ逃がす。リポジトリに残っている秘密情報は、移行後も残り続けます

環境変数と秘密情報の扱いそのものについては、Cloudflare Pages／Workersの環境変数と秘密情報の扱いで整理しています。

3. ドメインとDNSは「順番」が大事

このサイトは pastora.jp という裸ドメイン（apex）で公開しているので、apexの話がそのまま当てはまります。

⚠ 順番を間違えると詰むところ

  • 既存のDNSレコード、とくにメール用のMXやSPFを控えずに進めると、サイトと関係ないところで事故になる
  • Pagesプロジェクト側の「Custom domains」でドメイン登録を済ませてからDNSを向けること。登録なしにCNAMEだけ作っても名前解決に失敗する
  • apexで公開するなら、ドメインをCloudflareのゾーンとして追加し、ネームサーバをCloudflareに向ける必要がある。サブドメインだけなら <プロジェクト>.pages.dev へのCNAMEで足りる、という違いを先に押さえる
  • 既存のDNSレコードを全部控えておく。とくにメール用のMXやSPFは、移行作業の巻き添えで消すとサイトと関係ないところで事故になる
  • Pagesプロジェクト側の「Custom domains」でドメイン登録を済ませてからDNSを向ける。登録なしにCNAMEだけ作っても名前解決に失敗します（公式ドキュメントの既知の問題に載っているパターンです）。CloudflareでDNSを管理しているゾーンなら、レコードは自動で作られます
  • wwwあり／なしのどちらを正にするか決め、逆側からのリダイレクトを用意する
  • 証明書は自動発行されるので、切り替え直後に「有効になっているか」を確認項目に入れておく

4. リダイレクトとヘッダーの棚卸し

  • Netlifyの _redirects ファイルや netlify.toml の [[redirects]] に書いたルールを全件書き出す。Pagesも _redirects ファイルに対応しているので、基本的な書式は持ち越せます
  • 置き場所はビルド成果物の中。Astroなら public/ フォルダに入れておけば dist にコピーされます
  • 件数の上限を確認する。 _redirects は静的リダイレクト2,000件・動的100件まで、1行は1,000文字までが公式の制限です。超える場合はBulk Redirects側で受ける。個人ブログで当たることはまずありませんが、件数だけは数えておく
  • 移せないルールがないか個別に見る。Netlify側で使えた条件指定（クエリパラメータや言語など）やプロキシ的な書き換えは、Pagesの _redirects では対応が限られます。該当するものはRedirect RulesやPages Functionsで受けるか、あきらめるかを決める
  • [[headers]] を使っていた場合は _headers ファイルに書き直す
  • 今回のようにURL設計自体が変わるリニューアルでは、旧URL→新URLの対応表を先に作ってから設定に落とす

5. ホスティング固有の機能は、移行先に「無い」ものとして洗う

ここが一番漏れやすいところです。設定ファイルに書かれていない機能は、引っ越しの荷物一覧に出てきません。

  • フォーム。Netlify Formsは、フォームタグに netlify 属性を付けておくとビルド時に検出して受け付けてくれる仕組みで、Pagesには同等の機能がありません。使っているなら、Pages Functionsで受け口を作るか、外部のフォームサービスに替える。使っていない場合も、HTMLに属性だけ残っていないか確認する
  • 管理画面・CMS。旧構成にはNetlify CMSが付いていました。ログインまわりにNetlify Identityを使っている構成は移行先ではそのまま動きません。移行を機に「記事はGitで直接編集する運用に寄せる」のか、別のCMSに替えるのか、ここで決めておく
  • 管理画面でONにしていたその他の機能。ビルドプラグイン、デプロイ通知、スプリットテストなど、画面側の設定はファイルに残らないので、旧サービスの管理画面そのものを一度棚卸しする

6. 解析タグは、移行のついでに直す

このサイトの解析は、旧Universal AnalyticsのIDが残ったままになっていて、計測自体が止まっていました。移行作業と直接は関係ないのですが、こういう「ずっと壊れていたもの」は、引っ越しのタイミングでしか直りません。

  • UAのタグをそのまま持ち越さない。GA4に替えるか、Cloudflare Web Analyticsに寄せるか決めて、新しいID・トークンで貼り直す
  • Search Consoleの所有確認の方法を確認する。DNSで確認している場合は、ネームサーバの変更で影響が出ないか先に見る

7. 切り替え直後の確認

  • トップページと主要な記事が200で返ること
  • 旧URLが、対応表どおりに301で新URLへ飛ぶこと
  • 存在しないURLで自前の404ページが出ること
  • RSSとサイトマップが新ドメインで生成されていて、canonicalが新しいURLを指していること
  • 画像などのファイルが欠けていないこと。無料プランでは1サイトあたり20,000ファイルまでという制限があるので、総ファイル数だけ確認しておく（制限値や無料枠の条件は変わりうるので、移行時点の公式ドキュメントで再確認すること）
  • フォームを用意した場合は、テスト送信が届くこと
  • 解析が受信できていることをリアルタイム表示で見ること
  • *.pages.dev 側を公開したままにするかどうか決める。プレビュー用のURLが本番とは別に残るので、扱いを決めておく
  • 問題がなければ、Netlify側の自動デプロイを止める。二重にデプロイが走る状態を残さない

おわりに

ホスティング移行で怖いのは、ビルドエラーよりも「通ったのに何かが落ちている」状態です。落ちるものは大抵、リダイレクト1件、タグ1つ、フォーム1つといった小さいものばかりで、チェックリストに書いて1つずつ潰すのが結局いちばん早い。実際の切り替え結果と、詰まったところがあれば、それは移行が終わったあとに別の記事で書く予定です。

参考

Tags Categories