Hugo BeautifulhugoテーマをSubmoduleからHugo Modulesに移行した

このサイトで導入しているHugoのBeautifulhugoは今までsubmoduleとして利用してきましたが、hugo modules形式へ変更しました。

環境

Githubから自分のリポジトリをCloneして作業します。

まず、ローカル環境の確認です

❯ go version
go version go1.22.6 darwin/arm64
❯ hugo version
hugo v0.131.0+extended darwin/arm64 BuildDate=2024-08-02T09:03:48Z VendorInfo=brew

themeはbeautifulhugoをsubmoduleでインストールしている

hugo modules初期化

$ hugo mod init github.com/user/scribble
go: creating new go.mod: module github.com/user/scribble
go: to add module requirements and sums:

beautifulhugoテーマの取得

$ hugo mod get github.com/halogenica/beautifulhugo
go: added github.com/halogenica/beautifulhugo v0.0.0-20240711164100-bd5ebaab69c6

hugo.toml

下記を追記し、themeの項目をコメントアウト

[[module.imports]]
  path = "github.com/halogenica/beautifulhugo"

git submodule関連の設定の削除

submodule関連の設定やファイルを削除します。

.git/config がsubmodule関連の設定を持っているので、その記述も削除します。

$ rm -rf themes
$ rm .gitmodules

起動確認

$ hugo server -D

起動が確認できたら、GithubへPushし完了

補足

なお、Cloudflareの環境変数でGO_VERSIONは特に設定する必要はなさそうです。

また、今後のテーマ更新については、hugo mod get -u コマンドを使用してテーマを更新し、その後、hugo mod tidy で不要な依存関係を削除して整理する事になるかと思います。

_vendorディレクトリに注意

hugo mod vendor を実行すると _vendor ディレクトリにテーマの中身がコピーされますが、これを .gitignore に入れて管理外にしていると、ローカルとCloudflare Pagesでビルド結果がずれる原因になります。

Hugoは _vendor が存在するとそちらを優先して使うため、go.mod でテーマのバージョンを更新しても、ローカルの _vendor が古いままだと更新前のテーマでビルドされ続けてしまいます。一方Cloudflare Pages側は毎回リポジトリを新規Cloneするため _vendor が存在せず、go.mod通りの最新テーマでビルドされます。

その結果、「ローカルでは問題なく表示されるのに、Cloudflareにデプロイすると崩れる」という現象が起こり得ます。ブラウザやCloudflareのキャッシュをクリアしても直らないのは、そもそもキャッシュの問題ではなく、ローカルとCloudflareで異なるバージョンのテーマがビルドされているためです。

_vendor はテーマのコードをローカルに凍結コピーしておくためのオプション機能で、hugo mod vendor を実行しない限り生成されません。作らなければHugoは常に go.mod/go.sum が指すバージョンをモジュールプロキシ経由で取得してビルドするため、ローカルとCloudflareで参照するテーマのバージョンが必ず一致します。Cloudflare Pages側もどのみちhugo: downloading modulesのステップでネットワーク経由の取得を行っているため、_vendorによるオフラインビルドの恩恵は今回の構成では特に活きません。

そのため、_vendor はそもそも作らない（hugo mod vendor を使わない）運用にするのが、今回のような差分が起きなくなる一番シンプルな対策です。

関連項目