zfb
GitHub リポジトリ

検索したい単語を入力

いつでも検索バーを開ける

トラブルシューティング

作成 2026年7月6日更新 2026年11月7日Takeshi Takatsudo

具体的な修正方法つきの既知の失敗モード — インストール、bundle 設定、import query、module worker、プロジェクトルート外の import、削除されたバンドラーセレクタ、組み込み時の `.ts` 設定。

このページで扱うこと

直接名前を付けて解説する価値があるほど頻繁に出てくる失敗モードを、症状ベースで索引したものです。それぞれについて、実際に目にするメッセージと修正方法を示します。あなたの問題がここにない場合は、リンク先の概念/ガイドのページが、各機能の土台となる挙動全体を扱っています。

unsupported island registration … has unsupported initializer

症状: production build が非ゼロで終了し、 target Target has unsupported initializer という接頭辞の未対応 island 登録を報告します。スキャナーは既存の factory member 形式と、証明済み ローカル const object literal からの 1 段 spread を受け付けます。 コンポーネントを探すために factory を実行したり、任意の object を評価したり することはありません。

原因: factory parameter は読み取り専用に保ち、すべての直接呼び出しで object literal を渡す必要があります。spread source は同じ module の const object literal に束縛された識別子であり、ネストした spread と 値の escape がない場合に限り使えます。引数と source には静的な data property だけを指定できます。選択キーは各 literal 内で 1 回だけ指定でき ますが、literal 間の衝突は許可され、左から右へ最後に出た値が勝ちます。 同じ factory の直接呼び出しは、引き続き同じ関数定義を選ぶ必要があります。 先行する条件値を後続の具体値で上書きできますが、最終値が host.Counter ?? Counter、三項演算子、Counter || Other なら拒否されます。

対処: factory parameter を読み取り専用にし、object literal で直接呼び 出します。必要ならローカルの静的 spread を使いますが、外側の引数に object 変数を渡してはいけません。最初に該当した factory 理由を修正します。

診断理由修正方法
mutable target bindingconst の target 束縛を使い、再代入しません。
parameter <name> has a default valuedefault を削除し、すべての呼び出しで object を明示します。
destructured parameter <name> uses a rest patternrest pattern を削除し、名前付きの静的 property だけを分割代入します。
parameter <name> is written or escapes at <loc>parameter を静的 member 読み取りか const object pattern だけに使い、書き込み、削除、引き渡し、alias、返却、spread をしません。
factory <F> escapes as a value at <loc>F の参照をすべて直接呼び出しにし、渡す、保存する、返す、bind/apply する、JSX として描画する操作を避けます。
factory <F> has no call site in the scanned modules必要な object literal を使う直接呼び出しをスキャン対象 module に追加するか、固定 target を使います。
call site at <loc> passes too few arguments宣言された位置に parameter を渡します。
call site at <loc> spreads positional argumentsparameter の位置までの位置引数を明示します。
call site at <loc> passes a non-literal argument外側の引数を object literal にします。spread には同一 module の const object literal を使い、ネストした spread、未対応 property、選択キーの重複、禁止された参照/書き込み/export を含めません。createBoundary(deps) は deps がローカル定数でも拒否されます。
property Counter missing at call site <loc>展開後の object に選択 property を追加します。
call site at <loc> selects Counter conditionally (??, ternary, ||)最終値を静的な関数束縛にするか、host/default の選択を公開 server composition seam に移します。
property Counter at <loc> is not a function binding1 つの関数束縛に解決できる値を使います。host.Counter のような runtime/opaque object receiver は証明できません。既存の resolver 理由が後ろに付く場合があります。
call sites disagree: <loc> passes Counter, <loc> passes Otherすべての呼び出しで同じ関数定義を選ぶか、固定ターゲット wrapper を分けます。
parameter deps is written or escapes at <loc>inner({ ...deps }) や inner(deps) では既存の読み取り専用契約を守ります。spread は関数間転送を追加しません。
boundary wrapper escapes into an opaque containerbare return の固定 Island wrapper や汎用転送 boundary wrapper を map に保存しません。Fragment で囲んだ固定ターゲット map を使います。
boundary wrapper escapes into an opaque object汎用 wrapper を省略記法の object value として保存せず、到達可能な固定ターゲット wrapper に置き換えます。

