生产环境与部署指南

Bun 生产环境与部署指南

一、生产构建

Bun 内置了高性能的打包器（bundler），可以对前端或全栈应用进行生产优化。

bash

# 构建前端应用（如 React/Vue 的入口 HTML）
bun build --production ./index.html --outdir ./dist

# 构建后端服务（将 TypeScript 编译为 JavaScript）
bun build --production ./src/index.ts --outdir ./build --target node

常用构建选项：

--production：启用生产优化（压缩、Tree Shaking、环境变量替换）
--outdir：指定输出目录
--target：可选 browser、node 或 bun（默认）
--minify：显式开启压缩（--production 会自动开启）
--sourcemap：生成 source map（便于错误追踪）

构建产物可直接部署到任何静态托管服务（如 S3、CloudFlare Pages）或生产服务器。

二、使用 Docker 部署

将 Bun 应用容器化，保证环境一致性，适合云平台或自建服务器。

dockerfile

# Dockerfile
FROM oven/bun:latest AS builder
WORKDIR /app
COPY package.json bun.lock ./
# 若仓库仍提交旧的二进制锁文件，可改为复制 bun.lockb
RUN bun install --frozen-lockfile --production

FROM oven/bun:latest
WORKDIR /app
COPY --from=builder /app/node_modules ./node_modules
COPY . .
EXPOSE 3000
CMD ["bun", "run", "index.ts"]

构建并运行镜像：

bash

docker build -t my-bun-app .
docker run -p 3000:3000 my-bun-app

小技巧：使用多阶段构建可以减小最终镜像体积（上面的示例已包含）。基础镜像 oven/bun:latest 约 50MB，生产环境下非常轻量。

三、部署到云平台

许多主流云平台已原生支持 Bun，无需复杂配置即可部署。

1. DigitalOcean App Platform

连接 GitHub 仓库，平台检测到 bun.lock（或旧格式 bun.lockb）后，通常会按 Bun 项目构建并运行。
可在 Procfile 或环境变量中指定启动命令（如 web: bun run index.ts）。

2. Railway

一键部署：railway up（需安装 Railway CLI）
支持直接导入 GitHub 仓库，若检测到 Bun 项目会自动配置。
有时需要显式添加 Dockerfile（如上节所示）以确保构建通过。

3. Vercel / Netlify（前端静态资源）

使用 bun build --production 生成静态文件后，将 dist 目录部署到这些平台即可。

4. 自建服务器（如 AWS EC2、Linode）

安装 Bun（通过官方脚本），用 bun run 启动服务。
建议配合 PM2（bun 可运行 PM2 进程管理器）或 systemd 守护进程。

四、常见问题与注意事项

问题	说明与解决方案
Node.js 兼容性	Bun 对 Node.js API 覆盖面很高，但具体比例随版本变化；C++ 原生插件（部分旧版 `bcrypt`、`sharp`、`node-gyp` 相关包）仍可能不兼容。请以当前 Node.js 兼容性与实测为准。
锁文件	Bun 1.2+ 默认文本锁文件 `bun.lock`（可直接看 diff）；旧项目可能仍是二进制 `bun.lockb`。两种格式均应提交到 Git；查看依赖可用 `bun pm ls`。
CPU 指令集要求	标准 x64 构建通常要求 AVX2（约 Haswell / Excavator 及更新）；无 AVX2 时可选用官方 x64-baseline 构建（更慢）。以安装文档为准。
macOS 版本要求	官方要求 macOS 13.0 (Ventura) 或更高。
CI 中锁定依赖	使用 `bun install --frozen-lockfile`：锁文件与 `package.json` 不一致时会失败，避免 CI 静默升级依赖。
测试新特性	使用 `bun upgrade --canary` 升级到每日构建版；通过 `bun upgrade`（或文档推荐的稳定通道命令）切回稳定版。
环境变量	生产环境推荐通过 `.env` 或平台环境变量注入，启动时可用 `bun --env-file .env run index.ts` 加载。

五、性能与监控建议

启用日志压缩：使用 bun run 时可通过管道将日志输出到 bun --silent 减少输出开销。
健康检查：为 HTTP 服务添加 /health 端点，供容器编排或负载均衡器使用。
多核利用：Bun 默认利用多线程处理 I/O，无需额外配置。如需更精细的集群模式，可启动多个进程（如使用 bun run 配合负载均衡）。

总结：部署 Checklist

构建优化：bun build --production 生成产物。
依赖锁定：提交 bun.lock（或仍在使用的 bun.lockb）到版本库。
容器化（可选）：使用 oven/bun 基础镜像编写 Dockerfile。
云平台选择：DigitalOcean / Railway / Vercel 等都支持 Bun。
环境变量：通过 .env 或平台注入。
CI 命令：bun install --frozen-lockfile && bun run test。
兼容性排查：检查 C++ 插件、CPU 指令集、macOS 版本。

Bun 目前已在生产环境中被许多公司使用，随着版本的迭代，稳定性和兼容性不断提升。对于新项目，Bun 是一个非常值得尝试的高性能 JavaScript 运行时。