sveltekit-remote-functions

SvelteKit 远程函数

当前状态

远程函数在 SvelteKit 2.58 中仍为实验性功能。建议通过 SvelteKit Vite 插件在 vite.config.ts 中启用：

import { sveltekit } from '@sveltejs/kit/vite';
import { defineConfig } from 'vite';

export default defineConfig({
	plugins: [
		sveltekit({
			experimental: { remoteFunctions: true },
			compilerOptions: { experimental: { async: true } } // only for await in components
		})
	]
});

快速入门

文件命名： 从 *.remote.ts 或 *.remote.js 导出远程函数。 远程文件可以放在 src 下的任意位置，但不能放在 src/lib/server 中。

使用哪个函数？

• 动态读取 → query()
• 实时服务端流 → query.live()
• 渐进式表单 → form()
• 事件处理器中的变更 → command()
• 构建时／静态读取 → prerender()

示例

// posts.remote.ts
import { command, query, requested } from "$app/server";
import * as v from "valibot";

export const getPosts = query(
	v.object({ tag: v.optional(v.string()) }),
	async (filter) => {
		return db.posts.find(filter);
	},
);

export const createPost = command(
	v.object({ title: v.string() }),
	async (data) => {
		await db.posts.create(data);

		for (const { query } of requested(getPosts, 5)) {
			void query.refresh();
		}
	},
);

客户端：

<script lang="ts">
	import { createPost, getPosts } from './posts.remote';

	const posts = $derived(await getPosts({ tag: 'svelte' }));
</script>

<button onclick={() => createPost({ title: 'New' }).updates(getPosts)}>
	Create
</button>

当前规则

• svelte.config.js 在 Kit 2 中仍然有效，但 Kit 3 将改为从 Vite 插件读取 Kit 配置。
• 远程函数始终在服务端运行，即使它们是从浏览器调用的也是如此。
• 参数和返回值使用 devalue；避免使用函数、类实例、符号、循环引用和 RegExp。
• 使用 Standard Schema（valibot、zod、arktype 等）验证对外开放的输入，或有意使用 .unchecked／'unchecked'。
• query.batch() 会批量处理同一宏任务中的调用，以解决 n+1 次读取问题。
• query.live() 返回异步可迭代对象；SSR 使用首次生成的值，客户端会在渲染期间保持连接。
• 如果某个变更可以通知监听器（Promise.withResolvers()／pubsub），优先使用事件驱动的实时查询，而不是轮询。
• 实时查询提供 connected 和 reconnect()，但不提供 refresh()；.run() 会返回 Promise<AsyncGenerator<T>>。
• 不要对实时查询响应使用 Service Worker 缓存；排除 Cache-Control: no-store 流。
• form().enhance() 的 submit() 在提交有效／成功时返回 true，在验证失败时返回 false。
• .updates() 由客户端请求；服务端处理器必须通过 requested(queryFn, limit) 显式启用。
• requested() 现在会生成 { arg, query }；请对绑定的实例调用 query.refresh()／query.set(...)。
• requested() 必须指定 limit，以限制客户端可控的刷新请求。
• 在 command/form 处理器中，使用 void query.refresh()／void query.set(value)；SvelteKit 会等待并序列化这些更新。
• 对于实时查询，单航班变更可以调用 void live_query.reconnect()。
• 如果需要渐进增强，优先使用 form() 而不是 command()。
• 对于每次部署最多变化一次的数据，使用 prerender()。
• 最后验证时间： 2026-06-08

参考文件

• references/remote-functions.md - 当前模式、示例和注意事项