使用时机

在以下情况时使用此技能：

• 运行代码：直接执行 .ts、.tsx、.js、.jsx 文件，无需编译步骤
• 启动服务器：使用 Bun.serve() 或 Express、Elysia、Hono 等框架构建 HTTP 服务器
• 管理包：安装、添加、移除或审计 npm 依赖
• 测试：编写和运行支持 TypeScript 的、与 Jest 兼容的测试
• 打包：为浏览器、Node.js 或独立可执行文件创建优化的包
• 从 Node.js 迁移：将 Bun 引入现有的 Node.js 项目，只需极少的改动
• 全栈开发：在单个项目中构建服务器和客户端代码，支持 HTML 导入
• 开发工作流：使用监视模式、热重载或 REPL 进行交互式开发

快速参考

基本命令

文件类型支持（无需配置）

配置文件位置

• 本地：./bunfig.toml (项目根目录)
• 全局：$HOME/.bunfig.toml 或 $XDG_CONFIG_HOME/.bunfig.toml
• 合并规则：本地配置覆盖全局配置；命令行标志覆盖两者

常见的 bunfig.toml 配置节

[install]
linker = "hoisted"  # 或 "isolated" 以实现类似 pnpm 的行为
optional = true
dev = true
production = false

[test]
root = "."
coverage = false
timeout = 5000

[run]
shell = "system"  # 在 Windows 上也可以是 "bun"
bun = true        # 自动将 node 别名指向 bun

[define]
"process.env.DEBUG" = "'true'"

决策指南

何时使用 X 对比 Y

工作流程

1. 初始化项目

bun init my-app
cd my-app

这将创建 package.json、tsconfig.json、bunfig.toml 和一个起始 index.ts 文件。

2. 安装依赖

bun install
bun add react
bun add -d @types/react

Bun 读取 package.json，解析依赖，并创建 bun.lock（基于文本的锁文件）。

3. 编写并运行代码

创建 index.ts：

const server = Bun.serve({
  port: 3000,
  routes: {
    "/": () => new Response("Hello!"),
  },
});
console.log(`Listening on ${server.url}`);

运行它：

bun run index.ts
# 或
bun index.ts

4. 向 package.json 添加脚本

{
  "scripts": {
    "dev": "bun --watch run index.ts",
    "build": "bun build ./index.ts --outdir ./dist",
    "test": "bun test"
  }
}

运行：

bun run dev
bun run build
bun run test

5. 编写测试

创建 math.test.ts：

import { test, expect } from "bun:test";

test("2 + 2 = 4", () => {
  expect(2 + 2).toBe(4);
});

运行测试：

bun test
bun test --watch
bun test --coverage

6. 为生产环境打包

bun build ./index.ts --outdir ./dist --minify

对于可执行文件：

bun build ./cli.ts --outfile ./mycli --compile
./mycli

7. 发布前验证

• 运行测试：bun test
• 检查类型（如果使用 TypeScript）：bun run tsc --noEmit
• 构建：bun build ./index.ts --outdir ./dist
• 测试构建产物：node ./dist/index.js

常见陷阱

• Node.js 兼容性并非 100%：请查看 runtime/nodejs-compat 了解不支持的 API。大多数流行的包都能正常工作。
• 生命周期脚本默认被禁用：将包添加到 package.json 的 trustedDependencies 中以允许 postinstall 脚本。
• 自动安装可能掩盖缺失的依赖：在 bunfig.toml 中设置 [install] auto = "disable" 来尽早发现缺失的包。
• Bun 标志放在bun之后，而不是脚本之后：使用 bun --watch run dev，而不是 bun run dev --watch。
• 测试文件必须匹配模式：只有 *.test.ts、*_test.ts、*.spec.ts、*_spec.ts 会被自动发现。
• 锁文件格式已更改：Bun v1.2+ 使用基于文本的 bun.lock 而不是二进制的 bun.lockb。使用 bun install --save-text-lockfile 进行升级。
• 隔离安装可能会破坏某些包：如果遇到幻影依赖问题，请在 bunfig.toml 中切换到 linker = "hoisted"。
• bunfig.toml 中的环境变量：使用 $VAR_NAME 语法；Bun 会自动加载 .env、.env.local、.env.[NODE_ENV]。
• 打包器不是类型检查器：使用 tsc --noEmit 单独进行类型检查；bun build 只进行转译。
• HTML 导入仅适用于bun build --target=bun 或 bun --hot：它们不能直接与 bun run 一起工作。

验证清单

在使用 Bun 提交工作之前：

• 代码运行无错误：bun run index.ts
• 所有测试通过：bun test
• 无 TypeScript 错误（如果适用）：bun run tsc --noEmit
• 依赖已安装：bun install 完成且无错误
• 锁文件已提交：bun.lock 在版本控制中
• 构建成功：bun build ./index.ts --outdir ./dist 完成
• 未使用已弃用的模式（检查是否使用了仅限 Node.js 的 API）
• bunfig.toml 是有效的 TOML 文件（如果存在）
• package.json 中的脚本正确且经过测试
• 监视模式适用于开发：bun --watch run dev

资源

• 综合导航：https://bun.com/docs/llms.txt — 供智能体导航的完整页面列表
• 运行时 API：https://bun.com/docs/runtime — 文件 I/O、HTTP、网络、工作线程、环境变量
• 包管理器：https://bun.com/docs/pm/cli/install — 安装、添加、移除、工作区、注册表
• 打包器：https://bun.com/docs/bundler — 构建、代码分割、插件、可执行文件、优化
• 测试运行器：https://bun.com/docs/test — 编写测试、模拟、快照、覆盖率、监视模式

