トラブルシューティング

具体的な修正方法つきの既知の失敗モード — インストール、bundle 設定、import query、module worker、プロジェクトルート外の import、esbuild バイナリのエラー。

curl | sh インストールがリリースタグを解決できない

症状: curl インストーラ が次のいずれかで終了する。

error: could not resolve the latest release tag from GitHub API

error: could not resolve the latest prerelease tag from GitHub API (no prerelease found in the last 30 releases)

原因: install.sh は何かをダウンロードする前に、GitHub Releases API からタグを解決します。

• ZFB_VERSION が未設定の場合、最新の 非プレリリース リリースを要求します。通常はこれで解決できます。失敗するのは、API に到達できない、レート制限を受けている、あるいはリクエストが何らかの理由でブロックされている場合だけです。Node なしでインストール を参照してください。

• ZFB_VERSION=latest-prerelease の場合、直近 30 件のリリースを走査して "prerelease": true が付いたものを探します。直近 30 件のいずれもプレリリースでない場合（たとえば、その後いくつかの安定版がリリースされ、プレリリースがそのウィンドウから押し出された場合）、同じように解決に失敗します。

対処:

• レート制限を受けている場合やプロキシ環境の場合: リリースページ から厳密なタグを固定してください（例: ZFB_VERSION=v1.0.0）。タグ解決のリクエスト自体をスキップできます。

• プレリリースを使いたいが latest-prerelease の解決に失敗する場合（直近 30 件にプレリリースが 1 件も含まれていない場合）: 代わりにプレリリースのタグを直接固定してください（例: ZFB_VERSION=v0.1.0-next.99）。

musl/Alpine is not supported yet

症状:

[zfb] musl/Alpine is not supported yet — no @takazudo/zfb-linux-*-musl package exists.
      Use a glibc-based Linux image (e.g. Debian/Ubuntu) instead of Alpine.

原因: zfb は glibc にリンクされたプリビルドのプラットフォームバイナリしか配布しておらず、@takazudo/zfb-linux-*-musl パッケージは存在しません。npm ラッパー（packages/zfb/bin/detect-musl.mjs）は musl ランタイム（Alpine の /lib/ld-musl-* 動的ローダー、あるいは Node 自身のランタイムレポートに glibc バージョンが存在しないこと）を検出し、glibc バイナリを不透明な動的ローダーエラーでクラッシュさせる代わりに、この親切なメッセージで失敗します。スタンドアロンの curl/PowerShell インストーラはこの方法で musl を検出できず（OS/CPU しかチェックしません）、glibc バイナリをダウンロードしてしまい、それが実行時にそのまま失敗します。

対処: Alpine の代わりに glibc ベースの Linux ベースイメージ（Debian、Ubuntu）を使ってください。Dockerfile でも、CI ランナーでも、任意のコンテナイメージでも同様です。今日、musl 上でネイティブに zfb を動かす回避策はありません。サポートされるプラットフォームのマトリクスは インストール と Node なしでインストール を参照してください。

import.meta.glob(...) のビルドエラー

症状（zfb build から。または zfb dev からは警告 + リバンドルのスキップ）:

zfb islands: `import.meta.glob(...)` cannot be safely shipped from one or more
files reachable from a "use client" island. zfb can currently expand eager
string-literal globs only when the glob call is in an island-reachable module
that is written as a real shadow copy; unsupported forms and globs found only in
raw-mirrored glob target/subtree files would ship to the browser unexpanded and
throw at hydration: <file> — ... Follow the remediation above for each file,
use the eager string-literal form where applicable, replace the glob with
explicit static imports, or move the usage to a server-only (non-"use client")
module. Tracked at https://github.com/Takazudo/zudo-front-builder/issues/1385
and https://github.com/Takazudo/zudo-front-builder/issues/1412.

原因: import.meta.glob は Vite 専用のビルド時マクロです。島をバンドルする esbuild はこれをネイティブには理解しないため、zfb は esbuild がファイルを目にする前に、サポートされる唯一の形式を自分で展開します。サポートされるのは、glob 呼び出しが島から到達可能なモジュール内にあり、そのモジュールが展開済みの実体あるシャドウコピーファイルとして書き出される場合の import.meta.glob("<string-literal>", { eager: true }) だけです。パターンはインポート元ファイル自身のディレクトリ配下に解決される必要があります。それ以外のすべて — デフォルトの lazy 形式、{ eager: false }、リテラルでないパターン、import/query/as オプション、../ でディレクトリを抜け出すパターン — は拒否されます。JS 風のファイルが raw-mirrored な glob ターゲット、またはサブツリー内の companion ファイルとしてだけ到達していて、その中に glob がある場合も拒否されます。そうしなければ、そのファイルは未展開のままブラウザへ配信され、hydration 中に例外を投げるためです。

対処: 完全なサポートマトリクスと代替手段は Islands: import.meta.glob のサポート を参照してください。使える場所では eager + 文字列リテラル形式に直し、ネストした glob は島から到達可能なモジュールへ hoist するか、raw-mirrored な glob ターゲット／サブツリー内ファイルを glob されたサブツリーの外へ移動するか、明示的な静的インポートへ置き換えてください。なお クライアントスクリプト（*.client.ts）は import.meta.glob を一切サポートせず、しかも島とは異なり、その失敗はビルド時には検出され ません。クライアントスクリプト: import.meta.glob はサポートされていません を参照してください。

bundle.loaders または bundle.define が拒否される

