SuperAPI AI 工具集

bun-runtime

编程与开发

查看项目

更新于 11-10 16:20

技能介绍

Bun 是一个快速的一体化 JavaScript 运行时与工具包,同时提供运行时、包管理器、打包器和测试运行器。

用途与选择

资料建议在以下情况优先使用 Bun:新的 JS/TS 项目;安装或运行速度重要的脚本;使用 Bun 运行时的 Vercel 部署;希望使用单一工具链(运行 + 安装 + 测试 + 构建)。

在以下情况优先使用 Node:需要最大生态兼容性;依赖假设 Node 的旧工具链;某个依赖存在已知 Bun 问题。

适用场景包括:采用 Bun、从 Node 迁移、编写或调试 Bun 脚本/测试,或在 Vercel 及其他平台配置 Bun。

工作原理

版本基线:资料中的指引针对 Bun 1.4.x。在依赖具体命令行标志名称前,应先用 bun --version 检查实际版本,因为 CLI 标志可能随版本变化。

运行时:与 Node 兼容的即插即用运行时,基于 JavaScriptCore 构建。截至 Bun 1.4,运行时本身已用 Rust 实现(从 Zig 迁移)。它并非 100% 兼容 Node——某些原生插件、较少见的 node: 内部 API,以及依赖 Node 特定内部实现的包仍可能失败;在生产环境依赖它之前需要验证。

包管理器:Bun 内置包管理器;安装性能取决于项目、网络状况和缓存状态。当前 Bun 默认锁文件为 bun.lock(文本);旧版本使用 bun.lockb(二进制)——Bun 仍可读取该格式以便迁移,但新项目应使用 bun.lock。

打包器:内置用于应用和库的打包器与转译器。

测试运行器:内置 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 的地方优先使用 Bun API 以获得更好性能。

包与工作区命令

bun add <pkg> / bun remove <pkg> / bun update [pkg] 用于管理依赖;bun outdated 列出过时依赖。bun pm ls 使用锁文件列出项目依赖及解析版本;--all 包含传递依赖。它不是对已安装文件内容的完整性检查。bun audit 使用 bun.lock 中的包名和版本查询注册表公告;它不会修改 package.json、bun.lock 或 node_modules。发送私有包元数据前应审查获批的目标地址。作用域注册表缺少公告端点的包会被跳过,且不影响退出码。bun audit fix 会升级并安装依赖,改变锁文件和已安装包,有时会改变直接版本固定;应将其视为会修改内容的安装操作,包括适用的生命周期脚本。bun dedupe 合并重复安装,bun prune 移除不再被引用的包。Monorepo 在 package.json 中使用根 workspaces 数组(与 npm/yarn 相同约定);用 bun run --filter <pkg-name> <script> 在单个工作区运行脚本。

内置 API

在添加依赖前可先考虑这些内置能力——Bun.file / Bun.write 用于文件 I/O,bun:sqlite 用于嵌入式 SQLite 数据库,Bun.serve 用于 HTTP/WebSocket 服务器,Bun.sql 用于 SQL 数据库,Bun.redis 用于 Redis,Bun.S3Client 用于兼容 S3 的对象存储。其余新增内容见 1.4 发布说明。

Vercel

在 vercel.json 中设置 bunVersion: "1.4.x" 以使用 Bun 1.4(Rust 运行时)。参见 Vercel 的 Bun 运行时文档。构建:bun run build 或 bun build ./src/index.ts --outdir=dist。安装:bun install --frozen-lockfile 用于可复现部署。

参考:Bun 1.4 发布说明。

示例

运行与安装

安装依赖(创建/更新 bun.lock)

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

在 Bun 1.4 的 CI 中,可用选项包括 bun test --changed[=<ref>] 用于受影响测试,bun test --isolate 用于按文件隔离全局变量,bun test --parallel[=<n>] 用于工作进程,以及 bun test --shard=<n>/<count> 用于 CI 分区。--isolate 在同一进程中为每个文件创建全新的 JavaScript 全局环境,并清理文档中列出的按文件资源;它不是进程或安全沙箱。--parallel 默认启用它。--timings=<file> 读取先前耗时用于调度;--update-timings 记录耗时。示例:bun test --parallel --timings=./test-timings.json --update-timings。在多分片工作流中选择计时文件路径前,应查看已安装版本的帮助和文档。

// 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 run。对于 TypeScript,Bun 原生运行 .ts。

保持依赖更新;Bun 和生态发展很快。

限制

资料明确说明 Bun 并非 100% 兼容 Node,某些原生插件、较少见的 node: 内部 API 以及依赖 Node 特定内部实现的包可能失败,生产使用前需验证。安装性能取决于项目、网络状况和缓存状态。CLI 标志可能随版本变化,使用前应检查实际版本。bun pm ls 不是对已安装文件内容的完整性检查。bun audit 不会修改 package.json、bun.lock 或 node_modules,而 bun audit fix 会修改锁文件和已安装包。--isolate 不是进程或安全沙箱。关于收费、价格、平台支持范围等更多信息,资料暂未提供。