Bun Compile — Executable Một File
Đóng gói CLI TypeScript của bạn thành một binary tự chứa với bun build --compile: số liệu thực tế, cross-compilation và những cái bẫy về bunfs.
Bạn viết xong một CLI tool bằng TypeScript. Chạy rất đẹp trên máy bạn. Giờ bạn muốn đưa nó cho người dùng — và người đó không có Node.js, không có Bun, cũng không muốn chạy npm install trước khi dùng được.
Đó chính là vấn đề mà bun build --compile giải quyết. Một lệnh, một file, kết quả chạy được trên máy không cài gì cả.
bun build --compile ./cli.ts --outfile myclibashĐúng vậy, chỉ cần vậy thôi. Nhưng phía sau dòng lệnh một phút đó là những con số thật, những đánh đổi thật, và vài cái bẫy thật — bài viết này nói về cả ba.
[!NOTE] Mọi con số và hành vi dưới đây đều được đo trực tiếp với Bun 1.4.3 trên macOS arm64 (Apple Silicon), không sao chép từ bài viết nào khác. Các lệnh đều có thể chạy lại để kiểm chứng.
“Executable một file” thực chất là gì? (ELI5)#
Hãy tưởng tượng bạn nấu một bữa cơm cho người bạn của mình.
- Cách thường thấy: bạn đưa họ công thức nấu (các file
.tscủa bạn), danh sách đi chợ (package.json), và dặn họ phải đi siêu thị trước (npm install). Họ cần một cái bếp (Node.js hoặc Bun) hoạt động được, cộng thêm internet, cộng thêm thời gian. Ba thứ có thể hỏng. - Cách compile: bạn nấu sẵn cả món, đóng kín vào hộp rồi đưa cho họ. Họ mở ra và ăn. Không cần bếp, không cần đi chợ.
bun build --compile chính là cái hộp đó. Kết quả là một binary native chứa ba thứ:
- Code của bạn, đã được bundle và tree-shake.
- Mọi npm package bạn đã import.
- Một bản sao đầy đủ của Bun runtime, bao gồm JavaScriptCore.
Hệ quả quan trọng: kích thước output bị chi phối bởi runtime, không phải bởi code của bạn. Chúng tôi đã đo điều này bên dưới.
Mốc baseline: một lệnh tạo ra gì#
#!/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 ./myclibashKết quả đo được với Bun 1.4.3 / macOS arm64:
[27ms] bundle 1 modules
[260ms] compile ./myclitextRồi:
$ ./mycli hello world
args: [ "hello", "world" ]
bun version: 1.4.3
$ ./mycli pkg
args: [ "pkg" ]
bun version: 1.4.3
bundled-okbashBuild mất khoảng 300 ms, và kết quả là một binary 67.6 MB chạy được trên máy không cài gì.
Những con số đáng quan tâm#
Kích thước: runtime chính là payload#
| Cờ build | Kích thước binary | Ghi chú |
|---|---|---|
--compile | 67.6 MB (70,862,450 bytes) | Mốc baseline trên macOS arm64 |
--compile --minify | 67.6 MB | Giống hệt nhau — code của bạn chỉ là sai số so với runtime |
--compile --minify --sourcemap --bytecode | 67.6 MB | Cùng kích thước; xem lưu ý về bytecode bên dưới |
--minify ở đây không làm nhỏ đi đâu cả, và đó không phải bug. Nếu app của bạn chỉ 3 KB source, minify cũng chỉ tiết kiệm được khoảng 1 KB trong tổng 67.6 MB. Minify có ý nghĩa khi bạn đang bundle mấy megabyte dependency — nhưng ở đây nó không phải đòn bẩy mà mọi người tưởng.
[!TIP] Nếu kích thước binary mới là vấn đề của bạn,
--minifykhông phải câu trả lời. Đòn bẩy là runtime, và bạn không thể gỡ nó khỏi bản build--compile. Hãy ship một Docker image có base layer dùng chung, hoặc publish lên npm để runtime của người dùng lo.
Startup: lợi ích tỉ lệ với độ lớn của app#
Chúng tôi đo 20 lần chạy mỗi lệnh (sau 3 lần warmup) trên cùng một máy:
| Lệnh | Thời gian mỗi lần chạy |
|---|---|
node -e "console.log('x')" | 26.7 ms |
bun run simple.ts (1 module) | 6.9 ms |
| compiled (1 module) | 6.1 ms |
bun run index.ts (400 module) | 15.7 ms |
| compiled (400 module) | 9.6 ms |
Hãy đọc con số này một cách thành thật, vì dễ phóng đại lắm:
- Với script một file, compile tiết kiệm khoảng 0.8 ms. Thời gian spawn tiến trình chiếm phần lớn; gần như không có gì để thắng.
- Với app có 400 module thật, compile tiết kiệm 6.1 ms — giảm 39% thời gian khởi động.
Lý do chính xác là như tài liệu Bun mô tả: bình thường Bun đọc file từ đĩa, resolve path, parse và transpile mỗi lần khởi động. --compile chuyển chi phí đó sang thời điểm build. Càng nhiều code, càng nhiều thứ được chuyển đi.
[!WARNING] Đừng trích dẫn “binary đã compile khởi động tức thì” mà không kèm điều kiện. Câu nói trung thực là: càng bundle nhiều code, bạn càng tiết kiệm được thời gian khởi động — và với script tầm thường thì khác biệt nằm trong nhiễu.
Cross-compilation: build một lần, ship khắp nơi#
Bạn không cần máy Linux để tạo ra binary Linux. Chỉ cần truyền --target:
# Linux x64 (đa số server)
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 được thêm tự động)
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 myappbashCác target được hỗ trợ:
--target | OS | Kiến trúc | 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 | — |
Chúng tôi cross-compile từ Mac Apple Silicon sang Linux x64 và nhận được một binary ELF thật:
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.2textTarget musl cho bạn binary chạy được trong container Alpine:
$ file ./app-musl
ELF 64-bit LSB executable, x86-64, dynamically linked, interpreter /lib/ld-musl-x86_64.so.1text[!NOTE] Lần cross-compile đầu tiên sẽ tải runtime của target về (khoảng 40 MB trong lần chạy của chúng tôi) và mất ~3.5 s. Sau đó nó được cache lại và build rất nhanh. Trên CI, hãy cache
~/.bun/install/cacheđể không phải tải lại ở mỗi job.
Những cờ thực sự thay đổi hành vi#
--define — hằng số thời gian build#
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 inline các giá trị này lúc build, nên chúng không tốn gì lúc runtime và giúp dead-code elimination.
--sourcemap — stack trace chỉ đúng file gốc#
Cái này quan trọng hơn bạn nghĩ trong một binary đã compile, vì không có nó thì stack trace sẽ trỏ vào một filesystem ảo.
Với --sourcemap=linked:
error: kaboom from original source
at boom (crash.ts:2:9)
at crash.ts:4:1textKhông có nó:
error: kaboom from original source
at boom (/$bunfs/root/crash2:4:9)
at /$bunfs/root/crash2:6:5textCùng một bug, cùng một thông báo — nhưng chỉ bản đầu cho bạn biết mở file nào, dòng nào. Luôn dùng --sourcemap cho bất cứ thứ gì bạn ship.
--bytecode — và lỗi top-level await#
--bytecode chuyển việc parse của JavaScriptCore từ runtime sang thời điểm build. Chúng tôi tìm ra một vấn đề tái lập được với nó trên 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 # cùng file, không --bytecode
[2ms] bundle 1 modules
[171ms] compile ./b-tla-nobc
$ ./b-tla-nobc
tla: 42bashNên: top-level await + --bytecode không build được, tái lập được (2 trên 2 lần thử), trong khi cùng file đó build và chạy hoàn hảo nếu bỏ --bytecode. Một script không có top-level await thì compile với --bytecode không vấn đề gì.
[!WARNING] Nếu entrypoint của bạn dùng top-level
await(rất phổ biến vớiawait Bun.$,await Bun.file(...), hoặcfetchở top-level), đừng bật--bytecodetrên Bun 1.4.3. Hãy kiểm tra entrypoint của chính bạn trước khi ship một bản build không compile được.
--compile-exec-argv — bake cờ runtime vào binary#
bun build --compile --compile-exec-argv="--smol --user-agent=MyBot" ./app.ts --outfile myappbashconsole.log(process.execArgv); // ["--smol","--user-agent=MyBot"]tsBạn cũng có thể đổi cờ lúc runtime mà không cần compile lại, bằng biến môi trường BUN_OPTIONS:
BUN_OPTIONS="--cpu-prof" ./myappbashCái bẫy bunfs — thứ sẽ khiến bạn bất ngờ#
Một khi code của bạn nằm trong binary, không còn thư mục src/ nào trên đĩa nữa. Bun expose các file đã nhúng thông qua một filesystem ảo tên là bunfs, được mount tại /$bunfs/root.
Chúng tôi chạy một binary đã compile và in ra các đường dẫn:
import.meta.path: /$bunfs/root/mycli
import.meta.dir: /$bunfs/root
execPath: /private/tmp/bcompile/myclitextBa hệ quả:
import.meta.pathkhông phải đường dẫn thật. Bất kỳ code nào mở file tương đối so với vị trí của chính nó sẽ hỏng. Hãy dùngprocess.execPathnếu cần đường dẫn thật của binary.import.meta.dircủa bạn trỏ vàobunfs. Đó là chỗ đúng để tìm asset đã nhúng, nhưng không phải chỗ đúng để ghi file tạm.- Asset đã nhúng được gọi bằng đường dẫn bunfs. Bun hash tên file, nên bạn không thể đoán ra.
Đọc file đã nhúng — import attribute rất quan trọng#
import assetPath from "./asset.txt" with { type: "file" };
import readmeText from "./README.txt" with { type: "text" };tsChú ý đây là hai file khác nhau. Không phải ngẫu nhiên — lý do nằm ở cảnh báo ngay bên dưới.
Hai dòng này không thể hoán đổi cho nhau:
// với { type: "file" } → bạn nhận ĐƯỜNG DẪN, không phải nội dung
console.log(assetPath); // "/$bunfs/root/asset-b45kncad.txt"
console.log(await Bun.file(assetPath).text()); // "embedded-asset-content"
// với { type: "text" } → bạn nhận NỘI DUNG trực tiếp
console.log(readmeText); // "Hello from README"tsNếu muốn duyệt qua toàn bộ file đã nhúng, hãy dùng Bun.embeddedFiles — nó là một mảng các object 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] Sự phân biệt
type: "file"vớitype: "text"làm hầu hết mọi người trượt chân. Nếu bạn chỉ cần nội dung, hãy dùngtype: "text". Chỉ dùngtype: "file"khi bạn cần truyền đường dẫn cho thứ gì đó thực sự cần một file thật —Bun.file(),Bun.serve(), hoặc một thư viện native.
Đừng import cùng một file hai lần#
Có một cái bẫy tinh vi hơn nữa. Nếu bạn import cùng một file hai lần với hai attribute khác nhau, Bun gộp chúng thành một module duy nhất — và attribute của import đầu tiên thắng, rồi áp dụng cho cả hai biến:
// import "text" đứng trước → cả hai biến đều là NỘI DUNG
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"]
// import "file" đứng trước → cả hai biến đều là ĐƯỜNG DẪN
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] Đo trên Bun 1.4.3: trong mỗi cặp, cả hai biến đều nhận cùng một kiểu — hoặc đường dẫn, hoặc nội dung, tuỳ vào import nào đứng trước. Nếu bạn cần cả hai, hãy import asset đó ở hai module khác nhau, hoặc duyệt
Bun.embeddedFiles.
Executable full-stack#
--compile còn bundle cả asset frontend. Import HTML của bạn và Bun sẽ nhúng nó, cùng với CSS và JS mà nó tham chiếu:
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 myappbashChúng tôi đã chạy nó — server khởi động, cấp một port, và phục vụ frontend đã nhúng với MIME type và cache header đúng. Một file, server cộng client, deploy ở bất cứ đâu.
CLI của bạn cũng có thể là Bun#
Kể từ Bun 1.2.16, một executable có thể fallback về Bun CLI đầy đủ:
BUN_BE_BUN=1 ./myapp installbashChúng tôi đã kiểm chứng: một binary được compile từ script in ra "you should not see this" thì in đúng câu đó khi chạy bình thường, và in ra phiên bản Bun thật khi đặt BUN_BE_BUN=1. Đây là cách để bạn ship một CLI vừa có thể cài package, bundle dependency, hoặc chạy file khác — mà không cần ship thêm binary thứ hai.
Còn npm dependency thì sao?#
Chúng được bundle vào. Chúng tôi compile một script import picocolors, sau đó di chuyển node_modules đi nơi khác rồi chạy lại binary:
colored: hello-from-a-npm-packagetextVẫn chạy tốt. Binary không cần gì trên máy đích — kể cả thư mục dependency.
Khi nào không nên compile#
Compile không miễn phí, và không phải lúc nào cũng là câu trả lời đúng:
Cảnh báo thực tế:
- macOS Gatekeeper. Binary chưa ký tải từ internet sẽ bị quarantine và chặn cho tới khi người dùng duyệt. Hãy ship binary đã ký hoặc hướng dẫn người dùng cách duyệt.
- Docker image. Một binary 67 MB bị copy vào mọi layer của image sẽ làm phình image. Một base layer runtime mỏng thường thắng.
- Native addon. Một addon
.nodeđược compile cho máy build của bạn vẫn là một binary đã biên dịch; cross-compile không cross-compile native addon C++. Đây là lý do chính để giữ build--targettrong CI trên đúng kiến trúc đích. - Cập nhật thường xuyên. Ship một file 67 MB mỗi lần release chậm hơn nhiều so với publish một package nhỏ lên npm.
API Bun.build()#
Tất cả những gì trên cũng dùng được theo kiểu lập trình, và đó là thứ bạn cần trong một build script:
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#
# Một file, chạy ở mọi nơi
bun build --compile ./cli.ts --outfile mycli
# Cross-compile ngay trên laptop của bạn
bun build --compile --target=bun-linux-arm64 ./cli.ts --outfile mycli
# Cấu hình chúng tôi dùng để ship
bun build --compile --minify --sourcemap=linked ./cli.ts --outfile myclibash- Output 67.6 MB trên macOS arm64 — đó là Bun runtime, không phải code của bạn.
--minifysẽ không làm nó nhỏ lại. - Lợi ích khởi động tỉ lệ với độ lớn code: ~0.8 ms cho script một file, 6.1 ms (39%) cho app 400 module.
import.meta.pathbên trong binary đã compile là/$bunfs/root/<tên>. Dùngprocess.execPathđể lấy đường dẫn thật.with { type: "file" }cho bạn đường dẫn;with { type: "text" }cho bạn nội dung.- Đừng import cùng một asset hai lần — attribute của import đầu tiên thắng và áp dụng cho cả hai biến.
- Tránh
--bytecodenếu entrypoint dùng top-levelawait— nó không build được trên Bun 1.4.3. - Luôn ship kèm
--sourcemap; nếu không, stack trace sẽ trỏ vào/$bunfs/rootthay vì source của bạn.