WebStorm 2026.1 原生支持 SvelteKit 全栈开发，但需手动配置三类关键设置：启用 SSR 调试、API 路由跳转和类型推导；否则 npm run dev 会降级为 CSR，导致页面空白或 404、+server.ts 断点失效、类型提示缺失等问题。
WebStorm 2026.1 原生支持 SvelteKit 全栈开发，但默认不启用服务端渲染调试、API 路由跳转和类型推导，必须手动配齐三类关键设置才能真正跑通 SSR + API + 类型安全的完整链路。
为什么 npm run dev 启动后页面空白或 404？
SvelteKit 默认使用 adapter-auto，但在 WebStorm 中未识别为全栈模式时，会降级为纯客户端渲染（CSR），导致服务端路由（如 +page.server.ts）不执行、load 函数不触发、POST /api/xxx 返回 404。
- 确认项目根目录存在
svelte.config.js，且导出含kit.adapter配置（如adapter-node或adapter-static） - 在 WebStorm 中右键项目 → “Reload project from disk”，强制刷新框架识别状态
- 打开
Run → Edit Configurations…，检查启动脚本是否为npm run dev（不是vite dev），并勾选 “Allow parallel run” —— SvelteKit 需要同时监听客户端和服务端端口
如何让 +server.ts 断点生效？
WebStorm 默认只附加到 Vite 的前端进程，+server.ts 运行在 Node.js 子进程中，不配置就无法单步调试。
- 在
Run → Edit Configurations…中，新增一个 Node.js 配置 -
Working directory设为项目根目录，JavaScript file填node_modules/.bin/svelte-kit -
Application parameters填dev --host（加--host是为了让 WebStorm 能连上本地服务） - 运行前确保已执行
npm install安装svelte-kitCLI 工具，否则.bin/svelte-kit不存在
import type 提示失效或跳转错误？
WebStorm 对 SvelteKit 的类型生成路径（.svelte-kit/types）识别不稳定，尤其在首次启动或 svelte-kit sync 后未自动索引。
- 手动触发类型同步：终端中运行
npx svelte-kit sync，然后 File → Synchronize - 检查
Settings → Languages & Frameworks → JavaScript → Libraries，确认.svelte-kit/types已被标记为 “Source”（而非 “Not included”） - 若
$lib别名跳转失败，在tsconfig.json的compilerOptions.paths中确认映射正确，例如："$lib/*": ["src/lib/*"]
服务端组件（+layout.server.ts）里不能用 document 却没报错？
这是 WebStorm 类型检查未严格区分服务端/客户端上下文导致的静默问题。SvelteKit 编译时会剥离服务端代码中的 DOM API，但 IDE 不提示。
- 启用
Settings → Editor → Inspections → TypeScript → Unresolved variable，并勾选Check all scopes - 在服务端文件顶部加
/// <reference types="svelte"></reference> /// <reference types="@sveltejs/kit"></reference>显式声明环境 - 更可靠的做法：把 DOM 操作逻辑抽离到
onMount或browser判断块中，WebStorm 对import { browser } from '$app/environment'的条件分支有准确类型推导
最易被忽略的是 svelte.config.js 中 kit.typescript.skipLibCheck 设为 true 时，WebStorm 的类型索引会跳过 .svelte-kit/types，导致所有服务端类型提示失效——这个开关必须关掉，哪怕编译变慢一点。
