bun

Bun

当工作涉及 Bun 运行时、包管理器、测试运行器、打包器、bunfig.toml、Node 兼容性，或迁移到 Bun 的安装/脚本时，请使用此技能。

快照：[email protected]、@types/[email protected] / [email protected]（采集于 2026-09-18，已于 2026-10-01 重新验证——仍为最新稳定版）。若版本不同，请从 source-map.md 刷新。

工作流

1. 检查本地 Bun 环境：
   • bun --version / bun --revision（稳定版系列为 1.4.x；API 相关任务优先使用 bun upgrade 升级到 1.4.2）。
   • 锁文件：bun.lock（文本格式；lockfileVersion 为 2，或带嵌套/版本范围覆盖项的 3）与旧版 bun.lockb。
   • package.json 脚本、工作区、目录、覆盖项、trustedDependencies、可选的 nativeDependencies / ignoreScripts / selfContained。
   • bunfig.toml（项目级及可选的全局配置）、.npmrc、@types/bun，以及 TypeScript 6/7 的 "types": ["bun"]。
   • 代码使用的是 Bun 原生 API（Bun.serve、Bun.Image、bun:sqlite……）还是 Node API（node:*）。
2. 日常操作指南、渐进式采用和故障排查，请先参阅 usage-guide.md。
3. 当版本有变化，或任务涉及 Redis/SQL/HTTP2/HTTP3/FFI、锁文件/链接器/globalStore，或从 1.3 升级到 1.4 时，请更新文档。从 source-map.md 开始。
4. 深入了解相关细节：
   • 运行时 API、HTTP、文件、shell、Image/WebView/markdown/cron、SQLite/Redis/S3/SQL：runtime-apis.md。
   • 安装、锁文件、工作区、信任、bunx、CI、audit/dedupe/prune：package-manager.md。
   • bun test、bun build、--compile、init/create：test-bundler-build.md。
   • Node 26 兼容性、全局变量、watch/hot、bunfig、1.3→1.4 破坏性变更：node-compat-config.md。
5. 新建 Bun 项目时，优先使用 Bun 原生 API 和 bun / bunx 命令。如果代码库已采用 Node 风格且运行正常，则保留 Node API。
6. 使用范围最小且有用的 bun 命令验证（bun test、bun run、bun ci，或针对性的 Bun.serve 冒烟测试）。

核心判断

• Bun 将 运行时 + 包管理器 + 测试运行器 + 打包器 集成在一个二进制文件中——它不只是“速度更快的 Node”。1.4 是用 Rust 重写的版本，标准库也更丰富（Image、WebView、markdown、cron、Terminal、XML/JSON5/JSONL）。
• 在 Bun 项目的命令中，优先使用 bun / bunx，而非 npm / npx / yarn / pnpm。
• 提交 bun.lock。CI 安装命令：bun ci（使用冻结锁文件）。
• 依赖的生命周期脚本默认会被阻止，除非已获信任——添加原生包（如 sharp）后，请检查 bun pm untrusted。
• 新工作区的锁文件默认使用 isolated 链接器（configVersion: 1）；旧版锁文件仍使用 hoisted。全局虚拟存储为可选项（[install] globalStore = true），且仅适用于 isolated。
• 新建 HTTP 服务时优先使用 Bun.serve；注意默认的空闲超时时间为 10s（SSE 需要 server.timeout(req, 0)）。HTTP/2（http2: true）和 HTTP/3（http3: true）仍为实验性功能。
• 使用 Bun 优先的代码时，优先选择 bun:sqlite / Bun.SQL / Bun.redis / Bun.Image，而非较重的 Node 客户端。
• bun --watch 会硬重启；bun --hot 会软重载（globalThis 会保留）——适合服务器。
• Bun 标志必须放在 run 之前：使用 bun --watch run dev，而非 bun run dev --watch。
• Bun.env 是启动时的快照；值会在运行时变化时，优先使用 process.env。
• bun build 不会进行类型检查，也不会生成 .d.ts——类型重要时请运行 tsc。
• 在 1.4 中，bun:ffi 已成为引擎原生功能（cstring 是普通字符串）。对生产关键型 FFI，优先使用 Node-API 原生模块。
• 从 1.3 升级到 1.4：Bun 报告的版本为 Node.js 26（process.versions.modules 为 147）；bunfig.toml 中的字符串必须加引号。完整列表：node-compat-config.md。

验证

优先使用仓库自带的命令。对于有意义的 Bun 工作，覆盖相关子集：

• 运行 bun --version，并确认锁文件 / 链接器 / globalStore 的预期。
• 运行针对性 bun test（路径或 -t 模式）；如果 CI 需要，则使用 --parallel / 覆盖率 / junit。
• 修改锁文件后运行 bun ci 或 bun install --frozen-lockfile。
• 使用 bun run <entry> 进行冒烟测试，或通过 port: 0 + fetch 测试 Bun.serve。
• 添加原生依赖后：按需运行 bun pm untrusted / 信任依赖。
• 运行 bun build / --compile 后：在目标平台运行生成的输出。
• Node 兼容性迁移：在 Bun 下运行同一套测试，并注明尚未完全支持的模块。
• 从 1.3 升级到 1.4 后：为 NODE_MODULE_VERSION 147 重新构建原生扩展；使用带引号的 bunfig.toml；不得使用 res.writeHeader()。

报告运行了哪些检查、未运行哪些检查，以及仍有哪些 Bun 版本假设。