コンテンツにスキップ

Zensical + uv + Cloudflare Pages のビルドエラーと解決方法

Zensical で作成したサイトを Cloudflare Pages にデプロイした際、Python パッケージのインストール処理でエラーが発生した。 原因は Cloudflare Pages による依存関係の自動インストールと、サイト用リポジトリのパッケージ化だった。 SKIP_DEPENDENCY_INSTALL と uv のオプションを利用して解決したので、その内容を記録する。

1. はじめに

Zensical で作成したサイトを Cloudflare Pages で公開するため、GitHub リポジトリと連携して自動デプロイする環境を構築した。

Python のパッケージ管理には uv を使用している。

当初、Cloudflare Pages の Build command に次のコマンドを設定した。

curl -LsSf https://astral.sh/uv/install.sh | sh && export PATH="$HOME/.local/bin:$PATH" && uv sync --frozen && uv run zensical build

しかし、デプロイ時に Zensical のビルド処理まで進まず、エラーが発生した。

2. 発生したエラー

Cloudflare Pages のビルドログを確認すると、次のメッセージが出力されていた。

Installing project dependencies: pip install .
Processing /opt/buildhome/repo
...
Building wheels for collected packages: zensical-sample
Building wheel for zensical-sample (pyproject.toml): finished with status 'error'
...
Error: Expected a Python module at: src/zensical_sample/__init__.py
...
ERROR: Failed building installable wheels for some pyproject.toml based projects (zensical-sample)

特に重要なのは、次のエラーメッセージである。

Error: Expected a Python module at: src/zensical_sample/__init__.py

Cloudflare Pages がリポジトリを Python パッケージとしてインストールしようとしていた。

しかし、今回のリポジトリは Python パッケージを開発するためのものではなく、Zensical で静的サイトを生成するためのものである。

そのため、Python モジュールとして必要なファイルが存在せず、インストールに失敗していた。

3. 原因

原因は、Cloudflare Pages による依存関係の自動インストールだった。

Cloudflare Pages はリポジトリ内の pyproject.toml を検出し、ビルドコマンドを実行する前に次の処理を実行していた。

pip install .

この処理は、リポジトリ自体を Python パッケージとしてインストールするものである。

一方、今回のプロジェクトでは pyproject.toml を uv による依存関係管理に利用している。

サイト生成用のリポジトリなので、リポジトリ自体を Python パッケージとしてインストールする必要はない。

したがって、次の2点を修正することにした。

  1. Cloudflare Pages の自動依存関係インストールを停止する。
  2. uv で依存パッケージだけをインストールする。

4. 解決方法

4.1 自動依存関係インストールを停止

Cloudflare Pages の管理画面から、対象プロジェクトの環境変数を設定する。

Settings → Environment variables

次の環境変数を追加する。

項目 値
Variable name SKIP_DEPENDENCY_INSTALL
Value 1

Production と Preview の両方に設定する。

この設定により、Cloudflare Pages による自動依存関係インストールを停止できる。

4.2 Build command を変更

次に、Build command を変更する。

変更後のコマンドは次のとおり。

curl -LsSf https://astral.sh/uv/install.sh | sh && export PATH="$HOME/.local/bin:$PATH" && uv sync --frozen --no-install-project && uv run --no-sync zensical build

変更前と変更後を比較する。

変更前

curl -LsSf https://astral.sh/uv/install.sh | sh && export PATH="$HOME/.local/bin:$PATH" && uv sync --frozen && uv run zensical build

変更後

curl -LsSf https://astral.sh/uv/install.sh | sh && export PATH="$HOME/.local/bin:$PATH" && uv sync --frozen --no-install-project && uv run --no-sync zensical build

変更した箇所は次の2つである。

オプション 役割
--no-install-project プロジェクト自体のインストールを省略する
--no-sync uv run 実行時の依存関係の再同期を省略する

uv sync --frozen --no-install-project によって、ロックファイルに従って依存パッケージをインストールしつつ、リポジトリ自体のインストールを省略できる。

また、uv run --no-sync によって、Zensical の実行時に再度同期処理が行われることを防ぐ。

4.3 最終的な設定

Cloudflare Pages の設定をまとめる。

Build configuration

項目 設定値
Framework preset None
Build command 上記のコマンド
Build output directory site
Deploy command 空欄
Preview command 空欄

Environment variables

変数 値
SKIP_DEPENDENCY_INSTALL 1

5. デプロイ結果

上記の2点を変更して再デプロイしたところ、ビルドが正常に完了した。

今回の修正によって、次の流れでサイトを生成できるようになった。

GitHub リポジトリを取得
        |
        v
uv をインストール
        |
        v
uv sync --frozen --no-install-project
        |
        v
uv run --no-sync zensical build
        |
        v
site/ に静的サイトを生成
        |
        v
Cloudflare Pages で公開

6. まとめ

今回のエラーは、Zensical 自体の問題ではなく、Cloudflare Pages が pyproject.toml を検出してリポジトリ自体を Python パッケージとしてインストールしようとしたことが原因だった。

解決のポイントは次の2つである。

  • SKIP_DEPENDENCY_INSTALL=1 を設定して Cloudflare Pages の自動インストールを停止する。
  • uv sync --frozen --no-install-project を使い、リポジトリ自体をインストールせずに依存パッケージだけを同期する。

Python の pyproject.toml は、必ずしも Python パッケージを作成するためだけのものではない。uv による開発環境や依存関係の管理にも利用できる。

Cloudflare Pages と uv を組み合わせる場合は、Cloudflare 側の自動インストールと uv 側の依存関係管理が重複しないように注意したい。

参考