SvelteKit adapter-node 实战指南:构建、部署与运维独立 Node 服务器
SvelteKit adapter-node 实战指南:构建、部署与运维独立 Node 服务器
@sveltejs/adapter-node 是 SvelteKit 官方适配器之一,用于将应用构建为一个可独立运行的 Node.js 服务器,输出产物可直接部署到任意支持 Node 的裸机、云主机或容器平台(如 Docker、systemd 服务)。本文以本仓库 documentation/docs/25-build-and-deploy/40-adapter-node.md 为核心骨架,结合 adapter-node 包源码 深入讲解从安装配置、构建部署到反向代理、优雅停机、socket 激活、自定义服务器的完整实战链路,读完后你将能独立完成一个生产级 Node 服务器的配置与排障。
何时使用 adapter-node
SvelteKit 提供了多种适配器以对接不同部署平台(Cloudflare Workers、Vercel、Netlify、静态托管等),而 adapter-node 针对的是"通用 Node.js 服务器"这一场景:它不绑定任何特定云厂商,生成一个包含完整 HTTP 服务器的构建产物,由你自己负责进程管理、端口监听、反向代理与系统集成。它非常适合:
- 部署到自己的 VPS / 物理机,使用 systemd、Docker 或 PM2 管理进程;
- 需要自由编写自定义服务器中间件(如健康检查、鉴权)的场景;
- 需要精细控制优雅停机、Keep-Alive 等 Node HTTP 层行为的场景。
快速开始:安装与配置
在 SvelteKit 项目中安装适配器:
npm i -D @sveltejs/adapter-node
然后在 vite.config.js 中挂载(本仓库 packages/adapter-node/index.js 是适配器工厂实现,默认选项即如下代码注释所示):
// @errors: 2307 2554
/// file: vite.config.js
import adapter from '@sveltejs/adapter-node';
import { sveltekit } from '@sveltejs/kit/vite';
import { defineConfig } from 'vite';
export default defineConfig({
plugins: [
sveltekit({
adapter: adapter()
})
]
});
安装完成后,适配器会在 npm run build 时接管构建:从源码看,适配器的 adapt() 钩子 依次完成"清空输出目录 → 写入客户端静态资源与预渲染页面 → 按需 gzip/brotli 压缩 → 生成服务端实例 → 拷贝 server 目录 → 写出 index.js 与 handler.js 两个入口"。这也是构建产物结构的来源。
构建与部署
执行 npm run build 后,生产服务器会生成到适配器选项指定的输出目录(默认 build)。运行应用需要三样东西:
- 输出目录(默认
build); - 项目的
package.json; node_modules中的生产依赖。
生产依赖可通过复制 package.json 和 package-lock.json 后执行 npm ci --omit dev 生成(若应用没有任何依赖可跳过)。随后启动:
node build
依赖的打包策略(devDependencies vs dependencies)
一个容易混淆的点是:开发依赖会被打包进应用,而生产依赖保持外部化。官方文档说明开发依赖会使用 Rolldown 打进产物;这一点在源码中得到印证——适配器构建配置 中,Rolldown 的 external 列表包含 package.json 中 dependencies 的所有包名(含深导入路径),因此:
- 放在
devDependencies中的包 → 被 bundle 进build/server,运行时无需安装; - 放在
dependencies中的包 → 保持 external,部署机上必须执行npm ci --omit dev安装。
这直接决定了你的部署机需要携带哪些 node_modules,也解释了为什么 npm ci --omit dev 可以只装生产依赖。
压缩响应(Compressing responses)
生产环境通常需要对服务器响应做压缩。官方文档给出两条路径:
- 优先在反向代理层压缩:如果服务器已经部署在 SSL 终结或负载均衡的反向代理之后,把压缩也放在该层通常性能更好,因为 Node.js 是单线程的,压缩会占用主线程 CPU;
- 自定义服务器中压缩:如果构建的是自定义服务器并希望添加压缩中间件,建议使用
@polka/compression。原因是 SvelteKit 的响应是流式(streaming)的,而更流行的compression包不支持流式压缩,直接使用可能引发错误。
顺带一提,流式响应对反向代理还有一层隐藏要求:在 handler.js 源码 中,当响应 content-type 为 text/event-stream(SSE)时,适配器会自动附加 x-accel-buffering: no 响应头,以规避 nginx 等代理默认缓冲导致的事件流中断——这是源码级佐证:即使部署在反向代理后,adapter-node 也内置了对流式场景的适配。
环境变量:运行时配置的核心
dev 与 preview 模式下,SvelteKit 会按 Vite 的规则从 .env、.env.local、.env.[mode] 读取环境变量。生产模式下 .env 不会自动加载,需要显式使用 Node 的 --env-file 标志:
node --env-file=.env build
下面逐一说明 adapter-node 识别的运行时环境变量。它们的解析逻辑集中在 packages/adapter-node/src/env.js(变量白名单集合见 L4-L18,LISTEN_PID/LISTEN_FDS 属于例外,永远不带前缀读取,见 L20)。
PORT、HOST 与 SOCKET_PATH
默认情况下服务器监听 0.0.0.0:3000,可用 PORT 与 HOST 覆盖:
HOST=127.0.0.1 PORT=4000 node build
也可以指定 socket 路径监听:一旦设置 SOCKET_PATH,HOST 与 PORT 将被忽略。
SOCKET_PATH=/tmp/socket node build
对应实现见 src/index.js:path = env('SOCKET_PATH', false)、host = env('HOST', '0.0.0.0')、port = env('PORT', !path && '3000'),即只有未使用 socket 路径时才默认 3000。
PROTOCOL_HEADER、HOST_HEADER 与 PORT_HEADER
HTTP 协议本身无法可靠地告知 SvelteKit 当前请求的真实 URL。默认情况下,适配器从请求的 host 头(以及未设置 PROTOCOL_HEADER 时的 https 协议)推导 origin。
如果你的应用部署在反向代理之后、请求时的 origin 未知——例如代理不转发 host 头,或者希望为 CSRF 校验使用一个与请求 host 不同的规范 origin——可以设置 paths.origin 配置项:
// @errors: 2307
/// file: vite.config.js
import adapter from '@sveltejs/adapter-node';
import { sveltekit } from '@sveltejs/kit/vite';
import { defineConfig } from 'vite';
export default defineConfig({
plugins: [
sveltekit({
adapter: adapter(),
paths: {
origin: process.env.ORIGIN
}
})
]
});
行为差异在于:未设置 paths.origin(默认)时,adapter-node 从请求推导 origin——优先使用 host 头(若配置了 PROTOCOL_HEADER/PORT_HEADER 则一并参与)——并据此设置 request.url;设置了 paths.origin 时,该值被用作表单提交与远程函数调用的 CSRF 校验所信任的 self-origin,并作为预渲染期间 url.origin 的值。
另一种做法是指定请求头告诉 SvelteKit 协议与主机,由此构造 origin URL:
PROTOCOL_HEADER=x-forwarded-proto HOST_HEADER=x-forwarded-host node build
x-forwarded-proto 与 x-forwarded-host 是反向代理(负载均衡器、CDN)转发原始协议与主机的事实上标准请求头。只有服务器确实位于可信反向代理之后才应设置这些变量,否则客户端可以伪造这些头。若代理运行在非标准端口且支持 x-forwarded-port,还可设置 PORT_HEADER=x-forwarded-port。
从源码看,get_origin() 函数 实现了完整的 origin 推导:读取协议头(默认 https,且会拒绝包含 : 的非法协议值以防 host 注入)、host 头(缺失时报错)、可选端口头(必须是数字),最终拼接 protocol://host:port。当无法推导 origin 时,请求会以 400 响应失败(见 L125-L136)。
如果部署后无法正确确定 URL,使用 form actions 时可能遇到如下错误:
[!NOTE] Cross-site POST form submissions are forbidden
这个错误几乎总是 origin 推导失败的信号,优先检查反向代理头配置。
ADDRESS_HEADER 与 XFF_DEPTH
RequestEvent 提供的 event.getClientAddress() 返回客户端 IP。默认取连接方 remoteAddress;当服务器位于一层或多层代理(如负载均衡器)之后时,该值将是最近一层代理的 IP 而非客户端 IP,因此需要指定 ADDRESS_HEADER 从请求头中读取:
ADDRESS_HEADER=True-Client-IP node build
请求头可以轻易伪造,与 PROTOCOL_HEADER、HOST_HEADER 一样,设置前请确认你了解其中的风险。
当 ADDRESS_HEADER 为 X-Forwarded-For 时,头值是一串逗号分隔的 IP 列表,XFF_DEPTH 用于声明服务器前可信代理的层数。例如有三个可信代理时,代理 3 会转发原始连接与前两个代理的地址:
<client address>, <proxy 1 address>, <proxy 2 address>
有些教程建议读取最左侧地址,但这会留下伪造漏洞:
<spoofed address>, <client address>, <proxy 1 address>, <proxy 2 address>
adapter-node 改为从右侧读取并按可信代理数取偏移,此场景应设置 XFF_DEPTH=3。对应实现位于 handler.js 的 getClientAddress:当 address_header === 'x-forwarded-for' 时,将值按逗号拆分,校验 xff_depth 为正整数且不大于地址数量,然后返回 addresses[addresses.length - xff_depth];若校验失败(深度非法或地址数不足)会抛出明确错误。
[!NOTE] 如果你确实需要读取最左侧地址(不关心伪造问题)——例如提供地理定位服务,更看重 IP 的"真实"而非"可信"——可以在应用内自行检查
x-forwarded-for头实现。
BODY_SIZE_LIMIT
请求体最大字节数(包括流式读取过程中),支持单位后缀:K(千字节)、M(兆字节)、G(吉字节),例如 512K 或 1M。默认 512kb。可设置为 Infinity 禁用(旧版本适配器为 0);如需更高级的控制,可在 handle 钩子中自行实现检查。
源码侧:utils.js 的 parse_as_bytes 按末尾字母映射 1024/1024²/1024³ 倍率进行解析;handler.js 中默认值即为 '512K',解析失败(非数字)会直接抛错拒绝启动。该值最终通过 getRequest 的 bodySizeLimit 参数生效(handler.js L139-L144)。
SHUTDOWN_TIMEOUT
收到 SIGTERM 或 SIGINT 信号后,强制关闭剩余连接前的等待秒数,默认 30。内部调用 Node 的 closeAllConnections。详见下文优雅停机。
IDLE_TIMEOUT
用于 systemd socket 激活场景:指定无请求多少秒后应用自动进入休眠,未设置则持续运行。详见下文 Socket 激活。
KEEP_ALIVE_TIMEOUT 与 HEADERS_TIMEOUT
对应 Node HTTP 服务器的 keepAliveTimeout 与 headersTimeout,单位为秒。实现见 src/index.js:读取后将秒转换为 Node 期望的毫秒(* 1000)再赋值给 httpServer.keepAliveTimeout / httpServer.headersTimeout;非法值(非非负整数)会由 timeout_env 抛出结构化错误(见 env.js L66-L89)。
适配器选项(Options)
适配器支持三个构建期选项,默认值如下:
// @errors: 2307 2554
/// file: vite.config.js
import adapter from '@sveltejs/adapter-node';
import { sveltekit } from '@sveltejs/kit/vite';
import { defineConfig } from 'vite';
export default defineConfig({
plugins: [
sveltekit({
adapter: adapter({
// default options are shown
out: 'build',
precompress: true,
envPrefix: ''
})
})
]
});
out
服务器构建输出目录,默认 build——即构建完成后 node build 即可本地启动。
precompress
是否启用 gzip 与 brotli 预压缩(针对静态资源与预渲染页面),默认 true。构建时由 适配器调用 builder.compress 对 client 与 prerendered 两个目录统一压缩;运行时则由 handler.js 中基于 sirv 的静态服务 按请求协商 gzip/brotli 变体,并正确处理 Vary 头与 MIME 类型(含 text/html;charset=utf-8 修正,以及 /immutable/ 路径的 cache-control: public,max-age=31536000,immutable 长缓存策略)。
envPrefix
当需要变更运行时环境变量的命名前缀(例如与不受你控制的环境变量去冲突)时使用:
envPrefix: 'MY_CUSTOM_';
MY_CUSTOM_HOST=127.0.0.1 \
MY_CUSTOM_PORT=4000 \
node build
前缀机制在 env.js 中有严格校验:若环境中存在以该前缀开头、但去除前缀后不在适配器白名单内的变量,启动会直接抛错("You should change envPrefix … to avoid conflicts"),防止误读无关变量。LISTEN_PID 与 LISTEN_FDS 是例外——无论是否设置前缀,都以原名读取。
优雅停机(Graceful shutdown)
默认情况下,adapter-node 收到 SIGTERM 或 SIGINT 后按三步优雅关闭 HTTP 服务器:
- 拒绝新请求(
server.close); - 等待已进入但尚未返回的请求完成,连接空闲后关闭(
server.closeIdleConnections); - 最终在
SHUTDOWN_TIMEOUT秒后强制关闭仍活跃的连接(server.closeAllConnections)。
完整实现见 src/index.js 的 graceful_shutdown:先关闭空闲连接,再调用 close,并在其回调中清理超时定时器、发出 sveltekit:shutdown 事件;同时设置 shutdown_timeout_id 定时器兜底强杀。信号绑定在 L122-L123。需要自定义该行为时可改用自定义服务器。
sveltekit:shutdown 事件
服务器关闭所有连接后会发出 sveltekit:shutdown 事件。与 Node 的 exit 事件不同,它支持异步操作,且即使服务器仍有悬挂工作(如未关闭的数据库连接)也总会触发:
// @errors: 2304
process.on('sveltekit:shutdown', async (reason) => {
await jobs.stop();
await db.close();
});
reason 参数取值:
SIGINT— 由SIGINT信号触发;SIGTERM— 由SIGTERM信号触发;IDLE— 由IDLE_TIMEOUT触发。
Socket 激活(Socket activation)
现代 Linux 发行版普遍使用 systemd 管理服务。通过 socket 激活,可以让 systemd 预分配监听 socket,并按需启动/缩放应用。此时操作系统向应用传入两个环境变量——LISTEN_PID 和 LISTEN_FDS,适配器将监听指向 systemd socket 单元的文件描述符 3。
[!NOTE]
envPrefix在 systemd socket 激活下依然可用,但LISTEN_PID与LISTEN_FDS始终不带前缀读取。
源码侧,src/index.js 会校验 LISTEN_PID 必须等于当前进程 PID(否则抛错)、LISTEN_FDS 不得超过 1(适配器只接受单个 socket),并据此判定 socket_activation;随后 L76-L79 使用 httpServer.listen({ fd: SD_LISTEN_FDS_START }) 在文件描述符 3 上监听。
按以下步骤启用:
1. 将应用作为 systemd service 运行(可直接运行在宿主机,也可运行在容器内,如 Docker 或 systemd portable service)。若同时传入 IDLE_TIMEOUT,应用在连续无请求达到该秒数后会优雅停机,systemd 会在新请求到来时自动重新拉起。
/// file: /etc/systemd/system/myapp.service
[Service]
Environment=NODE_ENV=production IDLE_TIMEOUT=60
ExecStart=/usr/bin/node /usr/bin/myapp/build
2. 创建配套的 socket unit(适配器只接受单个 socket):
/// file: /etc/systemd/system/myapp.socket
[Socket]
ListenStream=3000
[Install]
WantedBy=sockets.target
3. 让 systemd 识别两个单元并启用:
sudo systemctl daemon-reload
sudo systemctl enable --now myapp.socket
此后首次访问 localhost:3000 时应用会自动启动。空闲休眠逻辑见 src/index.js:每次请求结束时检查请求计数归零,若处于 socket 激活模式且设置了 IDLE_TIMEOUT,则启动定时器执行 graceful_shutdown('IDLE');新请求到来时清除该定时器。
自定义服务器(Custom server)
构建目录包含两个入口:index.js 与 handler.js。运行 index.js(如默认目录下的 node build)会在配置的端口启动完整服务器。
如果需要自行搭建服务器,可导入 handler.js——它导出一个适用于 Express、Connect、Polka(甚至 Node 内置 http.createServer)的处理器:
// @errors: 2307 7006
/// file: my-server.js
import { handler } from './build/handler.js';
import express from 'express';
const app = express();
// add a route that lives separately from the SvelteKit app
app.get('/healthcheck', (req, res) => {
res.end('ok');
});
// let SvelteKit handle everything else, including serving prerendered pages and static assets
app.use(handler);
app.listen(3000, () => {
console.log('listening on port 3000');
});
handler 本身是一组中间件的串行组合(handler.js L280-L283):依次是静态资源服务(client 目录)、预渲染页面服务(含尾斜杠 308 重定向逻辑,见 L92-L117)以及 SSR 主逻辑,未命中时交由外层框架(如 Express 的 next)处理,最外层默认服务器则返回 404(src/index.js L70-L73)。
[!NOTE] 使用
handler.js时,只有 handler 自身读取的环境变量生效:PROTOCOL_HEADER、HOST_HEADER、PORT_HEADER、ADDRESS_HEADER、XFF_DEPTH和BODY_SIZE_LIMIT。服务器生命周期类变量(
PORT、HOST、SOCKET_PATH、SHUTDOWN_TIMEOUT、IDLE_TIMEOUT、KEEP_ALIVE_TIMEOUT、HEADERS_TIMEOUT、LISTEN_PID、LISTEN_FDS)仅由默认的node build服务器处理。自定义服务器若需同样行为须自行实现——例如上面示例中无论PORT如何设置都硬编码监听3000。
源码结构与测试印证
如需深入验证上述行为,可直接阅读本仓库的 adapter-node 包:
- src/env.js — 环境变量白名单、
envPrefix冲突校验与数值解析,配套测试见 src/env.spec.ts; - src/handler.js — origin 推导、客户端地址解析、请求体限制、静态资源与预渲染服务、SSE 响应头处理;
- src/index.js — 端口/socket 监听、Keep-Alive/Headers 超时、请求计数、优雅停机与 socket 激活;
- src/utils.js — 字节单位解析与监听地址格式化,配套测试见 src/utils.spec.ts;
- packages/adapter-node/index.js — 适配器工厂:
out/precompress/envPrefix选项处理、构建流程与 Rolldown 打包配置; - packages/adapter-node/package.json — 包声明与 peer 依赖(要求
@sveltejs/kitv3 及以上)。
此外,packages/adapter-node/test/apps/basic 提供了完整的端到端测试应用(含 Playwright 用例),可作为"一个真实的 adapter-node 部署项目长什么样"的参考样板。