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 的原生模块。.node addon 若直接链接 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,迁移才真正完成。

点赞(0) 打赏

评论列表 共有 0 条评论

暂无评论
立即
投稿

微信公众账号

微信扫一扫加关注

发表
评论
返回
顶部