SvelteKit 适配器 adapter-bun 实战指南:用 Bun 构建独立服务器
SvelteKit 适配器 adapter-bun 实战指南:用 Bun 构建独立服务器
导读
@sveltejs/adapter-bun 是 SvelteKit 官方适配器之一,它将 SvelteKit 应用构建为一个完全独立的 Bun 服务器:生成的服务端程序使用 Bun.serve 处理请求、以 Bun.file 提供客户端资源、预渲染输出以及通过 $app/server 中 read 读取的文件。阅读完本文,你将掌握如何安装配置该适配器、在 Bun 中完成生产构建与运行、定制 out/precompress/envPrefix/serverOptions/buildOptions 等全部选项、利用完整的环境变量清单在反向代理后部署、访问 Bun 专属的 platform API,并实现优雅停机。本文以仓库中的官方文档 documentation/docs/25-build-and-deploy/45-adapter-bun.md 为主体,并结合 packages/adapter-bun 包的源码与测试逐项佐证。
[!NOTE] 使用该适配器要求 Bun 1.4 或更新版本。package.json 的 engines 字段 声明了
"bun": ">=1.4.0";同时运行时入口 packages/adapter-bun/src/index.js 在启动时会通过Bun.semver.order(Bun.version, '1.4.0')主动校验版本,低于 1.4 直接抛错。
快速上手:安装、配置、构建与运行
安装适配器
在 SvelteKit 项目根目录执行:
bun add -D @sveltejs/adapter-bun
适配器位于仓库的 packages/adapter-bun 目录,其 peerDependencies 要求 @sveltejs/kit 3.x(见 package.json),对 Bun 运行时版本有硬性下限(1.4.0)。
在 vite.config.js 中启用
// @errors: 2307 2554
/// file: vite.config.js
import adapter from '@sveltejs/adapter-bun';
import { sveltekit } from '@sveltejs/kit/vite';
import { defineConfig } from 'vite';
export default defineConfig({
plugins: [
sveltekit({
adapter: adapter()
})
]
});
用 Bun 执行生产构建
适配器内部会调用 Bun 的构建 API(Bun.build),因此生产构建本身必须在 Bun 中运行。Vite 的可执行文件带有 Node.js shebang,需要通过 --bun 标志覆盖:
bun run --bun build
从构建入口 packages/adapter-bun/index.js 可以看到,adapt() 首先检查 typeof Bun === 'undefined',若非 Bun 环境会直接抛出 adapter-bun requires running the SvelteKit build with Bun. Use \bun run --bun build`.` 的明确提示,从源头杜绝用错运行时。
启动服务器
默认构建产物输出到 build 目录,启动方式:
bun ./build
build/index.js 内容仅一行 import './server/adapter-index.js';(见 packages/adapter-bun/index.js),真正的服务器入口被 Vite/Rolldown 打进 server/ 下。
部署时需要随产物一起发布的文件
要运行构建产物,除了输出目录本身,还需要:
- 项目的
package.json; - 生产依赖所在的
node_modules。
生产依赖可以这样生成:拷贝 package.json 与 bun.lock 后执行
bun install --production --frozen-lockfile
(如果你的应用没有任何依赖,可以跳过此步。)
开发依赖(devDependencies)会被直接打包进应用,而 dependencies 中的包默认保持外部化。因此在 package.json 中把某个包放在 devDependencies 还是 dependencies,就决定了它是被捆绑进产物还是运行时从 node_modules 解析。这一行为与构建配置中 external 的处理一一对应:构建入口会把 pkg.dependencies 的顶层包名映射为正则(new RegExp(\^`)`)加入 Rolldown 的 external 列表,见 packages/adapter-bun/index.js。
静态资源与预渲染输出的原生服务方式
生成的服务器并非把所有请求都交给 SvelteKit,而是将客户端资源与预渲染输出注册为 Bun 原生路由(Bun.serve 的 routes 选项)。只有 GET 与 HEAD 请求由这些静态路由处理,其他 HTTP 方法会继续转发给 SvelteKit 完整处理流程。这正是 packages/adapter-bun/src/routes.js 与 packages/adapter-bun/src/routes-util.js 所构建的路由表:构建期生成"路由数据",运行期转换成 Bun 路由(file_route 返回 { GET: handler })。
静态服务具备以下特性(均有源码佐证):
- 构建期 ETag:每个资源在构建时被计算哈希(
blake2b256,取前 16 位 hex,见 packages/adapter-bun/index.js),运行时作为ETag响应头下发。由于 Bun 只为内存态静态路由生成 ETag、不为文件背书(file-backed)的响应生成,适配器自己实现了校验逻辑(is_fresh),从而支持条件请求,命中时返回空 body 的304响应(见 routes-util.js 与file_route)。 - Bun 提供的原生能力:MIME 类型、文件系统支撑文件的字节范围(Range)请求、以及不把每个资源整体读入内存的流式响应(
Bun.file(body_file)直接作为 body)。 - immutable 长缓存:位于 SvelteKit
immutable目录(默认_app/immutable/,见 routes-util.js)之下的文件会收到Cache-Control: public,max-age=31536000,immutable响应头。 - 路径别名:
index.html同时注册到其目录 URL(/docs/index.html也能以/docs/与/docs访问),其他*.html注册为去掉扩展名的路径,行为对齐 sirv;路由路径按 WHATWG 序列化规则处理百分号编码,并额外注册一个全量编码的别名(见 routes-util.js 与 test/routes.spec.ts 中的a&b.txt、photo[1]^a|b.png等用例)。
[!NOTE] Bun 将路由 pathname 中的
*视为通配符。因此适配器会在构建时拒绝包含字面*的客户端/预渲染文件名(构建入口的validate_file_paths会抛错,见 packages/adapter-bun/index.js)。同时,以:开头的路径段也会被 Bun 当作参数处理而被拒绝。请先重命名这些文件再构建。
适配器选项(Options)
除默认调用 adapter() 外,可传入如下完整配置:
// @errors: 2307 2554
/// file: vite.config.js
import adapter from '@sveltejs/adapter-bun';
import { sveltekit } from '@sveltejs/kit/vite';
import { defineConfig } from 'vite';
export default defineConfig({
plugins: [
sveltekit({
adapter: adapter({
out: 'build',
envPrefix: '',
serverOptions: {
idleTimeout: 30
}
})
})
]
});
选项的默认值可在 packages/adapter-bun/index.js 的 opts 解构中直接确认:out = 'build'、envPrefix = ''、precompress = false、serverOptions = {}、buildOptions = {}。
out
构建输出目录,默认 build。构建开始时适配器会先 fs.rmSync(out, { recursive: true, force: true }) 清空旧产物。
precompress
设置 precompress: true 会在构建期为客户端与预渲染资源生成 .br(brotli)与 .gz(gzip)压缩变体。运行时每个请求根据 Accept-Encoding 协商压缩格式,优先 brotli 再 gzip;每个压缩变体携带各自独立的 ETag("${hash}-${encoding}"),并为资源加上 vary: accept-encoding 响应头(见 routes-util.js)。
注意:当设置了 buildOptions.compile(编译为可执行文件)时该选项会被忽略,因为嵌入型资源按身份路径(identity path)导入,构建期会打印 precompress is ignored with buildOptions.compile 警告(见 packages/adapter-bun/index.js)。
envPrefix
为下文中所有部署环境变量统一加前缀,适用于未加前缀的名字与宿主机管理变量冲突的场景:
// @errors: 2307
import adapter from '@sveltejs/adapter-bun';
// ---cut---
adapter({ envPrefix: 'MY_APP_' });
MY_APP_HOST=127.0.0.1 MY_APP_PORT=4000 bun ./build
设置前缀后,服务器启动时若发现带有该前缀但未列入白名单的环境变量,会直接启动失败,用于提前捕获拼写错误与命名冲突。白名单集合定义在 packages/adapter-bun/src/env.js,共 14 个名字:SOCKET_PATH、HOST、PORT、REUSE_PORT、IPV6_ONLY、CONNECTION_IDLE_TIMEOUT、BODY_SIZE_LIMIT、SHUTDOWN_TIMEOUT、DEVELOPMENT、XFF_DEPTH、ADDRESS_HEADER、PROTOCOL_HEADER、HOST_HEADER、PORT_HEADER。
serverOptions
以 JSON 可序列化的形式,作为默认值传给 Bun.serve。受支持的属性:
hostnameportunixreusePortipv6OnlyidleTimeoutmaxRequestBodySizedevelopment
环境变量的优先级高于这些默认值。若配置了 Unix socket(unix),则 hostname、port、reusePort、ipv6Only 都会被忽略。
生成的服务器接管了 fetch 与 routes 两个字段,因此 serverOptions 不会暴露 websocket、error、TLS、HTTP/3 或 HTTP/1 等 Bun.serve 配置。若你的应用需要这些能力,请使用自定义 Bun 集成方案。
buildOptions
buildOptions 配置把服务器打包成可执行文件的那次 Bun.build 调用,因此仅在设置 compile 时生效。适配器接受这些字段:sourcemap、minify、bytecode、banner、footer、drop、features、optimizeImports、external、compile。其中 entrypoint、输出目录、顶层 target 与模块 format 是保留项(由适配器强制设为 target: 'bun'、format: 'esm'、conditions: ['bun', 'node'],见 packages/adapter-bun/index.js)。source map 默认 external,可用 sourcemap: 'none' 关闭。
编译为单文件可执行程序
设置 compile: true 会在 <out>/server 生成单个可执行文件:
// @errors: 2307
import adapter from '@sveltejs/adapter-bun';
// ---cut---
adapter({
buildOptions: {
compile: true
}
});
构建与运行(无需单独安装 Bun 运行时):
bun run --bun build
./build/server
可执行文件会嵌入服务器代码、客户端资源、预渲染输出以及 Bun 运行时本身。compile 还可以是:
- 一个 Bun 目标字符串(target),此时保持默认的
server文件名; - 或一个选项对象,用于自定义可执行文件名或交叉编译:
// @errors: 2307
import adapter from '@sveltejs/adapter-bun';
// ---cut---
adapter({
out: 'dist',
buildOptions: {
compile: {
outfile: 'application',
target: 'bun-linux-x64'
},
minify: true,
bytecode: true,
sourcemap: 'linked'
}
});
上例的产物是 dist/application。平台目标、原生依赖及其他限制遵循 Bun 官方的可执行文件编译规则。compile 为字符串时,适配器会把它作为 target 并入编译参数(见 packages/adapter-bun/index.js)。
由于可执行文件内部没有 node_modules 可供解析,生产依赖也会被捆绑进可执行文件。若希望某个包在运行时从 node_modules 解析,需要把它列入 external 并设置 compile: { autoloadPackageJson: true }。依赖自身位置读取文件的包(例如 jsdom)只有这样才能正常工作。
环境变量清单
Bun 会自动加载 .env 文件。若设置了 envPrefix,请为下面每个变量名加上前缀。全部变量的解析逻辑集中在 packages/adapter-bun/src/env.js:布尔值、数字、字节数分别有严格的校验。
监听器(Listener)
HOST 与 PORT 配置 TCP 监听地址。两者都未设置且 serverOptions 无默认值时,服务器监听 3000 端口(运行时入口显式回退到 options.port = ... ?? 3000,见 packages/adapter-bun/src/index.js)。
HOST=127.0.0.1 PORT=4000 bun ./build
SOCKET_PATH 改为监听 Unix domain socket;设置后所有仅适用于 TCP 的选项都会被忽略:
SOCKET_PATH=/tmp/sveltekit.sock bun ./build
REUSE_PORT 启用 Bun 的 reusePort 选项,IPV6_ONLY 启用 ipv6Only。布尔变量接受 1、true、yes、on,或 0、false、no、off,不区分大小写(见 env.js 的 BOOLEANS 映射)。
请求限制与诊断
BODY_SIZE_LIMIT 控制 Bun.serve 的 maxRequestBodySize,默认 512K(512 * 1024 字节,见 src/index.js)。值必须解析为整数个字节,可带不区分大小写的二进制后缀 K、M、G,例如 768K 或 1.5M;Infinity 表示禁用限制。解析实现在 env.js。
CONNECTION_IDLE_TIMEOUT 设置 Bun 的每请求非活跃超时(秒),必须是 0 到 255 的整数,0 表示禁用。生成的处理程序会对 content-type 以 text/event-stream 开头的响应禁用该超时,并额外添加 X-Accel-Buffering: no 响应头(见 packages/adapter-bun/src/handler.js)。注意它刻意不叫 IDLE_TIMEOUT——这个名字在 adapter-node 中含义不同(无请求 N 秒后关闭服务器),沿用会造成误解或冲突(源码注释对此有明确说明,见 src/index.js)。
DEVELOPMENT 启用 Bun 的开发模式错误页面,对生成的服务器默认 false。
反向代理后的公共源(Public origin)
如果配置了 paths.origin,该值就是每个请求的受信源(trusted origin)。否则适配器从 Host 头推导主机名,并默认假设协议为 https,因为生产部署通常在更上游的位置终止 TLS。若该假设不成立(例如直接以明文 HTTP 提供服务),请配置 paths.origin 或 PROTOCOL_HEADER。
在受信的反向代理之后,PROTOCOL_HEADER、HOST_HEADER、PORT_HEADER 分别指定包含公网协议、主机名与端口的请求头:
PROTOCOL_HEADER=x-forwarded-proto \
HOST_HEADER=x-forwarded-host \
PORT_HEADER=x-forwarded-port \
bun ./build
校验规则(实现于 packages/adapter-bun/src/handler.js):
- 协议头必须包含不带冒号的
http或https; - 端口头必须包含数字;
- 非法值返回
400 Bad Request; - 头存在但为空时忽略,回退到默认推导。
[!CAUTION] 只有当请求能通过你控制的代理到达服务器时,才应信任这些转发头。直接连接的客户端可以伪造这些头。
代理后的客户端地址
event.getClientAddress() 默认使用 server.requestIP(request).address。当直接对端是代理时,用 ADDRESS_HEADER 指定一个受信代理头:
ADDRESS_HEADER=true-client-ip bun ./build
对于 x-forwarded-for,还需设置 XFF_DEPTH 为受信代理数量。默认深度为 1,适配器从逗号分隔列表的右侧选取,这样客户端在左侧伪造的条目无法改变受信结果:
ADDRESS_HEADER=x-forwarded-for XFF_DEPTH=2 bun ./build
XFF_DEPTH 必须是不小于 1 的整数(解析时 { min: 1 } 限制见 env.js 与 handler.js)。若配置的地址头缺失,或地址数量少于配置的深度,getClientAddress() 会抛错。
Platform API:访问 Bun 服务器实例
请求事件的 platform 属性暴露了底层的 Bun 服务器实例,可读取服务器 ID、挂起请求数、挂起 WebSocket 数等信息:
/** @type {import('./$types').RequestHandler} */
export function GET({ getClientAddress, platform }) {
return Response.json({
address: getClientAddress(),
serverId: platform.server.id,
pendingRequests: platform.server.pendingRequests,
pendingWebSockets: platform.server.pendingWebSockets
});
}
该能力的注入点在 packages/adapter-bun/src/handler.js:调用 server.respond 时传入 platform: { server: bun_server } 与自定义的 getClientAddress,因此 platform.server 的类型即 Bun 的 Server。
优雅停机(Graceful shutdown)
收到 SIGINT 或 SIGTERM 时,生成的服务器调用 server.stop():Bun 停止接受新连接,适配器等待挂起请求完成,然后以信号名作为参数发出 sveltekit:shutdown 进程事件:
process.on('sveltekit:shutdown', async (reason) => {
await jobs.stop();
await db.close();
});
完整实现见 packages/adapter-bun/src/index.js:
- 停机会与
SHUTDOWN_TIMEOUT秒的截止时间赛跑(Promise.race),超时后调用server.stop(true)强制关闭仍然打开的连接,因此诸如持续打开的 event stream 之类的空闲连接不会无限期拖延停机; SHUTDOWN_TIMEOUT必须是非负整数,默认30秒;- 停机期间再次收到信号会强制以退出码
1立即退出(if (shutting_down) return process.exit(1);); - 停机时若仍有挂起请求,控制台会打印等待提示与
Press Ctrl+C again to force shutdown.。
小结
adapter-bun 充分利用了 Bun 运行时与 Bun.serve 的原生能力(原生静态路由、文件流式响应、Range/ETag/压缩协商、可执行文件编译),把 SvelteKit 应用变成单一进程即可运行的独立服务器。围绕它你需要掌握三件事:用 bun run --bun build 构建、用 bun ./build 运行;按需通过 out/precompress/envPrefix/serverOptions/buildOptions 定制行为;在代理部署场景下正确配置 PROTOCOL_HEADER/HOST_HEADER/PORT_HEADER/ADDRESS_HEADER/XFF_DEPTH 等环境变量。相关源码与测试可继续在仓库中研读:构建入口 packages/adapter-bun/index.js、运行时入口 packages/adapter-bun/src/index.js、请求处理 packages/adapter-bun/src/handler.js、路由表 packages/adapter-bun/src/routes.js、路由与压缩实现 packages/adapter-bun/src/routes-util.js、环境变量解析 packages/adapter-bun/src/env.js,以及路由行为测试 packages/adapter-bun/test/routes.spec.ts。