SvelteKit adapter-node 实战指南:构建、部署与运维独立 Node 服务器

原创2026-09-20 15:33:231,996 阅读
文章标签:Web框架后端前端

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)。运行应用需要三样东西:

  1. 输出目录(默认 build);
  2. 项目的 package.json;
  3. 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 服务器:

  1. 拒绝新请求(server.close);
  2. 等待已进入但尚未返回的请求完成,连接空闲后关闭(server.closeIdleConnections);
  3. 最终在 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 包:

此外,packages/adapter-node/test/apps/basic 提供了完整的端到端测试应用(含 Playwright 用例),可作为"一个真实的 adapter-node 部署项目长什么样"的参考样板。

登录后查看全文
kit