factory の診断には source location 付きの既存接頭辞と一般 rewrite suffix が続きます。選択キーを 1 つの literal 内に明示的に 2 回書くと、値が同じ でも後続 spread が上書きしても拒否されます。選択しない data key の重複は 引き続き許可されます。最終値を調べる前に source の構文全体を検証するため、 勝つ override で未対応構文を隠すことはできません。

downstream の zudo-doc 修正は公開 composition seam migration です。 機能設定は 2 段のネストした server factory に残し、呼び出し側で DefaultPanelIsland と HostPanelIsland の別々の描画を選び、 描画済みの子を通常の server PanelSlot に渡します。有効で host が なければ default を描画し、host があれば host を優先します。機能が無効なら どちらも描画しません。default suppression があり host がなければ何も描画せず、 host があれば host を描画します。コンポーネント関数や描画済み server child は Island JSON prop にしません。これは consumer の source/API migration であり、 consumer 自身で検証が必要です。このドキュメントは downstream browser parity を 主張しません。

map では MDX components にある Fragment で囲んだ固定ターゲットの手順を 維持します。map に格納された bare return 固定 wrapper と汎用転送 boundary entry は拒否されます。map key が Island でも、 children ?? null の SSR passthrough は SDK boundary ではありません。

ロックされた acceptance 行は factory-static-spread、factory-composition-default、 factory-composition-host-override、 factory-composition-settings-disabled、 factory-composition-default-suppressed、 factory-composition-host-with-default-suppressed、 factory-map-default、factory-map-host-override、 factory-map-settings-disabled です。Islands ガイド に各 route marker と操作を記載しています。両方が有効な client export で PropsReceiver が固定 target の場合、関数を Island JSON prop に渡すと、 より後の SSR で ZR_ISLAND_PROPS PropsReceiver: ZR_PROPS_FUNCTION at props.component になります。

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 なしでインストール を参照してください。

Linux で GLIBC が見つからない

症状: Linux バイナリが起動を拒否する。典型的には AWS Amplify Hosting、CodeBuild、あるいは RHEL 9 系のホストで発生します。

