☁️

Hugo 製の静的サイトを Cloudflare Pages から Cloudflare Workers に移行する

k1350

2026/03/02に公開

Hugo

Cloudflare Workers

tech

 概要Cloudflare はしばらく前から Cloudflare Pages でデプロイされているサイトを Cloudflare Workers に移行することを勧めてきています。

ビルド時に Hugo のバージョンを指定するための環境変数 HUGO_VERSION について Pages のドキュメントにしか書いていなかったため放置していたのですが、Workers でも設定したら動いたので移行することにしました。

 前提Hugo 製の完全に静的なサイトです。Pagefind で検索機能を提供しています。
これまでのデプロイは Pages の環境変数 HUGO_VERSION に Hugo のバージョンを指定した上で、下記の記事で書いている Pagefind インストールスクリプトを同梱し、Pages のビルドコマンドを hugo && chmod +x ./pagefind.sh && ./pagefind.sh としていました。

https://zenn.dev/k1350/articles/42c13020038d4c
Hugo のバージョンは 2026/2/22 時点で最新の v0.156.0 を使うものとし、ローカル環境に Hugo はインストール済みとします。

 移行手順Migrate from Pages to Workers という公式ガイドを参考にやっていきます。

 1. package.json を作るまずフレームワークごとのガイドを見ましたが、Hugo は掲載されていないためスルーします。
wrangler をインストールするため package.json を作ります。どうせ package.json を作るので、Pagefind もインストールスクリプト経由ではなく npm 経由でインストールするようにしました。
package.json
{
  "name": "daybreak",
  "private": true,
  "scripts": {
    "deploy": "wrangler deploy",
    "build": "hugo && pnpm run pagefind",
    "pagefind": "pagefind --site public --glob=\"{logs,posts}/*/*.html\""
  },
  "devDependencies": {
    "pagefind": "^1.4.0",
    "wrangler": "^4.67.0"
  }
}

 2. wrangler.jsonc を作るwrangler の設定ファイルを作ります。
wrangler.jsonc
{
  "name": "daybreak",
  "compatibility_date": "2026-02-22",
  "assets": {
    "directory": "./public",
    "not_found_handling": "404-page"
  },
  "workers_dev": false,
  "preview_urls": true
}
not_found_handling を指定しておかないと 404 ページが表示されません。
また私はカスタムドメインを使っているので workers.dev ドメインは無効にします。

でもプレビューURLは使うので別途有効とします。
ここまでやったら一度ローカル環境から npm run build してから npm run deploy します。

特に問題なくデプロイできるはずです。

 3. プレビューURLに Cloudflare Access を設定するデプロイしたアプリケーションの設定タブに行きます。

「ドメインとルート」で workers.dev は無効、プレビューURLは有効になっているはずです。
プレビューURLのメニューから Cloudflare Access を有効にします。
「JWTを設定しろ」みたいなモーダルウィンドウが出ますが、今回は完全に静的なサイトなので必要ありません。無視します。

モーダルウィンドウは閉じることができなかったのでブラウザバックで別の画面に遷移しました。
きちんとデプロイされていることを確認するため、デプロイタブに行きます。

「バージョン履歴」でバージョンIDをクリックするとプレビューURLを開けます。
先ほど Cloudflare Access を有効にしたためメールアドレスを入力して確認コードを入れないと閲覧できません。
プレビューURLでサイトが問題なくデプロイされており、404ページもきちんと表示されることを確認しておきます。

 4. カスタムドメインの移動 & Pages 削除Pages 側の設定画面に行き、カスタムドメインを削除します。（このとき勝手に CNAME の削除もやってくれました。）

そして Workers の設定画面に行き、カスタムドメインを設定します。

付け替えている間に一時的にサイトに接続できなくなると思うので、アクセスが多いサイトでは事前に告知しておくほうがよさそうです。
カスタムドメインでサイトを閲覧できることを確認しましょう。

確認出来たら Pages 側は不要になったので丸ごと消します。

 5. 自動デプロイの設定Builds のページを参考に、これまで通り GitHub に push したら勝手にデプロイされるようにします。
前手順でデプロイした Worker の設定画面を開いて、GitHub のリポジトリに接続します。
ビルドコマンド: npm run build

デプロイコマンド: npm run deploy
として保存しておきます。
また、ここでビルド時の環境変数 HUGO_VERSION を 0.156.0 と指定しておきます。
Workers のドキュメントでは HUGO_VERSION という環境変数についての記述がありませんでしたが、試した結果 Pages と同様に有効でした。

これを指定しない場合、2026/2/22 時点では Hugo v0.147.7 が使われました。
あとビルドキャッシュの設定など適宜やってください。

 終わりにCloudflare Workers では workers.dev ドメインを無効にできるところが良いですね。

Pages では pages.dev ドメインを無効にできなかったので Headers で pages.dev ドメインのページ全てに noindex をつけていました。
また Hugo は公式では npm パッケージとして提供されていないため、環境変数 HUGO_VERSION の指定がもし効かなかったらインストールスクリプトを書かなければいけないところでした。

しかし Hugo の作者は HUGO_VERSION が Hugo standard edition にしか対応していないという理由から、あえて自力でスクリプトを書く方法を紹介しています。下記がそのリポジトリです。
https://github.com/jmooring/hosting-cloudflare-worker
Workers だとプレビュー環境と本番環境でビルド時環境変数を設定し分けることができないように見えるので、細かく制御したい場合はスクリプトを書いたり、GitHub Actions 等の別の方法でデプロイを行ったりするほうが良さそうです。