答案是ts类型加载、调试器类型、prettier解析器三处必须对齐：tsconfig.json需显式配置types和jsx为preserve；launch.json用pwa-node并校准sourcemappathoverrides；prettier须升级至3.0.0+且parser设为typescript。
能直接跑起来，但默认配置下 VSCode 无法识别 useSignal$、断点不生效、格式化破坏宏调用——问题不在插件没装，而在 TypeScript 类型加载、调试器类型、Prettier 解析器三处必须对齐。
TS 类型不识别 useSignal$？检查 tsconfig.json 的 types 和 jsx
VSCode 报 Cannot find name 'useSignal$'，不是插件失效，而是 TypeScript 编译器根本没加载 Qwik 类型声明。即使装了官方插件，tsc 和 TS 服务仍会跳过这些宏。
- 确认已安装
@builder.io/qwik@2.6+，且node_modules/@builder.io/qwik/tsconfig.json存在 -
tsconfig.json中compilerOptions.types必须显式包含"@builder.io/qwik"，不能靠 extends 继承覆盖 -
compilerOptions.jsx必须设为"preserve"（不是"react"或"react-jsx"） - 若使用
extends，需打开被继承文件（如tsconfig.base.json），确认它没清空types或重写jsx
SSR 断点不命中？改用 pwa-node 并校准 sourcemap 路径
Qwik 的 SSR 运行在 Node.js 进程里（比如 dist/server/entry.dev.ts），用 pwa-chrome 调试只会连浏览器，断点停在空白行或直接跳过函数体。
-
.vscode/launch.json中"type"必须是"pwa-node"，不是"pwa-chrome"或旧版"node" -
"program"指向 SSR 入口，常见路径为"dist/server/entry.dev.ts"（npm run dev时）或"src/entry.dev.ts"（npm run serve时） -
"sourceMapPathOverrides"必须匹配构建输出中的 sourcemap 前缀；Vite 默认生成webpack:///./src/，就得写成："webpack:///./src/*": "${webRoot}/src/*" - 启动调试前，确保已运行
npm run dev（或npm run build && npm run serve），否则调试器连不上进程
Prettier 格式化后 useServer$ 变形？升级并锁定 parser
老版本 Prettier（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 开发服务器靠 inotify 监听文件变更触发 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 - 禁用可能干扰文件监听的扩展：特别是 Remote - WSL、Docker、某些搜索增强类插件
- 确保项目根目录是 VSCode 工作区根（不是子文件夹），否则插件无法正确激活 Qwik 语言服务
- 重启 VSCode（不是重载窗口），因为 Qwik 插件的语言服务器需完整初始化
最常被忽略的是 tsconfig.json 里 jsx: "preserve" 和 launch.json 中 sourceMapPathOverrides 的路径映射——这两处一错，其余配置全白搭。