如需更多文档和导航，请参阅：https://bun.com/docs/llms.txt

每周安装量

209

来源

bun.sh/docs

首次出现

2026年3月2日

安全审计

SocketPass

安装于

opencode207

gemini-cli206

kimi-cli206

codex206

cursor206

amp206

When to Use

Reach for this skill when:

• Running code : Executing .ts, .tsx, .js, .jsx files directly without compilation steps
• Starting servers : Building HTTP servers with Bun.serve() or frameworks like Express, Elysia, Hono
• Managing packages : Installing, adding, removing, or auditing npm dependencies
• Testing : Writing and running Jest-compatible tests with TypeScript support
• Bundling : Creating optimized bundles for browsers, Node.js, or standalone executables
• Migrating from Node.js : Dropping Bun into existing Node.js projects with minimal changes
• Full-stack development : Building server and client code in a single project with HTML imports
• Development workflows : Using watch mode, hot reloading, or REPL for interactive development

Quick Reference

Essential Commands

File Type Support (No Configuration Needed)

Configuration Locations

• Local : ./bunfig.toml (project root)
• Global : $HOME/.bunfig.toml or $XDG_CONFIG_HOME/.bunfig.toml
• Merging : Local overrides global; CLI flags override both

Common bunfig.toml Sections

[install]
linker = "hoisted"  # or "isolated" for pnpm-like behavior
optional = true
dev = true
production = false

[test]
root = "."
coverage = false
timeout = 5000

[run]
shell = "system"  # or "bun" on Windows
bun = true        # auto-alias node to bun

[define]
"process.env.DEBUG" = "'true'"

Decision Guidance

When to Use X vs Y

Workflow

1. Initialize a Project

bun init my-app
cd my-app

This creates package.json, tsconfig.json, bunfig.toml, and a starter index.ts.

2. Install Dependencies

bun install
bun add react
bun add -d @types/react

Bun reads package.json, resolves dependencies, and creates bun.lock (text-based lockfile).

3. Write and Run Code

Create index.ts:

const server = Bun.serve({
  port: 3000,
  routes: {
    "/": () => new Response("Hello!"),
  },
});
console.log(`Listening on ${server.url}`);

Run it:

bun run index.ts
# or
bun index.ts

4. Add Scripts to package.json

{
  "scripts": {
    "dev": "bun --watch run index.ts",
    "build": "bun build ./index.ts --outdir ./dist",
    "test": "bun test"
  }
}

Run with:

bun run dev
bun run build
bun run test

5. Write Tests

Create math.test.ts:

import { test, expect } from "bun:test";

test("2 + 2 = 4", () => {
  expect(2 + 2).toBe(4);
});

Run tests:

bun test
bun test --watch
bun test --coverage

6. Bundle for Production

bun build ./index.ts --outdir ./dist --minify

For executables:

bun build ./cli.ts --outfile ./mycli --compile
./mycli

7. Verify Before Shipping

• Run tests: bun test
• Check types: bun run tsc --noEmit (if using TypeScript)
• Build: bun build ./index.ts --outdir ./dist
• Test the build: node ./dist/index.js

Common Gotchas

• Node.js compatibility is not 100% : Check runtime/nodejs-compat for unsupported APIs. Most popular packages work fine.
• Lifecycle scripts are disabled by default : Add packages to trustedDependencies in package.json to allow postinstall scripts.
• Auto-install can mask missing dependencies : Disable with [install] auto = "disable" in bunfig.toml to catch missing packages early.
• Bun flags go afterbun, not after the script: Use bun --watch run dev, not bun run dev --watch.
• Test files must match patterns : Only *.test.ts, *_test.ts, *.spec.ts, *_spec.ts are discovered automatically.
• Lockfile format changed : Bun v1.2+ uses text-based bun.lock instead of binary bun.lockb. Upgrade with bun install --save-text-lockfile.
• Isolated installs can break some packages : If you hit phantom dependency issues, switch to linker = "hoisted" in bunfig.toml.
• Environment variables in bunfig.toml : Use $VAR_NAME syntax; Bun loads .env, .env.local, .env.[NODE_ENV] automatically.
• Bundler is not a type checker : Use tsc --noEmit separately for type checking; bun build only transpiles.
• HTML imports only work withbun build --target=bun or bun --hot: They don't work with bun run directly.

Verification Checklist

Before submitting work with Bun:

• Code runs without errors: bun run index.ts
• All tests pass: bun test
• No TypeScript errors (if applicable): bun run tsc --noEmit
• Dependencies are installed: bun install completes without errors
• Lockfile is committed: bun.lock is in version control
• Build succeeds: bun build ./index.ts --outdir ./dist completes
• No deprecated patterns used (check for Node.js-only APIs)
• bunfig.toml is valid TOML (if present)
• package.json scripts are correct and tested
• Watch mode works for development: bun --watch run dev

Resources

• Comprehensive navigation : https://bun.com/docs/llms.txt — Full page-by-page listing for agent navigation
• Runtime API : https://bun.com/docs/runtime — File I/O, HTTP, networking, workers, environment variables
• Package Manager : https://bun.com/docs/pm/cli/install — Install, add, remove, workspaces, registries
• Bundler : https://bun.com/docs/bundler — Build, splitting, plugins, executables, optimization
• Test Runner : https://bun.com/docs/test — Writing tests, mocks, snapshots, coverage, watch mode

For additional documentation and navigation, see: https://bun.com/docs/llms.txt

Weekly Installs

209

Source

bun.sh/docs

First Seen

Mar 2, 2026

Security Audits

SocketPass

Installed on

opencode207

gemini-cli206

kimi-cli206

codex206

cursor206

amp206