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点を修正することにした。
- Cloudflare Pages の自動依存関係インストールを停止する。
- 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 側の依存関係管理が重複しないように注意したい。