先确认 TypeScript 类型系统是否就位：需安装 @builder.io/qwik@2.6+，tsconfig.json 的 compilerOptions.types 必须包含 "@builder.io/qwik"，jsx 设为 "preserve"，且 extends 不得覆盖关键配置。
Qwik 项目在 VSCode 里无法识别 useSignal$ 等宏？先确认类型系统是否就位
这不是插件没装好，而是 TypeScript 编译器压根没加载 Qwik 的类型定义。即使插件装了、重启了，tsc 和 VSCode 内置 TS 服务仍会报 "Cannot find name 'useSignal$'"。
- 确保已安装
@builder.io/qwik@2.6+，且node_modules/@builder.io/qwik/tsconfig.json存在 - 项目根目录的
tsconfig.json中，compilerOptions.types必须显式包含"@builder.io/qwik" -
compilerOptions.jsx必须设为"preserve"（不是"react"或"react-jsx"） - 若使用
extends，检查被继承文件（如tsconfig.base.json）是否覆盖或清空了types或jsx
SSR 断点调试时断点不命中？关键在 launch.json 的 type 和 sourceMapPathOverrides
Qwik 的 SSR 渲染由 Node.js 进程驱动（比如 qwik-city 的 serverless entry），不能用 pwa-chrome 类型直接调试。必须切换到 Node.js 调试模式，并正确映射源码路径。
- 在
.vscode/launch.json中使用"type": "pwa-node"，而非pwa-chrome或node -
"program"指向 SSR 入口，常见路径是"dist/server/entry.dev.ts"或"src/entry.dev.ts"（取决于你用的是 dev server 还是自建 build） -
"sourceMapPathOverrides"必须匹配构建输出中的 sourcemap 路径，例如 Vite 默认生成webpack:///./src/...，应写为："webpack:///./src/*": "${webRoot}/src/*" - 启动前确保已运行
npm run dev或npm run build & npm run serve，否则调试器连不上目标进程
VSCode 调试器连上了但变量为空、调用栈混乱？检查是否启用了 ESM 支持
Qwik v2+ 默认使用 ES modules，而旧版 Node.js 调试器对 import / export 的 sourcemap 解析不完整，会导致断点停在编译后代码、this 或局部变量显示为 undefined。
- 确认 Node.js 版本 ≥ 18.18.0（推荐 20.9.0+），并在
launch.json中添加："runtimeArgs": ["--enable-source-maps"] - 避免在
package.json中设置"type": "module"后又混用require()—— Qwik SSR 入口必须是 ESM，但部分插件或工具链可能仍依赖 CJS - 如果用的是
qwik-city，确保middleware.ts和entry.dev.ts都是.ts后缀且导出为export default函数，而非module.exports =
热更新（HMR）失效导致 SSR 断点“只生效一次”？inotify 限制常被忽略
Qwik 的 HMR 依赖文件系统事件通知，而 VSCode（尤其 WSL 用户）的 Remote - WSL 扩展或 Docker 插件会干扰 inotify 句柄，造成开发服务器收不到变更信号，调试器也就无法重新 attach 到新进程。
- 在 WSL 中执行
cat /proc/sys/fs/inotify/max_user_watches，若低于 524288，需临时提升：echo 524288 | sudo tee /proc/sys/fs/inotify/max_user_watches - 关闭 VSCode 中可能冲突的扩展：Remote - WSL、Docker、GitLens（某些版本会劫持文件监听）
- 在 Qwik 项目根目录下运行
npm run dev时，观察终端是否打印[vite] hmr update日志 —— 若无，则 HMR 已静默失败，此时断点只会作用于首次启动的进程
Qwik 的 SSR 调试难点不在配置本身，而在于它横跨三套机制：TypeScript 类型系统、Vite/Esm 模块解析、Node.js 原生调试协议。任一环节的路径映射或运行时假设错位，都会让断点“看起来设上了，实际没停住”。最易漏掉的是 sourceMapPathOverrides 与实际构建产物 sourcemap 路径的严格对应 —— 它不像前端调试那样容错。
