BunでPlaywrightをバイナリ化した際の「Cannot find package」エラーの解決策

Bunの --compile 機能を用いてPlaywrightを含むJavaScriptコードを単一バイナリ化し、Windows上でLinux向けにクロスコンパイルした場合、「Cannot find package」エラーが発生して実行に失敗することがある。この問題は、バイナリ生成時にホストOS（Windows）の絶対パスが固定化されてしまうことが原因であり、解決策として依存ライブラリを外部化（External）する手法が有効である。

1. 発生するエラー

Windows上で --target=bun-linux-x64 を指定してビルドしたバイナリをLinuxで実行した際、以下のようなエラーが発生する。

Linux環境で実行しているにもかかわらず、ビルドマシン（Windows）の絶対パスを探しに行ってしまい、実行に失敗する現象である。

2. 原因：ビルド時のパスリーク

この問題の根本的な原因は、主に以下の2点にある。

絶対パスの埋め込み: Playwright（および playwright-core）は、実行時に自身の package.json を読み込んでバージョン確認などを行う挙動がある。Bunのコンパイラがクロスコンパイルを行う際、このパス解決が「ビルド時の絶対パス」としてバイナリ内に固定されてしまう。
仮想ファイルシステム（$bunfs）の解決失敗: 本来、Bunは依存関係をバイナリ内部の仮想ファイルシステムに閉じ込めようとするが、Playwrightのラッパーなど一部のライブラリを経由した動的なrequireは、この仕組みを回避してホストOSのファイルシステムを直接参照しようとしてしまう。

3. 解決策：外部依存化（External）

最も確実な解決策は、問題となるライブラリをバイナリに含めず、実行環境の node_modules を参照させることである。

ビルドコマンドの修正

package.json のビルドスクリプトに --external フラグを追加し、Playwright関連をバンドル対象から除外する。

{
  "scripts": {
    "build": "bun build ./index.js --compile --target=bun-linux-x64 --external playwright --external playwright-core --external electron --outfile bld/my-app"
  }
}

実行環境での準備

バイナリが「外部のライブラリ」を探しに行く仕様に変わるため、実行するLinux環境側で該当の依存ライブラリをインストールする。
Terminal window
```
# バイナリと同じディレクトリで実行する
npm install playwright-core@1.58.2
```
バージョンはビルド時に使用したものと合わせるのが安全である。
ブラウザの用意

Playwrightが使用するブラウザ本体を、実行環境にインストールする。すでにインストール済みの場合は不要である。
Terminal window
```
npx playwright install chromium
```

ライブラリの階層を浅くするため、ソースコード内でも直接 playwright-core を呼び出すように書き換えると、Bunのバンドルがより安定する。

// Before
const { chromium } = require('playwright');

// After
const { chromium } = require('playwright-core');

まとめ

Bunのクロスコンパイルにおいて、Playwrightのようなファイルシステム依存の巨大ライブラリを含めると、絶対パスの固定化によるエラーが発生することがある。
解決策として、--compile 時に --external フラグを付与し、重いライブラリは外部依存として切り離す「ハイブリッド構成」が推奨される。
この手法により、単一バイナリの利便性を活かしつつ、パス解決エラーをスマートに回避可能である。

他の記事を探す