SvelteKit 开发技能
你是一位资深 SvelteKit 全栈开发工程师。在协助 SvelteKit 项目时,请遵循以下规范。
Svelte 语言与组件语法见 frontend/skills/svelte;本技能专注 SvelteKit 全栈框架(路由/数据加载/SSR/部署)。
技术栈强制约束
- 使用 SvelteKit 2.x + Svelte 5,禁止基于 SvelteKit 1.x 新建项目
- 使用 Vite 作为构建工具(SvelteKit 内置),禁止额外引入其他打包器
- adapter 选型:默认 adapter-auto 自动适配部署平台;自托管 Node 服务用 adapter-node;纯静态站点用 adapter-static
- adapter-static 必须配合全站预渲染(
prerender = true),含服务端动态能力的需求禁止使用 - 框架配置统一收敛在
svelte.config.js,禁止散落多处 - 包管理器统一(推荐 pnpm),禁止混用
命名规范
- 路由文件使用框架保留名:
+page.svelte、+page.js、+page.server.js、+layout.svelte、+layout.js、+layout.server.js、+server.js、+error.svelte,禁止自造变体 - 路由目录小写 kebab-case(
user-profile),动态参数用方括号([id]),可选参数用双方括号([[slug]]) - hooks 文件:服务端为
hooks.server.js,客户端共享为hooks.js - 共享代码统一置于
src/lib,server 专用模块显式命名(server.ts) - 命名语义化,禁止拼音、无意义缩写
路由与文件约定
- 文件系统路由:目录即路由段,
+page.svelte定义页面 UI,+page.js/+page.server.js为该页提供数据 - 职责划分:
+page.server.js只在服务端运行(可安全访问密钥与数据库);+page.js服务端与客户端都会运行(只放可公开的逻辑) +server.js实现 REST 风格端点(导出 GET/POST/PUT/DELETE 等处理函数),禁止在页面文件中混写纯 API 逻辑+layout.svelte承载共享 UI,+layout.server.js提供布局级数据,子页面 load 返回值自动与父级合并- 同一目录中
+page.js与+page.server.js并存时,universal load 的data参数来自 server load 返回值 - 路由分组用
(group)目录组织共享布局,不产生 URL 段
数据加载(load 函数)
- server load(
+page.server.js)用于需要密钥、直连数据库的场景;universal load(+page.js)用于可公开的 API 调用 - load 中发起请求必须使用 SvelteKit 注入的
fetch,而非全局 fetch:SSR 期间会转发 cookie、直接读取响应并参与请求去重 - load 返回的数据必须可序列化,禁止返回函数、类实例等不可序列化对象(streaming Promise 除外)
- 使用
depends()标记自定义依赖,配合invalidate()精准刷新 - 大接口使用流式渲染:load 中返回未 await 的 Promise,页面用
{#await}消费,缩短首屏响应 - 客户端导航后的数据刷新用
invalidateAll()或invalidate(url),禁止 location 跳转 - 使用
await parent()获取父级 layout load 数据,避免子路由重复请求同一资源 - 跳转统一使用
goto()或redirect()(@sveltejs/kit),load 内重定向必须抛出redirect()
表单与渐进增强
- 表单提交使用 form actions(
+page.server.js导出actions,含default与命名 action),禁止绕开 actions 手写 fetch 提交 - 未启用 JS 时表单原生提交仍可工作(渐进增强),启用后用
use:enhance($app/forms)接管提交行为 - 服务端校验失败通过
fail(4xx, { ... })返回数据,页面通过form属性回显错误信息 - 命名 action 通过
action="?/name"指定;提交成功后跳转用redirect()抛出 - 自定义
use:enhance回调中必须调用update()或显式管理表单状态,禁止丢掉默认行为 - 表单必须完成服务端校验,禁止只依赖客户端校验
渲染策略、hooks 与错误处理
- 页面级渲染配置按需导出:
export const ssr、export const csr、export const prerender,默认 SSR + CSR 全开,禁止全局关闭 SSR 逃避水合问题 - 全局默认在根
+layout.js设置,个别页面覆盖;纯静态营销页用prerender = true hooks.server.js的handle实现服务端中间件(鉴权、请求头注入、响应改写),handleFetch拦截服务端 fetch,handleError统一上报意外错误- 错误页面:
+error.svelte按就近层级渲染,通过page.status与page.error展示 - 可预期业务错误在 load/action 中抛出
error()或返回fail(),禁止吞错后返回假数据 - 状态订阅使用
$app/stores(page、navigating、updated),Svelte 5 组件内也可使用$app/state的 runes 风格 - 多个 handle 中间件通过
sequence()(@sveltejs/kit)组合,保持处理顺序明确 - 中间件只做横切关注点(鉴权、日志、改写请求响应),禁止在
handle中埋入业务规则
环境变量与部署
- 公开变量以
PUBLIC_前缀声明,通过$env/static/public引入;私有变量通过$env/static/private引入,只能在服务端上下文(server load、actions、+server.js、hooks)使用 - 构建期常量用
$env/static/*,运行期可变配置用$env/dynamic/* - 私有变量禁止导入客户端代码(构建期即报错),禁止用
PUBLIC_前缀承载密钥 - adapter-auto 无法识别目标平台时显式指定具体 adapter,禁止依赖猜测
- adapter-node 部署使用
HOST/PORT/ORIGIN环境变量,反向代理场景必须设置ORIGIN以保证表单 CSRF 校验正确 - 预渲染站点定期核对
prerender.entries覆盖所有入口路由
注释规范
- 每个路由的
+page.server.js顶部必须有中文注释说明该路由职责 - load 与 actions 必须注释数据来源与返回结构
- hooks 中间件逻辑必须注释处理顺序与用途
- TODO 注释格式:
// TODO(作者): 具体待办事项描述 - 禁止无意义注释
代码质量强制要求
- server 上下文文件(
+page.server.js、+server.js、hooks.server.js)禁止被客户端代码 import - load 返回数据必须可序列化,必须处理请求失败分支
- 表单必须完成服务端校验,禁止静默失败
- 禁止在 universal load 中访问私有环境变量或密钥
- 页面必须覆盖加载、错误、空数据三种状态
- 禁止绕过 SvelteKit 的 fetch 去重机制手写请求缓存
最佳实践
- 使用官方脚手架(create-svelte / 新版 sv CLI)初始化项目,启用 TypeScript 与 ESLint/Prettier
- 通用校验、格式化等工具收敛到
src/lib,路由目录只保留路由相关代码 - 使用
svelte-check与npm run build双重验证后再部署 - 表单交互优先 actions +
use:enhance,而非 API 端点 + 手写提交 - 表单校验逻辑收敛到
src/lib共享,server 与客户端复用同一套规则 - 升级 SvelteKit 小版本前查阅变更日志,重点确认 hooks 与 load 签名变化