Bun 1.0 把运行时、包管理、打包与测试合并成一套工具链,但生产落地的难点不在"能不能跑",而在锁文件、原生模块、内存画像与灰度回滚能否被工程化地管住。本文按依赖、运行时、构建、测试与可观测性五条线,给出一套可执行的落地清单与排查路径。
一、先判断:Bun 1.0 适不适合你的生产环境
1.1 生产可用性的四个评估维度
Bun 1.0 的意义在于把 "Node.js compatible" 从 API 子集推进到工程语义层面:bun install 直接读写 package.json,bun run 执行 scripts,bun:test 兼容 Jest 风格用例,bun build 与 bun --compile 覆盖打包与分发。但"能跑"和"能上生产"之间还有四个必须自问的问题。
- 有没有非 N-API 的原生模块。
.nodeaddon 若直接链接 V8 内部符号,Bun 需要在自己的兼容层里重新解析;node-gyp构建产物在版本升级时最容易断。用ldd、nm检查符号,或换成纯 JS/WASM 实现(bcrypt改用纯 JS 版,argon2改用 WASM 版)。 - 部署目标的 libc 与架构。
bun --compile产出的单文件默认动态链接宿主 libc,alpine/musl 与 arm64 需要显式--target。企业内网若锁定基础镜像版本,先验证再承诺。 - Windows/macOS 本地一致性。Bun 的 Windows 支持在 1.0 后明显改善,但路径分隔符、
node:前缀大小写、shell差异仍会让同一份 CI 脚本表现不同。 - 升级节奏。minor 版本会改锁文件格式与内置 API 行为(典型如二进制
bun.lockb到文本bun.lock)。把版本写进 CI 缓存键与镜像标签,避免"升级一次、缓存全失效"。
1.2 适合与不适合的场景
- 适合:I/O 密集、JSON 序列化重的网关/BFF,内部工具与 CLI,Serverless 短生命周期函数,构建链脚本与单元测试。它们能吃到启动快、内置转译器省掉
tsx/esbuild依赖、单文件分发的红利。 - 谨慎:依赖
sharp/puppeteer/@tensorflow的原生栈,需要精确 GC 调参的长连接服务,强依赖 Node 诊断工具链(clinic/0x/特定 APM agent)的核心链路。 - 不建议:把
Bun.*特化 API 写进领域层。保留适配层,让 Bun 只是"当前更快的那一层"。
二、依赖管理:锁文件与 CI 缓存是第一个战场
2.1 bun install 与 lockfile 策略
Bun 1.0 默认生成二进制 bun.lockb,1.2 起切换为文本 bun.lock:可读、可 review、可 diff。生产仓库只应存在一份锁文件;package-lock.json 与 yarn.lock 若因历史原因并存,会让 CI 缓存与依赖版本出现三份真相。
- 固定版本:
bun add -E pkg或直接在package.json写精确版本,避免^范围在锁文件失效时漂移。 - 冻结安装:CI 与镜像构建统一
bun install --frozen-lockfile,本地开发用bun install;锁文件冲突人工 review,不允许--no-save绕过。 - 混用运行时:双轨验证时以
bun.lock为准,Node 侧用npm ci隔离,不要把node_modules挂载进容器当共享缓存。
2.2 私有源、生命周期脚本与可复现构建
- 私有 registry:
.npmrc配置registry与//host/:_authToken,Bun 读取 npm 配置;CI 里 token 只走 secret,不落镜像层。 - 生命周期脚本:
postinstall里的原生构建是供应链与构建时长双风险。用trustedDependencies白名单限制可执行脚本的包,未列名的包其postinstall不自动运行,需要显式bun pm trust。 - 可复现:
--frozen-lockfile加固定oven/bun:<版本>基础镜像,CI 缓存键包含bun.lock哈希与运行时版本。
FROM oven/bun:1.2-debian AS build
WORKDIR /app
COPY package.json bun.lock ./
RUN bun install --frozen-lockfile --production
COPY . .
RUN bun build ./src/index.ts --target=bun --minify --outfile=dist/server.js
FROM oven/bun:1.2-debian AS run
RUN apt-get update \
&& apt-get install -y --no-install-recommends tini \
&& rm -rf /var/lib/apt/lists/*
WORKDIR /app
ENV NODE_ENV=production
COPY --from=build /app/dist /app/dist
COPY --from=build /app/node_modules /app/node_modules
EXPOSE 8080
ENTRYPOINT ["/usr/bin/tini", "--"]
CMD ["bun", "run", "/app/dist/server.js"]
三、运行时与服务:从 bun run 到 Bun.serve
3.1 服务启动、进程模型与信号
Bun 的 HTTP 层基于 uSockets,Bun.serve 直接绑定端口,没有 Node http.createServer 那层包装。生产上要做几件事:显式设置 idleTimeout(默认偏短,长连接/Keep-Alive 场景按客户端超时对齐)、maxRequestBodySize 限流、TLS 证书内嵌或交给 sidecar/反代。--watch/--hot 只用于本地与预发,生产交给进程管理器;容器里 PID 1 的信号转发必须实测,否则滚动更新时连接被硬切。
// src/index.ts —— 仅使用 1.0 起稳定的 API
import { Database } from "bun:sqlite";
const db = new Database("app.db");
db.exec("CREATE TABLE IF NOT EXISTS hit (id INTEGER PRIMARY KEY, at TEXT)");
const insert = db.prepare("INSERT INTO hit (at) VALUES (?)");
const server = Bun.serve({
port: Number(process.env.PORT ?? 8080),
idleTimeout: 125,
maxRequestBodySize: 1 << 20,
tls: {
cert: await Bun.file("tls.crt").text(),
key: await Bun.file("tls.key").text(),
},
fetch(req) {
const url = new URL(req.url);
if (url.pathname === "/healthz") return new Response("ok");
if (url.pathname === "/hits" && req.method === "POST") {
insert.run(new Date().toISOString());
return Response.json({ ok: true });
}
return new Response("not found", { status: 404 });
},
});
process.on("SIGTERM", () => server.stop(true)); // 停止接收,等在途请求排空
console.log(`listening on :${server.port}`);
3.2 内存、GC 与长尾延迟
Bun 用 JavaScriptCore,堆上限与 V8 的 --max-old-space-size 不是同一套参数;NODE_OPTIONS 在 Bun 下部分失效是常见误判来源。生产要固定内存上界:容器 resources.limits.memory 是唯一可靠约束,JSC 的 OOM 表现为进程被杀而不是抛错,因此要配合退出码 137 告警。
--smol:降低 JSC 堆与线程开销,适合短生命周期、低内存函数。- 观测 RSS 与事件循环延迟,不要只看平均吞吐;采样 P95/P99 RSS,对比同负载下 Node 基线。
- 长尾常见来源:大对象
JSON.parse/stringify、同步文件 I/O、未分页的bun:sqlite查询、Buffer拼接。改成流式或分页,收益通常大于换运行时。
四、构建与分发:bun build 与单文件可执行
4.1 目标与产物形态
--target=bun 产出自包含 JS,--compile 产出内嵌运行时的单文件。三件事决定分发成败:libc(debian/glibc 与 alpine/musl)、架构(x64 与 arm64)、交叉编译目标(--target=bun-linux-x64、bun-linux-arm64)。CI 里显式声明目标,避免"macOS 上编译、丢给 alpine 容器跑"的翻车。
- 外部依赖:数据库驱动、原生模块用
--external保留为import,配合已验证的node_modules,否则运行期找不到模块。 - 体积:
--compile内嵌整个 Bun(几十 MB 起),对镜像仓库与分发敏感的项目,用--target=bun加多阶段镜像通常更划算。 - 环境变量:编译期内联的只有被 Bun 识别的少量变量,业务配置必须运行期读取,不要指望编译期注入。
4.2 宏与运行时代码的耦合风险
Bun 宏在构建期执行任意代码,等于把"构建脚本"提升为运行时依赖。生产建议:宏只用于常量内联与死代码消除,不读网络、不依赖环境,并在 lint/审计里显式列出;一旦宏里出现 I/O,构建的可复现性与安全边界就破了。
五、测试、监控与灰度:把风险关进笼子
5.1 bun test 与 CI 提效
bun test 兼容 Jest 的 describe/it/expect 与 snapshot,省掉 tsx 与 vitest 的依赖与启动开销。落地要点:
- 迁移策略:先
bun test跑现有用例并保留--coverage阈值;不兼容的 matcher(如部分jest.mock语义)用mock.module或适配层替换。 - 隔离:默认并发与共享进程状态可能让单测互相污染,DB 用例用临时库或事务回滚。
- 收益再投资:
bun test通常比 Node 加 vitest 快数倍,但把收益投到"增加用例数与覆盖率",而不是单纯缩短反馈环。
curl -fsSL https://bun.sh/install | bash -s "bun-v1.2" # 与镜像一致的版本
export BUN_INSTALL="$HOME/.bun" PATH="$BUN_INSTALL/bin:$PATH"
bun install --frozen-lockfile
bun test --coverage
bun build ./src/index.ts --target=bun --minify --outfile=dist/server.js
bun build ./src/index.ts --compile --outfile=app # 单文件分发
5.2 可观测性与灰度回滚
- 指标:QPS、P99、错误率、RSS、事件循环延迟、GC 次数(如可获取)。Bun 没有 Node 的
--prof与diagnostics_channel全套,链路追踪优先用 OpenTelemetry JS SDK,而不是私有 profiler 协议。 - 日志:结构化 JSON,热路径避免同步写 stdout,容器里交给采集器。
- 灰度:按实例权重 1% 到 10% 到 50% 再到 100%,每档至少观察一个业务高峰;回滚预案是"换回 Node 镜像 tag",而不是"改代码重发"。双轨期间两种运行时共用同一套指标口径。
- 退出码:OOM(137)、未捕获异常(1)、
server.stop超时分别告警,滚动更新失败要能自动回退上一版本。
结语
Bun 1.0 的落地结论可以收敛成一句:先把依赖、构建、信号、内存四件事工程化,再谈收益。运行时不是信仰,而是可以在流水线上被量化、被替换的组件;当你能用同一套指标、同一套回滚路径同时驱动 Bun 与 Node,迁移才真正完成。

发表评论 取消回复