bun-runtime

Bun Runtime

Bun 是一個快速的全能 JavaScript 執行環境與工具組：包含執行環境、套件管理工具、打包工具與測試執行器。

使用時機

• 偏好 Bun：用於新的 JS/TS 專案、重視安裝/執行速度的腳本、使用 Bun 執行環境的 Vercel 部署，以及想要單一工具鏈（執行 + 安裝 + 測試 + 建置）時。
• 偏好 Node：需要最大生態系相容性、使用假設 Node 的舊工具，或依賴套件已知有 Bun 問題時。

使用情境：採用 Bun、從 Node 遷移、撰寫或除錯 Bun 腳本/測試，或在 Vercel 或其他平台上設定 Bun。

運作方式

• 執行環境：可無痛取代 Node 的相容執行環境（基於 JavaScriptCore，以 Zig 實作）。
• 套件管理工具：bun install 速度遠快於 npm/yarn。目前 Bun 預設鎖定檔為 bun.lock（文字格式）；舊版使用 bun.lockb（二進位格式）。
• 打包工具：內建打包與轉譯器，適用於應用程式與函式庫。
• 測試執行器：內建 bun test，提供類似 Jest 的 API。

從 Node 遷移：將 node script.js 替換為 bun run script.js 或 bun script.js。使用 bun install 取代 npm install；大多數套件皆可運作。使用 bun run 執行 npm 腳本；bun x 用於類似 npx 的一次性執行。支援 Node 內建模組；建議優先使用 Bun 的 API 以獲得更好效能。

Vercel：在專案設定中將執行環境設為 Bun。建置：bun run build 或 bun build ./src/index.ts --outdir=dist。安裝：使用 bun install --frozen-lockfile 以確保可重複部署。

範例

執行與安裝

# 安裝依賴（建立/更新 bun.lock 或 bun.lockb）
bun install

# 執行腳本或檔案
bun run dev
bun run src/index.ts
bun src/index.ts

腳本與環境變數

bun run --env-file=.env dev
FOO=bar bun run script.ts

測試

bun test
bun test --watch

// test/example.test.ts
import { expect, test } from "bun:test";

test("add", () => {
  expect(1 + 2).toBe(3);
});

執行環境 API

const file = Bun.file("package.json");
const json = await file.json();

Bun.serve({
  port: 3000,
  fetch(req) {
    return new Response("Hello");
  },
});

最佳實務

• 提交鎖定檔（bun.lock 或 bun.lockb）以確保可重複安裝。
• 偏好使用 bun run 執行腳本。對於 TypeScript，Bun 原生支援執行 .ts 檔案。
• 保持依賴更新；Bun 及其生態系演進快速。