症状: 設定のロードが次のようなメッセージで失敗する。

bundle.loaders key ".asset" uses unsupported loader "file"; inline-only v1 accepts: ...
bundle.define key "import.meta.env.DEV" is reserved by zfb's bundle mode ...

生の define 式が不正な場合は、最初に影響を受けるバンドルの実行時に esbuild のパースエラーとして現れることもあります。

原因: loader のキーは . で始まり、text、json、base64、dataurl、binary、empty のいずれかを使い、.css、.module.css、.mdx、.md を上書きしない必要があります。アセットを生成する file と copy loader はサポートされません。また zfb は import.meta.env.DEV、import.meta.env.PROD、process.env.NODE_ENV を所有するため、ユーザーの define から置き換えることはできません。define の値は、自動的に引用符が付く文字列ではなく esbuild の生の式です。

対処: inline loader と予約されていない拡張子 / キーを選んでください。文字列の define では、置換式に JSON の引用符を含めます（例: __APP_NAME__: '"my-app"'）。完全なコントラクトとブラウザへの公開に関する警告は defineConfig: bundle 設定を参照してください。

?raw インポートが失敗する

症状: build、または dev 中のブラウザバンドルの更新が、unsupported import query form、does not resolve to an existing file、is not valid UTF-8 text のいずれかを報告する。

原因: zfb がサポートするのは、リテラルのプロジェクトローカル相対ターゲットと厳密な ?raw サフィックスを持つ静的な default import だけです。ターゲットは終端の UTF-8 テキストファイルです。dynamic import、named import、namespace import、side-effect import、type-only import、re-export、?url、追加のクエリパラメータ、リテラルでないパス、ルート外 / symlink 経由の escape、UTF-8 ではないターゲットは拒否されます。

対処: import を次の形にし、厳密なファイルがプロジェクトルート内に存在することを確認してください。

import text from "./file.ext?raw";

拡張子は何でもよく、bundle.loaders のエントリも不要です。Islands: ?raw でテキストをインポートする、またはクライアントスクリプトを参照してください。

Module worker が出力されない、または SharedWorker が失敗する

症状: worker constructor が書き換えられず worker-*.js companion も現れない、または build が unsupported SharedWorker を報告する。

原因: zfb は shadow されていないグローバルの Worker を、下記のリテラルな module 形式でだけ探索します。URL はクエリや fragment のない、厳密なプロジェクトローカル相対パスの JS / TS ファイルを指す必要があります。リテラルでない形式や classic worker はコントラクトの対象外です。探索は意図的にインストール済みの node_modules をたどりません。同じリテラル URL 形式を使う SharedWorker は、一見サポートされるように見える URL が書き換えられず実行時に 404 する状態を避けるため、明示的に拒否されます。

対処: first-party の dedicated worker には次の形式を使います。

const worker = new Worker(
  new URL("./worker.ts", import.meta.url),
  { type: "module" },
);

island の worker は /assets/worker-*.js、クライアントスクリプトの worker は /assets/client/worker-*.js に置かれます。書き換え後の URL はその安定名を維持し、厳密に 8 文字の小文字 16 進数である ?v= グラフハッシュを追加します。サポートされない形式や third-party の推移的 worker は、パッケージ固有のツールでバンドルしてください。Islands: Module workerを参照してください。

プロジェクトルート外への相対インポートが "Could not resolve" になる

症状: zfb build（または zfb dev）が esbuild の Could not resolve "../../../somewhere/outside.ts" エラーで失敗し、付随する zfb の注記が「シャドウコピーのビルド境界」を説明する。

原因: zfb は、esbuild を実行する前にプロジェクトルートを一時ディレクトリへシャドウコピーしてビルドします。プロジェクトルートより上へ歩く相対インポート（例: ../../../../packages/ui/src/button.tsx）は、そのシャドウコピーの外に解決されるため見つかりません。これは診断専用であり、解決可能なバグではありません。根本的な脱出は依然としてサポートされません。zfb は、意味のない一時ディレクトリのパスを漏らす代わりに、報告される エラーが実際の（シャドウでない）パスを示し、回避策を説明するようにするだけです。

対処: ルート外のターゲットを相対インポートではなくパッケージインポートとして公開してください。ターゲットパッケージの package.json にワイルドカードの exports エントリ（例: "./src/*": "./src/*"）を追加し、パッケージ指定子でインポートします（例: @scope/pkg/src/button.tsx）。node_modules（file:/ワークスペースリンクされたパッケージを含む）はシャドウコピーに含まれるため、パッケージ指定子のインポートは通常どおり解決されます。詳細は defineConfig: プロジェクトルート外のパスを監視する を参照してください。追跡は issue #1385 で行われています。

組み込みの zfb-server からの esbuild binary not found

症状: zfb-server を組み込んだ Rust ホスト（ライブラリとして組み込む を参照）が、config_path が zfb.config.ts ファイルを指しているときに "esbuild binary not found" エラーで失敗する。

原因: TypeScript の設定を評価するには、まずそれを esbuild でバンドルする必要がありますが、組み込みの zfb-server は zfb CLI のように自前の esbuild バイナリを同梱していません。

対処: config_path を zfb.config.json ファイルに切り替える（esbuild は一切不要 — 最もシンプルな修正）か、build() を呼び出す前に環境変数 ZFB_ESBUILD_BIN を利用可能な esbuild CLI バイナリに設定してください。完全な説明は ライブラリとして組み込む: 設定形式 を参照してください。