SvelteKit 适配器 adapter-bun 实战指南:用 Bun 构建独立服务器

原创2026-09-20 10:39:071,665 阅读
文章标签:Web框架后端前端

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(\^d(/.∗)?{d}(\\/.*)?`)`)加入 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。受支持的属性:

  • hostname
  • port
  • unix
  • reusePort
  • ipv6Only
  • idleTimeout
  • maxRequestBodySize
  • development

环境变量的优先级高于这些默认值。若配置了 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。

登录后查看全文
kit