.../@takazudo/zfb-linux-x64-gnu/zfb: /lib64/libm.so.6: version `GLIBC_2.35' not found (required by .../@takazudo/zfb-linux-x64-gnu/zfb)

原因: プリビルドの Linux バイナリは glibc に動的リンクされているため、バイナリがリンクされた glibc より古い glibc を持つホストではロードできません。メッセージに出ているバージョンが、そのバイナリに必要なものです。

  • 3.1.0 までの リリースは Ubuntu 22.04 上でリンクされており、glibc 2.35 を必要とします。Amazon Linux 2023(AWS Amplify Hosting と CodeBuild のデフォルトビルドイメージ)および RHEL / Rocky / AlmaLinux 9 は glibc 2.34 なので、これらのリリースでは zfb build を起動できません。

  • それ以降の リリースは Amazon Linux 2023 コンテナ内でリンクされており、必要なのは glibc 2.34 です。上記のディストリビューションはこれを満たします。Ubuntu 22.04 以降と Debian 12 以降は引き続き動作します。Ubuntu 20.04 と Debian 11(glibc 2.31)は引き続き未対応です。

対処:

  • @takazudo/zfb を 3.1.0 より新しいリリースに更新してください。Linux パッケージはそのまま Amazon Linux 2023 と RHEL 9 系ホストで動作します。バイナリが参照する最大バージョンを確認したい場合は、node_modules/@takazudo/zfb-linux-x64-gnu/ のバイナリに対して strings zfb | grep GLIBC_2.3 を実行してください。

  • 3.1.0 以前に固定していて AWS Amplify Hosting を使っている場合は、アプリの カスタムビルドイメージ を glibc 2.35 以降のものに切り替えてください(例: public.ecr.aws/docker/library/node:24-bookworm、Debian 12、glibc 2.36)。このイメージには Amplify の nvm が入っていないため、amplify.yml から nvm use / nvm install の行を削除してください。イメージ自身の Node がすでに PATH 上にあります。

  • glibc 2.34 未満のその他のホストでは、代わりに Debian 12 / Ubuntu 22.04 コンテナ内でビルドしてください。

2.12.0 のインストールで ERR_PNPM_TRUST_DOWNGRADE

症状: pnpm のオプトイン設定 trustPolicy を no-downgrade にしていると、@takazudo/zfb* のいずれかを 2.12.0 でインストール/アップグレードする際に失敗します。

ERR_PNPM_TRUST_DOWNGRADE High-risk trust downgrade for "@takazudo/zfb@2.12.0" (possible package takeover)

Trust checks are based solely on publish date, not semver. A package cannot be
installed if any earlier-published version had stronger trust evidence. Earlier
versions had provenance attestation, but this version has no trust evidence.

trustPolicy はオプトイン(デフォルトは off)で、pnpm 10.21 以降で利用できます。既存のロックファイルで回避できるかどうかは、使っているバージョンによって異なります。

インストール方法pnpm 10.21 – 11.1pnpm 11.2 以降
新規/強制的な解決失敗失敗
pnpm install --frozen-lockfile成功失敗

pnpm 11.2 で、解決済みロックファイルの各エントリに対して有効なサプライチェーンポリシーを再適用する検証パスが追加されました。そのため、すでに 2.12.0 を固定しているロックファイルをコミットしていても、11.1 では通り、11.2 では失敗します。

原因: 2.12.0 のパッケージには npm の provenance attestation が付いていない一方、2.11.0 には付いています。これはパッケージの乗っ取りではありません。2.12.0 は zfb の published-release recovery パス — すでに公開済みのタグを再ビルドする、main からの workflow_dispatch 実行 — を通じて公開されました。その実行における GitHub OIDC のアイデンティティは、成果物が実際にビルドされた古いタグのコミットではなく main のワークフローコミットを指すため、出所を誤って示す attestation を付けるくらいならと、意図的に attestation なしで公開しています。この経緯は issue #2623 に記録されています。

通常のインストールで取得される 6 つのうち 5 つのパッケージが影響を受けます。@takazudo/zfb-darwin-x64 が検出されなかったのは、2.12.0 まで attestation が付いておらず、pnpm が比較する対象を持たなかったからです。2.13.0 以降は、他のパッケージと同様に attestation が付与されています。

対処: npm のバージョンはイミュータブルなので、2.12.0 自体が後から attestation を得ることはありません。次の順で検討してください。

  1. 2.13.0 以降に上げる。それらのリリースは通常のタグ/リリースパスを通り provenance が復活するため、ダウングレード判定が解消されます。これが本来の修正です。

  2. まだアップグレードできない場合は 2.11.0 に留まる。こちらは attestation があり、影響を受ける 2.12.0 を回避できます。

  3. どうしても今 2.12.0 が必要な場合は、pnpm-workspace.yaml の trustPolicyExclude で該当パッケージだけを除外する。他のすべての依存関係についてはポリシーが有効なままになります。

    trustPolicy: no-downgrade
    trustPolicyExclude:
      - "@takazudo/zfb@2.12.0"
      - "@takazudo/zfb-darwin-arm64@2.12.0"
      - "@takazudo/zfb-linux-arm64-gnu@2.12.0"
      - "@takazudo/zfb-linux-x64-gnu@2.12.0"
      - "@takazudo/zfb-win32-x64-msvc@2.12.0"

    各エントリでバージョンを固定しておくと、アップグレード時に除外が自動的に失効します。なお、名前のパターンとバージョンを組み合わせることはできません("@takazudo/zfb*@2.12.0" は ERR_PNPM_INVALID_TRUST_POLICY_EXCLUDE で拒否されます)。上記のように厳密な name@version を列挙するか、全バージョンの除外を許容できる場合は "@takazudo/zfb*" のようなバージョンなしの glob を使ってください。

trustPolicy 自体を無効化しても回避できますが、これら 5 つではなくすべての依存関係についてガードが外れます。範囲を限定した除外を優先してください。

@takazudo/zfb-darwin-x64 2.20.3 のインストールで ERR_PNPM_TRUST_DOWNGRADE

症状: pnpm のオプトイン設定 trustPolicy を no-downgrade にしていると、@takazudo/zfb-darwin-x64 を 2.20.3 でインストール/アップグレードする際に失敗します。

ERR_PNPM_TRUST_DOWNGRADE High-risk trust downgrade for "@takazudo/zfb-darwin-x64@2.20.3" (possible package takeover)

pnpm はホストの OS に関係なくすべての optionalDependencies を解決するため、macOS x64 ホストに限らず、どの OS の利用者にも影響します。

原因: 2.20.3 は --fast-mac エスケープハッチを使ってリリースされ、zfb-darwin-x64 に --provenance なしで公開されました。この パッケージの attestation の欠落が最初に解消された 2.13.0(上記の 2.12.0 の項を参照)以降、2.20.2 まではすべて attestation が付いていたため、2.20.3 は恒常的なギャップではなく、正真正銘のダウングレードです。当時はこれを公開前に検知できませんでした。このケースをブロックする preflight チェックとリリーススキル側のゲートは、まだ存在していなかったためです。

対処: npm のバージョンはイミュータブルなので、2.20.3 自体が後から attestation を得ることはありません。次の順で検討してください。

  1. 2.20.4 以降に上げる。それらのリリースは通常の provenance-first な CI パスを通り attestation が復活するため、ダウングレード判定が解消されます。これが本来の修正です。

  2. まだアップグレードできない場合は 2.20.2 に留まる。こちらは attestation があり、影響を受ける 2.20.3 を回避できます。

  3. どうしても今 2.20.3 が必要な場合は、pnpm-workspace.yaml の trustPolicyExclude でこのパッケージだけを除外する。

    trustPolicy: no-downgrade
    trustPolicyExclude:
      - "@takazudo/zfb-darwin-x64@2.20.3"

trustPolicy 自体を無効化しても回避できますが、このパッケージだけでなくすべての依存関係についてガードが外れます。範囲を限定した除外を優先してください。

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 専用のビルド時マクロです。そのため zfb は、島のバンドラーがファイルを目にする前に、サポートされる唯一の形式を自分で展開します。サポートされるのは、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 式が不正な場合は、最初に影響を受けるバンドルの実行時に バンドラーのパースエラーとして現れることもあります。

原因: 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 の値は、自動的に引用符が付く文字列ではなく生の JavaScript 式です。

対処: 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を参照してください。

ZFB_BUNDLER または ZFB_ROLLDOWN_* を含むメッセージでビルドが失敗する

症状: zfb がどのコマンドも実行する前に ZFB_BUNDLER=…: the esbuild bundler backend and its ZFB_BUNDLER selector were removed; zfb always bundles natively. Unset ZFB_BUNDLER. (または ZFB_ROLLDOWN_PROTOTYPE についての同じメッセージ)で終了する。あるいはビルドが ZFB_ROLLDOWN_TRAILING_ROOT_DIRS_UNSUPPORTED か ZFB_ROLLDOWN_RAW_CSS_UNSUPPORTED で始まるメッセージで失敗する。

原因: zfb はページ、islands、クライアントスクリプト、module worker、TypeScript プラグイン、zfb.config.ts を Rolldown でネイティブにバンドルします。esbuild はもう同梱も実行もしないため、ZFB_BUNDLER と ZFB_ROLLDOWN_PROTOTYPE のセレクタは削除されました。どちらかを(値にかかわらず)設定するとエラーになるので、esbuild を要求し続けるスクリプトが黙って別のバンドラーでビルドされることはありません。またバンドラーは 2 つの入力を拒否します。compilerOptions.rootDirs と、ディレクトリで終わる paths のターゲットを併用する tsconfig.json と、JavaScript バンドルへ生の CSS として読み込まれるモジュールです。

対処: ZFB_BUNDLER と ZFB_ROLLDOWN_PROTOTYPE を外してください。rootDirs のエラーは、rootDirs を削除するか、末尾の区切り文字なしで specifier をマッピングすれば解消します。生の CSS のエラーは、スタイルを CSS Modules(*.module.css)か zfb の CSS パイプライン(Wind ユーティリティと、Lightning CSS でコンパイルされる手書きスタイルシート)経由でインポートすれば解消します。

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

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

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

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

組み込みの zfb-server が .ts 設定にはコンパイラワーカーが必要だと報告する

症状: zfb-server を組み込んだ Rust ホスト(ライブラリとして組み込む を参照)が、config_path が zfb.config.ts ファイルを指しているときに、build() で … is a `.ts` config, which needs a compiler worker というエラーで失敗する。

原因: TypeScript 設定は、ホスト自身の実行ファイルから起動される、監視下のネイティブなコンパイラワーカーでバンドルされます。ライブラリがそのランチャーを推測することはありません。

対処: config_path を zfb.config.json ファイルに切り替える(ワーカーは一切不要 — 最もシンプルな修正)か、main の最初で zfb_server::run_compiler_worker_if_requested() を呼び出し、ServerBuilder::compiler_worker(WorkerLauncher::new(std::env::current_exe()?).arg(zfb_server::COMPILER_WORKER_ARG)) を渡してください。完全な説明は ライブラリとして組み込む: 設定形式 を参照してください。

prerender = false のルートが常に 405 を返す

症状: SSR ルートの POST/PUT/DELETE ハンドラが、期待どおりのメソッドを使い他の点でも正しいリクエストに対してまで、常に 405 Method Not Allowed を返す。

原因: そのルートのデフォルトエクスポートが、受信した Request を受け取るつもりの仮引数を宣言している。

export default async function Handler(request: Request) {
  if (request.method !== "POST") {
    return new Response("Method Not Allowed", { status: 405 });
  }
  // ...
}

zfb がページのデフォルトエクスポートを呼ぶときに渡すのは、Request ではなくそのページの props オブジェクトです。コントラクトの全体は デフォルトエクスポートが受け取るのは props であり Request ではない を参照してください。つまり上の request の実体は {}(あるいは { params }、あるいはそのルートの paths() / getStaticProps() の props)であり、request.method は undefined を読み、undefined !== "POST" が成り立つため、ハンドラは無条件に 405 を返します。何も例外を投げず、しかも Request は props を受け取る仮引数に対しても妥当な TypeScript の型注釈なので tsc --noEmit も通ります。コンパイルはきれいに通り、実行時に静かに壊れるということです。

次のコマンドで直接検出できます。

grep -rn 'export default \(async \)\?function \w\+(\s*request\s*:' pages/

対処: 仮引数を外す(あるいは実際に必要な props だけを分割代入する — { params } など)。そのうえで、本物の Request は getCloudflareContext() から読んでください。

import { getCloudflareContext } from "@takazudo/zfb-adapter-cloudflare";

export default async function Handler() {
  const { request } = getCloudflareContext();
  if (request.method !== "POST") {
    return new Response("Method Not Allowed", { status: 405 });
  }
  // ...
}

zfb check はこの形を検出して非ゼロで終了します。zfb dev と zfb build はビルドを失敗させずに警告します。実際の 405 を踏んだのではなくそれらの警告からここへたどり着いた場合も、原因と対処は上と同じです。

zfb の shadow ビルドディレクトリを調査したい

症状: zfb build または zfb dev が失敗する、あるいは想定外の挙動をし、その原因がバンドラーに渡す前に zfb が生成するもの — 生成された injected route の shim、解決済みの node_modules レイアウト、合成された tsconfig.json — に関係していそうだと分かった。しかしプロセスが終了する頃には(ビルド失敗時であっても)、それらを保持していた一時ディレクトリはすでに消えている。

原因: zfb は該当するツリーの shadow コピーを tempfile 管理の一時ディレクトリに生成してビルドし、プロセス終了時にそれを削除します — これは通常の動作であり、後から /tmp を探しても見つからない理由です。

対処: どちらか一方の opt-in 環境変数を設定すると、shadow ツリーを削除せずディスク上に残せます。対象となる一時ディレクトリの範囲はそれぞれ異なり、どちらも保持したディレクトリを自動では回収しません — 調査が終わったら自分で削除してください。

変数対象保持されるもの
ZFB_KEEP_BUILD_SHADOW=1zfb build のみバンドラの shadow ルート、その exact-node_modules 分離ルート、そしてパッケージルートのオーバーレイ(プロジェクトがパッケージルートを登録している場合)。ビルド失敗時も保持されます。保持された各パスは stderr に一度だけ出力されます。zfb build: 環境変数 を参照してください。
ZFB_KEEP_SHADOW_SESSION=1zfb dev のみdev サーバーがプロセス全体で使い回す、唯一の永続的な shadow セッション一時ディレクトリ。このフラグを設定せずに後で zfb dev を起動すると、内部の経過時間しきい値を超えた時点で以前保持したディレクトリが回収されます — デバッグセッション全体でフラグをエクスポートし続けてください(そのディレクトリを作成した起動時だけでは不十分です)。zfb dev: 環境変数 を参照してください。

どちらも対象範囲は狭く限定されています。zfb build/zfb dev のすべての一時ファイル生成元を網羅しているわけではありません(設定の読み込み、islands のバンドラー、CSS、プラグイン解決はどちらの対象外です)。また、一方を設定してももう一方のサブコマンドには影響しません — ZFB_KEEP_BUILD_SHADOW は zfb dev に影響せず、ZFB_KEEP_SHADOW_SESSION は zfb build に影響しません。

Revision History

Takeshi Takatsudo作成: 2026-07-07T04:21:00+09:00更新: 2026-11-07T18:50:56Z