Zig 在 VSCode 跑不起来主因是 zig 二进制、zls 路径、格式化配置未对齐：zig.zlsPath 不支持波浪线需写绝对路径；zig 必须在 VSCode 终端中能执行 zig version；zls 版本须与 zig 严格一致；保存自动格式化需手动配置 settings.json 中 "[zig]" 的 defaultFormatter 和 formatOnSave。
Zig 在 VSCode 里跑不起来，八成不是插件问题，而是 zig 二进制、zls 路径、格式化配置这三处没对齐——尤其 macOS 上 zig.zlsPath 写成 ~/.zigpkg/bin/zls 这种带波浪线的路径，VSCode 根本不展开，直接静默失败。
确认 zig 可执行文件已真正可用
VSCode 的 Zig 插件（ziglang.zig）启动时会尝试调用 zig 命令获取版本、启动 ZLS、调用 zig fmt。它不关心你是不是从官网下载解压的，只认 PATH 里能不能 zig version 成功。
- 在 VSCode 内置终端里运行
zig version，必须返回有效版本号（如0.14.1），否则插件连基础语言服务都起不来 - 如果终端里能运行但 VSCode 里报 “zig not found”，大概率是 shell 配置没被继承：检查 VSCode 是否以图形界面方式启动（比如从 Dock 点开），此时它不读
~/.zshrc；临时解决是用终端执行code .启动 - macOS 上用 Homebrew 安装的 zig，路径通常是
/opt/homebrew/bin/zig（Apple Silicon）或/usr/local/bin/zig（Intel），别写错
zls 路径必须显式指定且绝对完整
Zig 官方插件默认不自动发现 zls，也不会 fallback 到 zig 自带的简易 LSP。ZLS 是独立进程，版本必须和当前 zig 二进制严格一致，否则补全失效、跳转报错、错误标记延迟甚至不出现。
- Homebrew 用户：运行
brew install zls后，用brew --prefix zls查真实路径，例如/opt/homebrew/opt/zls/bin/zls，然后填进settings.json的"zig.zlsPath" - zigpkg 用户：安装后路径在
$HOME/.zigpkg/bin/zls，但 VSCode 不解析~，必须写成/Users/yourname/.zigpkg/bin/zls - 手动构建用户：构建完是
zls/zig-out/bin/zls，复制到固定位置再引用，别直接指向构建目录（每次zig build都可能变） - 验证是否生效：打开 .zig 文件后，看 VSCode 底部状态栏有没有 “ZLS Connected”，或者打开 Output 面板，选 “Zig Language Server” 查日志
保存时自动格式化要绕过两个坑
zig fmt 是唯一受认可的格式化工具，但 VSCode 默认不会把它设为 [zig] 语言的 formatter，而且容易因路径缺失导致“格式化失败”却不报错。
- 先确保
"zig.zigPath"已在settings.json中正确设置（例如"zig.zigPath": "/opt/homebrew/bin/zig"），否则zig fmt根本调不动 - 不要只靠 GUI 设置勾选 “Format on Save”，必须手动编辑
settings.json，加入："[zig]": { "editor.formatOnSave": true, "editor.defaultFormatter": "ziglang.zig" } - 如果保存后没反应，打开命令面板（
Cmd+Shift+P），输入 “Format Document”，看是否弹出 “Zig Formatter” 选项；没有就说明插件没识别到zig可执行文件
调试需手动配 launch.json + build 任务
Zig 没有原生 VSCode 调试器集成，得靠 CodeLLDB + DWARF 符号 + 正确的可执行路径。常见问题是断点不命中、变量显示 <optimized out>，本质是构建时没加调试信息或路径不对。
- 安装
CodeLLDB扩展（vadimcn.vscode-lldb），别用 C/C++ 扩展，它对 Zig 支持不稳定 -
tasks.json中的构建任务必须含-Doptimize=Debug，例如："args": ["build", "-Doptimize=Debug"]
，否则生成的二进制没有调试符号 -
launch.json的"program"字段必须指向实际生成的可执行文件，典型路径是${workspaceFolder}/zig-out/bin/your_project_name，不是源文件或build.zig - 首次调试前，务必先运行一次构建任务（
Cmd+Shift+B），确保zig-out/bin/下已有文件，否则调试器启动就失败
最常被忽略的是 zls 和 zig 编译器的版本耦合性——哪怕只是小版本号差一个（比如 zig 0.14.1 和 zls 基于 0.14.0 构建），LSP 就会拒绝连接，而 VSCode 很少明确提示这点，只表现为“没补全、没错误提示”。每次升级 zig，zls 必须重装或重建。
