zig命令必须全局可用且vscode需继承shell环境变量，否则所有功能静默失效；zls路径须绝对且版本严格匹配zig；zig fmt和调试均需手动配置settings.json并指向已编译带调试信息的二进制。

zig 命令没进 VSCode 的 PATH，所有功能都会静默失效——不是插件坏了，是它根本连不上编译器。

zig version 在终端能跑，VSCode 里却报 “command not found”

VSCode 图形界面启动（比如从 Dock 点开）时，不加载 ~/.zshrc 或 ~/.bash_profile，PATH 里压根没有 zig。这不是 Zig 插件的问题，是环境没继承。

• 临时解决：在终端里执行 code . 启动 VSCode，它会完整继承当前 shell 环境
• macOS/Linux 用户改完 ~/.zshrc 后，必须运行 source ~/.zshrc 才生效；光保存文件没用
• Homebrew 安装的 zig 路径通常是 /opt/homebrew/bin/zig（Apple Silicon）或 /usr/local/bin/zig（Intel），别写错
• Windows 用 Scoop 安装后，确认 scoop install main/zig 成功，且 scoop shim list 能看到 zig —— shims 目录必须在系统 PATH 中

Go to Definition 灰掉、Ctrl+Space 没反应，ZLS 状态栏显示 “not running”

ZLS 不是插件自带的，也不自动下载；它必须和当前 zig 版本严格匹配，否则 LSP 连接失败。路径写错、版本不配、用波浪线 ~/ 都会导致静默失败。

VSCode

避免常见的 VSCode 错误——设置冲突、调试器配置和扩展冲突。

下载

• Homebrew 用户：brew install zls 后，用 brew --prefix zls 查真实路径（如 /opt/homebrew/opt/zls/bin/zls），填进 settings.json 的 "zig.zlsPath"
• zigpkg 用户：zigpkg install zls 后路径是 $HOME/.zigpkg/bin/zls，但 VSCode 不解析 ~，必须写成绝对路径，例如 /Users/yourname/.zigpkg/bin/zls
• 手动构建用户：构建命令是 zig build -Drelease-safe，输出在 zls/zig-out/bin/zls；别直接填这个相对路径，复制到固定位置再引用
• 验证方式：打开任意 .zig 文件，看 Output 面板 → “Zig Language Server” 是否显示 Connected

保存代码不自动格式化，右键“格式文档”提示 “未配置格式化程序”

VSCode 默认根本不知道 zig fmt 是什么，也不会自动把它设为 [zig] 语言的 formatter。靠插件安装或右键选一次，都不算数。

• 必须在项目根目录的 .vscode/settings.json 里显式声明：

  {
    "[zig]": {
      "editor.defaultFormatter": "ziglang.zig",
      "editor.formatOnSave": true
    }
  }

• 如果 zig 不在系统 PATH，还得加 "zig.zigPath": "/path/to/zig"
• 格式化时报 command 'zig.fmt' not found？说明插件找不到 zig —— 回头验证 VSCode 内置终端里 zig version 是否真能返回版本号
• 别依赖右键菜单临时选 formatter，那只是 fallback，不持久也不触发 formatOnSave

调试时断点灰掉、变量为空、zig test 反复重启

Zig 没有原生调试器，VSCode 实际是用 CodeLLDB（macOS/Linux）或 cppdbg（Windows）去 attach 已编译的二进制，且必须带 DWARF 调试信息。直接调试 zig test 命令本身是无效路径。

• 不要写 "program": "zig test src/main.zig" —— launch.json 的 program 字段必须指向已生成的可执行文件，比如 ./zig-out/test
• 确保构建时加调试标志：zig build test -Doptimize=Debug -Dtarget=native，否则断点无法命中
• macOS 上若调试器启动失败，检查是否装了 CodeLLDB 扩展；Windows 上报 spawn lldb ENOENT，说明 vscode-cpptools 没装或 miDebuggerPath 没配
• zig test 子进程模型与调试器不兼容，这是设计使然，不是配置错误

最常被忽略的是：VSCode 启动方式决定 PATH 是否可用，而 zig.zlsPath 里的波浪线 ~ 在 JSON 配置中完全不展开——这两处一错，补全、跳转、格式化、调试全部归零，但界面不会报错，只会安静地不工作。