如何把 Bun.serve() 应用部署到 Vercel 并配置 bunVersion

如何把 Bun.serve() 应用部署到 Vercel 并配置 bunVersion

【免费下载链接】bunIncredibly fast JavaScript runtime, bundler, test runner, and package manager – all in one项目地址: https://gitcode.com/GitHub_Trending/bu/bun

如果你的项目核心是一个Bun.serve()HTTP 服务器（例如通过 routes 和 fetch 处理请求），想把它原样部署到 Vercel 而不是套一层框架，需要完成三件事：在vercel.json中通过bunVersion字段指定 Bun 运行时版本、让 Vercel 的 Bun framework preset 能发现你的服务器入口、然后用 Vercel CLI 完成部署并验证运行时。整个过程的前提是项目使用 Bun 管理依赖（有bun.lock文本锁文件），服务器在模块加载时调用一次Bun.serve()。

在 vercel.json 中配置 bunVersion

要让 Vercel 的 Functions 跑在 Bun 运行时上，需要在项目根目录的vercel.json中添加bunVersion字段：

{ "bunVersion": "1.4.x" }

文档示例中使用的是1.4.x。这里写的是 minor 版本，patch 版本由 Vercel 管理。为了让本地行为和线上一致，建议把本地安装的 Bun 版本调到与 Vercel 使用的版本一致。

注意 TanStack Start 的生态文档中给出的vercel.json写法是"bunVersion": "1.x"，写法风格与上面一致，按项目实际选用的 minor 版本填写即可。

用 Bun.serve() 承载整个应用

Vercel 的 Bun framework preset 会把部署内的所有请求转发到同一个Bun.serve()服务器。preset 生效需要同时满足三个条件：

• 项目设置了bunVersion（上一步的vercel.json）；
• 项目中有bun.lock文件（Bun 1.2 及以上版本运行bun install会自动生成；更早版本需要运行bun install --save-text-lockfile，preset 不识别二进制的bun.lockb格式）；
• 服务器入口位于以下路径之一：
  • server.{js,cjs,mjs,ts,cts,mts}
  • src/server.{js,cjs,mjs,ts,cts,mts}

在入口文件中，模块加载时调用一次Bun.serve()，Vercel 检测到这个调用后就会把进来的请求路由给它。Vercel 支持fetch、routes、error和websocket四个选项，文档给出的示例是：

Bun.serve({ routes: { "/health": () => Response.json({ status: "ok" }), }, fetch() { return new Response("Hello from Bun on Vercel"); }, });

这样一个最小可部署的项目只需要四个文件：package.json、bun.lock、server.ts和vercel.json。不需要api/目录，也不需要任何路由配置。

与本地运行相关的限制：

• port和hostname只在本地运行时生效，它们不配置线上端点；
• routes中的 Unix sockets 和 HTML imports 在 Vercel 上不支持；
• WebSocket 连接按 Vercel 自己的 WebSockets 文档中的 Bun 示例配置；
• node:http和node:https的自动 source maps、字节码缓存、请求指标在 Bun 运行时上不受支持（fetch的请求指标支持）。

可选分支：把 Bun.serve() 挂在 /api 下

如果项目已经有前端、只想给部分路径加一个 Bun 服务器，可以创建api/server.ts并在模块加载时调用一次Bun.serve()：

Bun.serve({ fetch(request) { const url = new URL(request.url); return Response.json({ message: "Hello from Bun on Vercel", pathname: url.pathname, }); }, });

Vercel 会把它部署成位于/api/server的单个 Function，只有请求/api/server才会到达这个服务器（区别于上面的 framework preset，preset 是全站请求都走这一个服务器）。这种写法只依赖vercel.json里的bunVersion，不使用 framework preset，也不要求bun.lock。如果想让其他路径也进入这个服务器，需要在vercel.json中追加路由重写（route overrides），每条重写必须写完整请求路径并包含/api/server前缀。

部署

把仓库连接到 Vercel，或者直接用 Vercel CLI 部署。文档给出两种方式：

# 用 bunx 运行，无需全局安装 bunx vercel login bunx vercel deploy

或者全局安装 Vercel CLI：

bun i -g vercel vercel login vercel deploy

bun i -g vercel会把 Vercel CLI 安装到你的全局依赖中，其余两条命令只是登录和执行部署，副作用限于本地环境。

验证运行时确实是 Bun

部署完成后，在服务器代码里打印process.versions.bun：

console.log("runtime", process.versions.bun);

文档示例的输出是：

runtime 1.4.0

上面的1.4.0是文档示例结果。实际输出取决于 Vercel 按bunVersion解析到的 patch 版本，只要日志中出现你配置的那个 minor 系列（如1.4.x）的版本号，就说明部署跑在 Bun 运行时上。

限制与注意事项

• node:http、node:https的自动 source maps、字节码缓存和请求指标在 Vercel 的 Bun 运行时上不支持，fetch的请求指标支持；
• routes中不能使用 Unix sockets 和 HTML imports；
• Routing Middleware 需要用 Node.js 运行时运行，在 middleware 文件中导出：

export const config = { runtime: "nodejs" };

• 如果项目是 Next.js 等 Vercel 支持的框架而非裸Bun.serve()应用，设置bunVersion后框架即可跑在 Bun 上；Next.js 项目（包括 ISR）还需要把package.json的 scripts 改成用bun --bun调用 Next CLI：

{ "scripts": { "dev": "bun --bun next dev", "build": "bun --bun next build" } }

--bun标志让 Next.js CLI 在 Bun 下运行，打包（Turbopack 或 Webpack）本身不受影响。此分支与本文的Bun.serve()部署路径相互独立，仅在框架项目参考时有用。

完整流程参考 部署到 Vercel 的官方文档，服务器配置细节见 Bun.serve() 文档与 路由文档。

【免费下载链接】bunIncredibly fast JavaScript runtime, bundler, test runner, and package manager – all in one项目地址: https://gitcode.com/GitHub_Trending/bu/bun