先确认 TypeScript 类型系统是否就位：需安装 @builder.io/qwik@2.6+，tsconfig.json 的 compilerOptions.types 必须包含 "@builder.io/qwik"，jsx 设为 "preserve"，且 extends 不得覆盖关键配置。
VSCode 识别不了 useSignal$ 等宏？先查 TypeScript 类型加载是否生效
这不是插件没装对，而是 TypeScript 编译器根本没读到 Qwik 的类型定义。即使装了官方 Qwik 插件（发布者必须是 QwikLabs），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 断点不命中？别用 pwa-chrome，改用 pwa-node 并配对 sourcemap 路径
Qwik 的 SSR 渲染由 Node.js 进程驱动（比如 qwik-city 的 serverless 入口），不能用浏览器调试类型直接连。断点停在空白行、跳过函数体，基本就是调试器类型和源码映射没对上。
- 在
.vscode/launch.json中，"type"必须是"pwa-node"，不是"pwa-chrome"或旧版"node" -
"program"指向 SSR 入口，常见路径是"dist/server/entry.dev.ts"或"src/entry.dev.ts"（取决于你跑的是npm run dev还是npm run serve） -
"sourceMapPathOverrides"必须匹配构建输出中的 sourcemap 前缀，例如 Vite 默认生成webpack:///./src/，就得写成："webpack:///./src/*": "${webRoot}/src/*" - 启动调试前，务必已运行
npm run dev或npm run build && npm run serve，否则调试器连不上进程
Prettier 格式化后 useServer$ 变形或报错？升级 + 锁定 parser
Qwik 宏依赖 AST 层面对 $ 符号的语义识别，老版本 Prettier（<3.0.0）会把 useServer$ 当普通标识符处理，格式化后可能破坏调用结构或注释位置，导致编译失败。
- 升级到
prettier@3.0.0+（Qwik v2.6+ 明确要求） - 在
.prettierrc中显式设置"parser": "typescript"（禁用babel或flow） - VSCode 设置中关闭全局
editor.formatOnSave对typescriptreact的默认绑定，改用工作区配置："[typescriptreact]": { "editor.formatOnSave": true } - 临时调试可用
// prettier-ignore，但不可长期依赖
热更新（HMR）失效、“断点只生效一次”？检查 inotify 限制和插件干扰
Qwik 开发服务器靠文件系统事件触发 HMR，而 VSCode（尤其 WSL 用户）某些扩展（如 Remote - WSL + Docker）会劫持或耗尽 inotify 句柄，导致后续变更完全不响应。
- Linux/WSL 下执行
cat /proc/sys/fs/inotify/max_user_watches，若低于524288，需提升：echo 524288 | sudo tee /proc/sys/fs/inotify/max_user_watches - 禁用非必要扩展，特别是涉及文件监听、远程容器、Docker 集成的插件
- 确保项目根目录是 VSCode 工作区（不是子文件夹），否则插件可能无法正确激活 Qwik 语言服务器
- 重启 VSCode 时务必“完全退出”，仅“重载窗口”不足以重启 Language Server
Qwik 的类型系统、调试模式、格式化链和文件监听是四个相互耦合的环节，任一环松动都会导致开发流中断。最容易被忽略的是 tsconfig.json 中 types 和 jsx 的显式声明——它们不继承、不默认、不推测，必须亲手写进去。
