SvelteKit 断点调试完整指南从 VSCode 到浏览器 DevTools 的前后端单步调试【免费下载链接】kitweb development, streamlined项目地址: https://gitcode.com/gh_mirrors/kit/kit导读SvelteKit 应用同时包含浏览器端客户端组件、load中的通用代码与 Node.js 服务端server.js、服务端load、form actions、hooks两类运行环境调试时往往需要在同一套断点工具中贯穿前后端。本篇基于 SvelteKit 官方文档的断点调试章节结合仓库源码系统讲解在 VSCode、WebStorm、Neovim 以及 Google Chrome / Microsoft Edge 中为 SvelteKit 项目设置断点、逐行单步、检查变量的完整方法。读完后你将掌握三条可落地的调试路径VSCode 内置调试终端、launch.json一键启动以及浏览器 DevTools 直连 Node.js 调试器并理解 SvelteKit 源码映射sourcemap在这些方案中起到的支撑作用。调试前的准备理解 SvelteKit 的双端执行模型SvelteKit 应用由vite dev驱动的开发服务器承载仓库中 playground 项目的dev脚本即为vite dev参见 playgrounds/basic/package.json。在开发模式下客户端代码page.svelte、客户端组件、通用load等在浏览器中执行服务端代码page.server.js、server.js、hooks、form actions在 Node.js 进程中执行由 packages/kit/src/exports/vite/dev/index.js 中的dev()函数将请求转交给 SvelteKit 运行时处理同一份.svelte文件中的script与script module可能分别运行在两端因此调试时需要明确断点属于哪一端。除 Svelte 模板中的debug标签外它只能在模板表达式中插入并自动暂停渲染断点调试适合在复杂逻辑、事件处理函数、load与服务端接口中深入排查。以下指南均假设 JavaScript 运行时为 Node.js。在 Visual Studio Code 中断点调试VSCode 内置的 JavaScript 调试器基于 debugger 协议可以直接附加到开发进程无需安装额外扩展。有两种启动方式方式一通过JavaScript 调试终端启动这是最轻量的方案适合临时调试步骤如下打开命令面板CMD/CtrlShiftP搜索并启动Debug: JavaScript Debug Terminal在该调试终端中启动项目例如执行npm run dev在客户端或服务端源码中设置断点点击行号左侧空白处出现红点即生效在浏览器中触发对应页面或接口断点命中后即可在调试面板查看调用栈、变量与表达式。关键点在于必须使用调试终端启动进程普通集成终端启动的进程不会挂载调试器断点不会命中。SvelteKit 依赖 Vite 的编译管线源码文件在 dev 模式下会被实时转换VSCode 调试器配合 sourcemap 可以自动将编译产物映射回你书写的原始.svelte、.js、.ts文件因此断点应直接打在源码上。方式二通过launch.json从调试面板启动如果需要可复现、可提交到团队仓库的调试配置推荐在项目中维护.vscode/launch.json。自动生成方式打开左侧Run and Debug运行和调试面板在顶部的 Run 下拉菜单中选择Node.js...选择与项目对应的运行脚本例如 Run script: dev对应package.json中的scripts.dev点击 Start debugging 播放按钮或直接按F5开始断点调试。手动创建时的最小示例配置如下{ version: 0.2.0, configurations: [ { command: npm run dev, name: Run development server, request: launch, type: node-terminal } ] }对该配置逐项说明type: node-terminal在 VSCode 的终端中启动 Node 进程并自动附加调试器是调试npm run dev这类脚本的首选类型request: launch表示由调试器直接启动程序而非attach到已运行进程command要执行的启动命令。若项目使用 pnpm 或 yarn可相应改为pnpm dev、yarn devname显示在调试面板中的名称可自由命名。如需对特定场景如调试svelte-kit sync、构建产物或生产预览vite preview扩展配置可在configurations数组中追加多个对象并通过调试面板下拉切换。更进一步可在launch.json的同级添加tasks.json定义预执行任务如先svelte-kit sync再启动这里不再展开。其他编辑器的断点调试如果你不使用 VSCode以下工具同样支持对 SvelteKit 项目的断点调试WebStorm / IntelliJ IDEAJetBrains 系列 IDE 提供对 Svelte 的一等支持可直接为npm run dev创建 Node.js 运行配置并打断点官方帮助中心提供 Debug your application 一节详细说明 Svelte 项目调试流程Neovim借助基于 Debug Adapter ProtocolDAP的插件如 nvim-dap js-debug adapter同样可以附加到 dev 进程进行断点调试社区有专门针对 JavaScript 框架含 Svelte/SvelteKit的调试文章可供参考。无论使用哪种编辑器其底层调试能力都依赖 Node.js 的 inspector 协议与 sourcemap 映射原理与 VSCode 完全一致。使用 Chrome / Edge DevTools 调试 SvelteKitNode.js 从 v6.3 起内置了基于 DevTools 协议的 inspector因此完全可以不依赖 IDE直接用浏览器调试 SvelteKit 的服务端与客户端代码。[!NOTE] 此方式仅适用于调试客户端侧 SvelteKit 源码映射即浏览器中执行的那部分代码组件、通用load、事件处理等可以正确映射回源码Node.js 进程内执行的代码服务端load、server.js等需要配合源码映射配置才能映射回原始文件默认开发模式下 Vite 会为 SSR 环境生成 sourcemap详见下文源码分析。操作步骤启动 Vite 服务器时附加--inspect标志例如NODE_OPTIONS--inspect npm run dev在新标签页打开站点默认地址为http://localhost:5173打开浏览器开发者工具点击左上角带有Node.js logo的 Open dedicated DevTools for Node.js打开专门用于 Node.js 的 DevTools图标在专用 DevTools 中设置断点触发页面交互即可调试服务端/客户端逻辑。此外也可以直接在地址栏导航到Google Chromechrome://inspectMicrosoft Edgeedge://inspect在设备列表中点击对应进程的 inspect即可打开 Node.js 专用调试面板。chrome://inspect页面会列出所有通过--inspect暴露的 Node.js 进程适合同时调试多个服务。关键提示为何断点能映射回源码SvelteKit 的 Vite 插件在构建/开发配置中显式启用了 sourcemap 支持。从源码可见packages/kit/src/exports/vite/index.js 中强制设置了 SSR 环境的 sourcemap 默认值environments: { ssr: { build: { sourcemap: config.environments?.ssr?.build?.sourcemap ?? config.build?.sourcemap ?? true } } }即当你在vite.config.js中未显式关闭 sourcemap 时服务端环境默认开启源码映射DevTools 与 VSCode 才能将编译产物定位回.svelte/.ts原始文件。同时插件通过sourcemapIgnoreList见 packages/kit/src/exports/vite/index.js将node_modules与.svelte-kit输出目录排除在调试堆栈之外避免在调试面板中看到框架内部噪音让你直接定位到业务代码。生产构建时vite build的 sourcemap 行为则由build.sourcemap配置控制若生产调试或错误堆栈还原需要可在vite.config.js中显式开启例如build: { sourcemap: true }但生产环境开启会增大产物体积建议仅在排查线上问题时临时使用。调试实战要点与常见坑同时调试前后端SvelteKit 一个典型调试场景是点击按钮 → 触发 form action 或 fetch 到server.js→ 服务端处理 → 返回数据 → 客户端更新 UI。推荐做法在客户端事件处理与通用load中打断点在Chrome/Edge DevTools中观察在page.server.js的load、form actions、server.js的请求处理函数中打断点在VSCode 调试终端或Node.js 专用 DevTools中观察两者可同时开启形成请求链路级的端到端调试。断点不命中的常见原因修改代码后未刷新页面或未重启 dev 进程Vite 热更新通常足够但调试器附加的进程若已崩溃需重启断点打在未实际执行的分支如仅 SSR 运行的代码在客户端断点无效反之亦然使用了普通终端而非调试终端启动VSCode 场景sourcemap 被关闭检查vite.config.js是否设置了sourcemap: false。调试生产构建如需在生产构建产物上调试例如复现适配器部署后的行为可用node --inspect build方式启动由适配器生成的服务如 packages/adapter-node 的输出再通过chrome://inspect附加。生产构建的源码映射需在构建时保留且不同适配器的输出结构不同调试体验不如 dev 模式顺畅通常仅作为兜底手段。参考资料Node.js 官方文档中的 Debugging 章节详细讲解--inspect、--inspect-brk、chrome://inspect 的工作原理与高级用法VSCode 官方调试文档涵盖launch.json全部字段、node-terminal类型与断点行为配置WebStorm 官方帮助中心对 Svelte 开发的调试说明社区关于在 Neovim 中调试 JavaScript 框架的实践文章。这些资料与本仓库的 SvelteKit 调试文档 相互印证可作为深入学习的下一步起点。【免费下载链接】kitweb development, streamlined项目地址: https://gitcode.com/gh_mirrors/kit/kit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 SvelteKit 断点调试完整指南：从 VSCode 到浏览器 DevTools 的前后端单步调试
SvelteKit 断点调试完整指南从 VSCode 到浏览器 DevTools 的前后端单步调试【免费下载链接】kitweb development, streamlined项目地址: https://gitcode.com/gh_mirrors/kit/kit导读SvelteKit 应用同时包含浏览器端客户端组件、load中的通用代码与 Node.js 服务端server.js、服务端load、form actions、hooks两类运行环境调试时往往需要在同一套断点工具中贯穿前后端。本篇基于 SvelteKit 官方文档的断点调试章节结合仓库源码系统讲解在 VSCode、WebStorm、Neovim 以及 Google Chrome / Microsoft Edge 中为 SvelteKit 项目设置断点、逐行单步、检查变量的完整方法。读完后你将掌握三条可落地的调试路径VSCode 内置调试终端、launch.json一键启动以及浏览器 DevTools 直连 Node.js 调试器并理解 SvelteKit 源码映射sourcemap在这些方案中起到的支撑作用。调试前的准备理解 SvelteKit 的双端执行模型SvelteKit 应用由vite dev驱动的开发服务器承载仓库中 playground 项目的dev脚本即为vite dev参见 playgrounds/basic/package.json。在开发模式下客户端代码page.svelte、客户端组件、通用load等在浏览器中执行服务端代码page.server.js、server.js、hooks、form actions在 Node.js 进程中执行由 packages/kit/src/exports/vite/dev/index.js 中的dev()函数将请求转交给 SvelteKit 运行时处理同一份.svelte文件中的script与script module可能分别运行在两端因此调试时需要明确断点属于哪一端。除 Svelte 模板中的debug标签外它只能在模板表达式中插入并自动暂停渲染断点调试适合在复杂逻辑、事件处理函数、load与服务端接口中深入排查。以下指南均假设 JavaScript 运行时为 Node.js。在 Visual Studio Code 中断点调试VSCode 内置的 JavaScript 调试器基于 debugger 协议可以直接附加到开发进程无需安装额外扩展。有两种启动方式方式一通过JavaScript 调试终端启动这是最轻量的方案适合临时调试步骤如下打开命令面板CMD/CtrlShiftP搜索并启动Debug: JavaScript Debug Terminal在该调试终端中启动项目例如执行npm run dev在客户端或服务端源码中设置断点点击行号左侧空白处出现红点即生效在浏览器中触发对应页面或接口断点命中后即可在调试面板查看调用栈、变量与表达式。关键点在于必须使用调试终端启动进程普通集成终端启动的进程不会挂载调试器断点不会命中。SvelteKit 依赖 Vite 的编译管线源码文件在 dev 模式下会被实时转换VSCode 调试器配合 sourcemap 可以自动将编译产物映射回你书写的原始.svelte、.js、.ts文件因此断点应直接打在源码上。方式二通过launch.json从调试面板启动如果需要可复现、可提交到团队仓库的调试配置推荐在项目中维护.vscode/launch.json。自动生成方式打开左侧Run and Debug运行和调试面板在顶部的 Run 下拉菜单中选择Node.js...选择与项目对应的运行脚本例如 Run script: dev对应package.json中的scripts.dev点击 Start debugging 播放按钮或直接按F5开始断点调试。手动创建时的最小示例配置如下{ version: 0.2.0, configurations: [ { command: npm run dev, name: Run development server, request: launch, type: node-terminal } ] }对该配置逐项说明type: node-terminal在 VSCode 的终端中启动 Node 进程并自动附加调试器是调试npm run dev这类脚本的首选类型request: launch表示由调试器直接启动程序而非attach到已运行进程command要执行的启动命令。若项目使用 pnpm 或 yarn可相应改为pnpm dev、yarn devname显示在调试面板中的名称可自由命名。如需对特定场景如调试svelte-kit sync、构建产物或生产预览vite preview扩展配置可在configurations数组中追加多个对象并通过调试面板下拉切换。更进一步可在launch.json的同级添加tasks.json定义预执行任务如先svelte-kit sync再启动这里不再展开。其他编辑器的断点调试如果你不使用 VSCode以下工具同样支持对 SvelteKit 项目的断点调试WebStorm / IntelliJ IDEAJetBrains 系列 IDE 提供对 Svelte 的一等支持可直接为npm run dev创建 Node.js 运行配置并打断点官方帮助中心提供 Debug your application 一节详细说明 Svelte 项目调试流程Neovim借助基于 Debug Adapter ProtocolDAP的插件如 nvim-dap js-debug adapter同样可以附加到 dev 进程进行断点调试社区有专门针对 JavaScript 框架含 Svelte/SvelteKit的调试文章可供参考。无论使用哪种编辑器其底层调试能力都依赖 Node.js 的 inspector 协议与 sourcemap 映射原理与 VSCode 完全一致。使用 Chrome / Edge DevTools 调试 SvelteKitNode.js 从 v6.3 起内置了基于 DevTools 协议的 inspector因此完全可以不依赖 IDE直接用浏览器调试 SvelteKit 的服务端与客户端代码。[!NOTE] 此方式仅适用于调试客户端侧 SvelteKit 源码映射即浏览器中执行的那部分代码组件、通用load、事件处理等可以正确映射回源码Node.js 进程内执行的代码服务端load、server.js等需要配合源码映射配置才能映射回原始文件默认开发模式下 Vite 会为 SSR 环境生成 sourcemap详见下文源码分析。操作步骤启动 Vite 服务器时附加--inspect标志例如NODE_OPTIONS--inspect npm run dev在新标签页打开站点默认地址为http://localhost:5173打开浏览器开发者工具点击左上角带有Node.js logo的 Open dedicated DevTools for Node.js打开专门用于 Node.js 的 DevTools图标在专用 DevTools 中设置断点触发页面交互即可调试服务端/客户端逻辑。此外也可以直接在地址栏导航到Google Chromechrome://inspectMicrosoft Edgeedge://inspect在设备列表中点击对应进程的 inspect即可打开 Node.js 专用调试面板。chrome://inspect页面会列出所有通过--inspect暴露的 Node.js 进程适合同时调试多个服务。关键提示为何断点能映射回源码SvelteKit 的 Vite 插件在构建/开发配置中显式启用了 sourcemap 支持。从源码可见packages/kit/src/exports/vite/index.js 中强制设置了 SSR 环境的 sourcemap 默认值environments: { ssr: { build: { sourcemap: config.environments?.ssr?.build?.sourcemap ?? config.build?.sourcemap ?? true } } }即当你在vite.config.js中未显式关闭 sourcemap 时服务端环境默认开启源码映射DevTools 与 VSCode 才能将编译产物定位回.svelte/.ts原始文件。同时插件通过sourcemapIgnoreList见 packages/kit/src/exports/vite/index.js将node_modules与.svelte-kit输出目录排除在调试堆栈之外避免在调试面板中看到框架内部噪音让你直接定位到业务代码。生产构建时vite build的 sourcemap 行为则由build.sourcemap配置控制若生产调试或错误堆栈还原需要可在vite.config.js中显式开启例如build: { sourcemap: true }但生产环境开启会增大产物体积建议仅在排查线上问题时临时使用。调试实战要点与常见坑同时调试前后端SvelteKit 一个典型调试场景是点击按钮 → 触发 form action 或 fetch 到server.js→ 服务端处理 → 返回数据 → 客户端更新 UI。推荐做法在客户端事件处理与通用load中打断点在Chrome/Edge DevTools中观察在page.server.js的load、form actions、server.js的请求处理函数中打断点在VSCode 调试终端或Node.js 专用 DevTools中观察两者可同时开启形成请求链路级的端到端调试。断点不命中的常见原因修改代码后未刷新页面或未重启 dev 进程Vite 热更新通常足够但调试器附加的进程若已崩溃需重启断点打在未实际执行的分支如仅 SSR 运行的代码在客户端断点无效反之亦然使用了普通终端而非调试终端启动VSCode 场景sourcemap 被关闭检查vite.config.js是否设置了sourcemap: false。调试生产构建如需在生产构建产物上调试例如复现适配器部署后的行为可用node --inspect build方式启动由适配器生成的服务如 packages/adapter-node 的输出再通过chrome://inspect附加。生产构建的源码映射需在构建时保留且不同适配器的输出结构不同调试体验不如 dev 模式顺畅通常仅作为兜底手段。参考资料Node.js 官方文档中的 Debugging 章节详细讲解--inspect、--inspect-brk、chrome://inspect 的工作原理与高级用法VSCode 官方调试文档涵盖launch.json全部字段、node-terminal类型与断点行为配置WebStorm 官方帮助中心对 Svelte 开发的调试说明社区关于在 Neovim 中调试 JavaScript 框架的实践文章。这些资料与本仓库的 SvelteKit 调试文档 相互印证可作为深入学习的下一步起点。【免费下载链接】kitweb development, streamlined项目地址: https://gitcode.com/gh_mirrors/kit/kit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考