Bun Compile — 単一ファイル実行ファイル
TypeScript の CLI を bun build --compile で 1 個のバイナリにまとめる: 実測した数値、クロスコンパイル、そして bunfs の落とし穴。
TypeScript で CLI ツールを作りました。自分のマシンでは完璧に動きます。次はそれをユーザーに渡したい — ところがそのユーザーには Node.js も Bun も、インストールする前提もありません。
bun build --compile が解決するのがまさにこの問題です。コマンド 1 つ、ファイル 1 つで、何も入っていないマシンでも動く結果が手に入ります。
bun build --compile ./cli.ts --outfile myclibash本当にそれだけです。ただしこの 1 行の裏には実測した数値、実質的なトレードオフ、そして実際に踏める落とし穴があります。この記事はそれらのすべてを扱います。
[!NOTE] 以下のすべての数値と挙動は、Bun 1.4.3 / macOS arm64 (Apple Silicon) でローカルに実測したもので、他の記事から写したものではありません。コマンドはすべて再現できます。
「単一ファイル実行ファイル」とは何か (ELI5)#
友人に夕食を作って差し上げると想像してみてください。
- 普通の方法: レシピ (あなたの
.tsファイル)、買い物リスト (package.json)、そして「まずスーパーに行ってから」という指示を渡します。相手には「ちゃんと動く台所 (Node.js か Bun)」と、インターネットと、時間が必要です。壊れうる要素が 3 つあります。 - コンパイルする方法: あなたが料理ごと作り上げ、容器に密封して渡します。相手は開けて食べるだけ。台所も準備も買い物も不要です。
bun build --compile がその容器です。出力は ネイティブバイナリ で、中に 3 つのものが入っています。
- あなたのコード (バンドル済み、tree-shake 済み)
- import したすべての npm パッケージ
- JavaScriptCore を含む Bun ランタイムの完全なコピー
重要な帰結があります。出力のサイズを決めるのはコードではなくランタイムです。 これは後で実測します。
基準点: コマンド 1 つで何ができるか#
#!/usr/bin/env bun
import { $ } from "bun";
const args = Bun.argv.slice(2);
console.log("args:", args);
console.log("bun version:", Bun.version);
if (args[0] === "pkg") {
console.log((await $`echo bundled-ok`.text()).trim());
}tsbun build --compile ./cli.ts --outfile ./myclibashBun 1.4.3 / macOS arm64 での実測結果:
[27ms] bundle 1 modules
[260ms] compile ./myclitextそして:
$ ./mycli hello world
args: [ "hello", "world" ]
bun version: 1.4.3
$ ./mycli pkg
args: [ "pkg" ]
bun version: 1.4.3
bundled-okbashビルドは約 300 ms。結果は 67.6 MB のバイナリで、何も入っていないマシンで動きます。
気になる数字#
サイズ: ペイロードはランタイム#
| ビルドフラグ | バイナリサイズ | 備考 |
|---|---|---|
--compile | 67.6 MB (70,862,450 bytes) | macOS arm64 の基準値 |
--compile --minify | 67.6 MB | 完全に同一 — ランタイムと比較すれば、あなたのコードは誤差レベルです |
--compile --minify --sourcemap --bytecode | 67.6 MB | サイズは同じ。bytecode の注意点は後述 |
ここで --minify は何も縮小しません。これはバグではありません。アプリが 3 KB のソースなら、minify で節約できるのは 67.6 MB 中わずか 1 KB 程度。minify は数 MB の依存関係をバンドルするときに効きますが、この場面では、思っているようなレバーにはなりません。
[!TIP] バイナリサイズが問題なら、
--minifyは答えではありません。レバーはランタイムであり、--compileビルドからそれを取り除くことはできません。ベースレイヤを共有する Docker イメージで配るか、npm に publish してユーザーのランタイムに任せましょう。
起動時間: 効果はアプリの規模に比例する#
同じマシン上で、各コマンドを 3 回ウォームアップしてから 20 回実行して計測しました。
| コマンド | 1 回あたりの時間 |
|---|---|
node -e "console.log('x')" | 26.7 ms |
bun run simple.ts (1 モジュール) | 6.9 ms |
| コンパイル済み (1 モジュール) | 6.1 ms |
bun run index.ts (400 モジュール) | 15.7 ms |
| コンパイル済み (400 モジュール) | 9.6 ms |
見出しだけを見ると本次活动の効果を oversell しやすいので、率直にお読みください。
- 1 ファイルのスクリプトでは、コンパイルで節約できるのは約 0.8 ms。プロセス起動が支配的で、勝てる余地はほとんどありません。
- 400 個のモジュールを持つアプリでは、6.1 ms 節約 — 起動時間で 39% 削減です。
理由は Bun のドキュメントの記述そのものです。通常の Bun は起動のたびにディスクからファイルを読み、パスを解決し、パースしてトランスパイルします。--compile はこのコストをビルド時点に移します。コードが多いほど、移すものが増えていきます。
[!WARNING] 「コンパイル済みバイナリは瞬時に起動する」という文句は、修飾詞なしで引用しないでください。正確な言い方はこうです。束ねたコードが多いほど、節約できる起動時間が大きい — そして些細なスクリプトでは差分はノイズの範囲です。
クロスコンパイル: 一度ビルドして、どこへでも配る#
Linux バイナリを作るのに Linux マシンは不要です。--target を渡すだけです。
# Linux x64 (多くのサーバー)
bun build --compile --target=bun-linux-x64 ./index.ts --outfile myapp
# Linux ARM64 (Graviton, Raspberry Pi)
bun build --compile --target=bun-linux-arm64 ./index.ts --outfile myapp
# Windows x64 / ARM64 (.exe は自動で付与される)
bun build --compile --target=bun-windows-x64 ./src/cli.ts --outfile myapp
bun build --compile --target=bun-windows-arm64 ./src/cli.ts --outfile myapp
# macOS
bun build --compile --target=bun-darwin-arm64 ./src/cli.ts --outfile myapp
bun build --compile --target=bun-darwin-x64 ./src/cli.ts --outfile myappbash対応ターゲット:
--target | OS | アーキテクチャ | libc |
|---|---|---|---|
bun-linux-x64 | Linux | x64 | glibc |
bun-linux-arm64 | Linux | arm64 | glibc |
bun-linux-x64-musl | Linux | x64 | musl |
bun-linux-arm64-musl | Linux | arm64 | musl |
bun-windows-x64 | Windows | x64 | — |
bun-windows-arm64 | Windows | arm64 | — |
bun-darwin-x64 | macOS | x64 | — |
bun-darwin-arm64 | macOS | arm64 | — |
Apple Silicon の Mac から Linux x64 へクロスコンパイルし、実際の ELF バイナリが得られることを確認しました。
bun build --compile --target=bun-linux-x64 ./cli.ts --outfile ./app-linux-x64
[3.482s] compile ./app-linux-x64 bun-linux-x64-v1.4.3
$ file ./app-linux-x64
ELF 64-bit LSB executable, x86-64, dynamically linked, interpreter /lib64/ld-linux-x86-64.so.2textmusl ターゲットは Alpine コンテナ向けのバイナリになります。
$ file ./app-musl
ELF 64-bit LSB executable, x86-64, dynamically linked, interpreter /lib/ld-musl-x86_64.so.1text[!NOTE] 初回のクロスコンパイルではターゲットのランタイムをダウンロードします (今回の計測で約 40 MB、所要時間 約 3.5 秒)。2 回目以降はキャッシュされるためビルドは速くなります。CI では
~/.bun/install/cacheをキャッシュして、ジョブごとに再ダウンロードしないようにしてください。
挙動を変えるフラグ#
--define — ビルド時定数#
bun build --compile --define BUILD_VERSION='"1.2.3"' --define BUILD_TIME='"2024-01-15T10:30:00Z"' \
src/cli.ts --outfile myclibashconsole.log(BUILD_VERSION); // 1.2.3
console.log(typeof BUILD_VERSION); // stringtsBun はこれらをビルド時にインライン化するため、実行時コストはゼロで、デッドコードの除去が可能になります。
--sourcemap — 元のソースを指すスタックトレース#
コンパイル済みバイナリでは、思っていた以上に重要なオプションです。これがないとスタックトレースが仮想ファイルシステムを指してしまいます。
--sourcemap=linked ありの場合:
error: kaboom from original source
at boom (crash.ts:2:9)
at crash.ts:4:1textなしの場合:
error: kaboom from original source
at boom (/$bunfs/root/crash2:4:9)
at /$bunfs/root/crash2:6:5text同じバグ、同じメッセージ — ただ前者のみがどのファイルのどの行を開けばよいかを教えてくれます。配るものには常に --sourcemap を使ってください。
--bytecode — と top-level await のバグ#
--bytecode は JavaScriptCore のパース作業を実行時からビルド時へ移します。Bun 1.4.3 で再現可能な問題が見つかりました。
const v = await Promise.resolve(42);
console.log("tla:", v);ts$ bun build --compile --bytecode --outfile ./b-tla ./tla.ts
1 | const v = await Promise.resolve(42);
^
error: "await" can only be used inside an "async" function
at /private/tmp/bcompile/tla.ts:1:17
1 | const v = await Promise.resolve(42);
^
error: Unexpected .
at /private/tmp/bcompile/tla.ts:1:24bash$ bun build --compile --outfile ./b-tla-nobc ./tla.ts # 同じファイル、--bytecode なし
[2ms] bundle 1 modules
[171ms] compile ./b-tla-nobc
$ ./b-tla-nobc
tla: 42bashつまり: top-level await と --bytecode の組み合わせはビルドできません (2 回中 2 回再現)。一方、同じファイルは --bytecode なしなら問題なくビルドして実行できます。top-level await のないスクリプトは --bytecode でも問題なくコンパイルされます。
[!WARNING] エントリポイントが top-level の
awaitを使っている場合 (await Bun.$、await Bun.file(...)、あるいはトップレベルのfetchなど、ごく普通に登場します)、Bun 1.4.3 では--bytecodeを有効にしないでください。コンパイルできないビルドを配る前に、自分のエントリポイントを確認してください。
--compile-exec-argv — ランタイムフラグを埋め込む#
bun build --compile --compile-exec-argv="--smol --user-agent=MyBot" ./app.ts --outfile myappbashconsole.log(process.execArgv); // ["--smol","--user-agent=MyBot"]ts再コンパイルせずに実行時にフラグを変更することもできます。環境変数 BUN_OPTIONS を使います。
BUN_OPTIONS="--cpu-prof" ./myappbashbunfs の落とし穴 — 最も驚かされるもの#
コードがバイナリの中に入った時点で、ディスク上に src/ ディレクトリはもうありません。Bun は埋め込まれたファイルを 仮想ファイルシステム bunfs として公開し、/$bunfs/root にマウントされます。
コンパイル済みバイナリを実行してパスを出力しました。
import.meta.path: /$bunfs/root/mycli
import.meta.dir: /$bunfs/root
execPath: /private/tmp/bcompile/myclitext3 つの帰結があります。
import.meta.pathは実在するパスではありません。 自身の位置を基準にファイルを開くコードは壊れます。バイナリの実パスが必要な場合はprocess.execPathを使ってください。import.meta.dirはbunfsを指します。 埋め込まれたアセット を探すには正しい場所ですが、スクラッチファイルを書く場所ではありません。- 埋め込まれたアセットは bunfs パスで参照します。 Bun はファイル名をハッシュ化するため、推測はできません。
埋め込みファイルの読み込み — import attribute が重要#
import assetPath from "./asset.txt" with { type: "file" };
import readmeText from "./README.txt" with { type: "text" };tsここが 別の 2 ファイル になっている点に注目してください。偶然ではなく、下の警告にその理由があります。
この 2 行は 相互に置き換えられません。
// { type: "file" } → パスが得られる。内容ではない
console.log(assetPath); // "/$bunfs/root/asset-b45kncad.txt"
console.log(await Bun.file(assetPath).text()); // "embedded-asset-content"
// { type: "text" } → 内容が直接得られる
console.log(readmeText); // "Hello from README"ts埋め込まれたファイルをすべて列挙したい場合は Bun.embeddedFiles を使います。これは Blob オブジェクトの配列です。
for (const blob of Bun.embeddedFiles) {
console.log(blob.size, blob.type); // 23 text/plain;charset=utf-8
console.log(await blob.text()); // "embedded-asset-content"
}ts[!TIP]
type: "file"とtype: "text"の区別は、ほぼ全員がつまずく点です。内容だけが必要ならtype: "text"を使ってください。type: "file"は、実ファイルが必要な対象にパスを渡したい場合 (例:Bun.file()、Bun.serve()、ネイティブライブラリ) だけ使います。
同じファイルを 2 回 import しない#
もう 1 つ、細かい罠があります。同じファイルを異なる attribute 付きで 2 回 import すると、Bun はそれらを 1 つのモジュールにまとめます。そして 最初 の import の attribute が勝ち、両方の 変数に適用されます。
// "text" の import が先 → どちらも内容
import a from "./asset.txt" with { type: "text" };
import b from "./asset.txt" with { type: "file" };
console.log(JSON.stringify([a, b])); // ["embedded-asset-content\n","embedded-asset-content\n"]
// "file" の import が先 → どちらもパス
import c from "./asset.txt" with { type: "file" };
import d from "./asset.txt" with { type: "text" };
console.log(JSON.stringify([c, d])); // ["/$bunfs/root/asset-b45kncad.txt","/$bunfs/root/asset-b45kncad.txt"]ts[!WARNING] Bun 1.4.3 での実測結果です。各ペアで 両方の 変数が同じ種類の値を受け取ります。パスか内容かは、先に来る import 的一方に従います。両方とも必要なら、そのアセットを 別々の 2 モジュール から import するか、
Bun.embeddedFilesを走査してください。
フルスタックの実行ファイル#
--compile はフロントエンドのアセットもバンドルします。HTML を import すると、Bun はそれを、参照している CSS と JS とともに埋め込みます。
import { serve } from "bun";
import index from "./index.html";
const server = serve({
routes: {
"/": index,
"/api/hello": { GET: () => Response.json({ message: "Hello from API" }) },
},
});
console.log(`Server running at http://localhost:${server.port}`);tsbun build --compile ./server.ts --outfile myappbash実行してみましょう — サーバーが起動し、ポートを割り当て、埋め込んだフロントエンドを正しい MIME タイプとキャッシュヘッダーで配信しました。ファイル 1 個でサーバーとクライアント、どこにでもデプロイできます。
あなたの CLI は Bun そのものになれる#
Bun 1.2.16 以降、実行ファイルは Bun CLI 自体にフォールバックできます。
BUN_BE_BUN=1 ./myapp installbash検証しました。通常実行では "you should not see this" と表示するスクリプトからビルドしたバイナリが、その文字列をそのまま表示し、BUN_BE_BUN=1 を設定すると実際の Bun バージョンを表示しました。これにより、パッケージのインストールや依存関係のバンドル、他のファイルの実行もできる CLI を、2 つ目のバイナリを配らずに提供できます。
npm 依存関係はどうなるの?#
バンドルされます。picocolors を import したスクリプトをコンパイルし、node_modules を別の場所へ移動してからバイナリを実行しました。
colored: hello-from-a-npm-packagetextそれでも動作しました。バイナリは対象マシンで何も必要としません — 依存関係のディレクトリすら不要です。
コンパイルしてはいけない場合#
コンパイルは無料ではなく、常に正解ではありません。
実践上の警告:
- macOS Gatekeeper. インターネットからダウンロードした未署名のバイナリは隔離され、ユーザーが許可するまでブロックされます。署名済みバイナリを配るか、承認手順を案内してください。
- Docker イメージ. 67 MB のバイナリを全レイヤーにコピーするとイメージのサイズが膨らみます。軽量なランタイムベースレイヤーが勝ることが多いです。
- ネイティブアドオン. ビルドマシン向けにコンパイルされた
.nodeアドオンは、やはりコンパイル済みバイナリです。クロスコンパイルはネイティブ C++ アドオンをクロスコンパイルしません。--targetビルドを CI 上で対象アーキテクチャのまま行うべき主な理由がこれです。 - 频繁な更新. リリースごとに 67 MB のファイルを配るのは、npm に小さなパッケージを publish するより遅いです。
Bun.build() API#
上記はすべてプログラムからも使えます。ビルドスクリプトにちょうどよい形です。
const result = await Bun.build({
entrypoints: ["./cli.ts"],
compile: {
outfile: "./mycli",
target: "bun-linux-x64",
},
define: {
BUILD_VERSION: JSON.stringify("1.2.3"),
},
minify: true,
sourcemap: "linked",
bytecode: true,
});
console.log(result.success, result.outputs.length);tsTL;DR#
# 1 ファイル、どこでも動く
bun build --compile ./cli.ts --outfile mycli
# ノート PC 上でクロスコンパイル
bun build --compile --target=bun-linux-arm64 ./cli.ts --outfile mycli
# 実際に配る設定
bun build --compile --minify --sourcemap=linked ./cli.ts --outfile myclibash- macOS arm64 での出力は 67.6 MB — Bun ランタイムの部分であり、あなたのコードではありません。
--minifyで小さくなりません。 - 起動時間の節約はコード量に比例します。1 ファイルスクリプトで 約 0.8 ms、400 モジュールのアプリで 6.1 ms (39%)。
- コンパイル済みバイナリ内の
import.meta.pathは/$bunfs/root/<name>です。実パスにはprocess.execPathを使ってください。 with { type: "file" }は パスを、with { type: "text" }は 内容を返します。- 同じアセットを 2 回 import しないでください — 最初の import の attribute が勝ち、両方の変数に適用されます。
- エントリポイントが top-level
awaitを使うなら--bytecodeは避ける — Bun 1.4.3 ではビルドできません。 --sourcemapは必ず付けてください。無いとスタックトレースが/$bunfs/rootを指し、ソースを指しません。