zig命令必须全局可用，否则vscode所有zig功能静默失效；zls需与zig版本严格匹配并配置绝对路径；zig fmt须在settings.json中显式绑定为默认格式化器。
zig 命令必须全局可用，否则 VSCode 里所有 Zig 功能（补全、跳转、格式化、调试）都会静默失效——不是插件坏了，是它根本连不上编译器。
为什么 zig version 在终端能跑，VSCode 里却报错？
VSCode 启动方式决定它能否读取你的 shell 环境变量：
- 从 Dock 或桌面图标启动 → 不加载 ~/.zshrc 或 ~/.bash_profile，PATH 里没有 zig
- 从终端执行 code . 启动 → 继承当前 shell 环境，zig version 才真有效
- Windows 用户若用 Scoop 安装，确认 scoop install main/zig 后，zig.exe 已在 Scoop 的 shims 目录且该目录已进系统 PATH
- macOS/Linux 用户改完 ~/.zshrc 后，必须运行 source ~/.zshrc，再用终端启动 VSCode
ZLS 路径配不对，补全和跳转就全灰掉
Zig Language Server（zls）不是插件自带的，也不自动下载；它必须和当前 zig 版本严格匹配，否则 LSP 连接失败。
常见错误现象：Go to Definition 灰掉、Ctrl+Space 没反应、状态栏显示 ZLS: not running
实操建议：
- 推荐用 Homebrew 安装（macOS）：brew install zls，然后查路径：brew --prefix zls → 典型输出是 /opt/homebrew/opt/zls/bin/zls
- Windows 可用 scoop install zls（需先 scoop bucket add extras）
- 配置时务必写**绝对路径**，"zig.zlsPath": "/opt/homebrew/opt/zls/bin/zls"，别写 ~/ 或环境变量
- VSCode 设置里搜 zig.zlsPath，直接在 settings.json 里加这一行，保存后打开任意 .zig 文件，看输出面板里 Zig Language Server 是否显示 Connected
zig fmt 不生效？默认根本没绑定
VSCode 不会自动把 zig fmt 当成格式化器，哪怕插件已装、zig 可用。
实操建议：
- 在项目根目录的 .vscode/settings.json 中显式声明：
{
"[zig]": {
"editor.defaultFormatter": "ziglang.zig",
"editor.formatOnSave": true
}
}
- 如果
zig 不在 PATH，还需加 "zig.executablePath": "/path/to/zig"- 格式化时报
command 'zig.fmt' not found？说明插件找不到 zig —— 回头验证终端里 zig version 和 VSCode 终端里是否一致- 别依赖“右键 → 格式化文档”弹窗选，那只是临时 fallback；必须靠上面 JSON 配置才稳定触发
调试必须对二进制下断点，不能调 zig test
Zig 没有原生调试器，VSCode 实际是用 CodeLLDB（macOS/Linux）或 cppdbg（Windows）去 attach 已编译的带 DWARF 符号的可执行文件。
常见错误现象：zig test 命令反复重启、断点灰色、变量面板空
实操建议：
- 先装扩展 CodeLLDB（macOS/Linux）或 C/C++（Windows）
- 用 zig build test -Doptimize=Debug 生成测试二进制（如 ./zig-out/test）
- launch.json 中 "program" 必须指向这个二进制路径，不能写 "zig test src/main.zig"
- Windows 上若报 spawn lldb ENOENT，说明没装 C/C++ 扩展，或没配 "miDebuggerPath" 指向 lldb 或 gdb
ZLS 版本错配、zig 路径未被 VSCode 继承、zig fmt 未显式绑定——这三处最容易漏，且错误表现都很“安静”，不报红但功能全失。
