需先编译并配置zls路径，再安装Zig Language Support插件；确保VSCode打开项目根目录且含build.zig或zig.mod；zig fmt需正确设置zigPath和formatArgs；调试应针对已编译二进制而非zig test命令。
怎么装 ZLS 插件才能让 Zig 代码有补全和跳转
VSCode 本身不支持 Zig，必须靠 zls（Zig Language Server）提供语义能力。只装官方 Zig 编译器没用，补全、悬停、跳转全依赖 zls 运行并被 VSCode 正确连接。
实操建议：
- 先用
zig build编译zls：从 zls GitHub 仓库 克隆后，在项目根目录执行zig build -Drelease-safe，生成的可执行文件在zls（Linux/macOS）或zls.exe（Windows） - 把编译好的
zls放进$PATH，或者在 VSCode 设置里显式指定路径："zls.path": "/path/to/zls" - VSCode 插件只装一个：
Zig Language Support（作者是mitchellh），别装其他名字相似的；它不带zls，也不自动下载，纯靠你配好路径才启动 - 常见错误现象：
Go to Definition灰掉、Ctrl+Space没反应、状态栏显示ZLS: not running—— 基本都是zls没启动或路径错
zig.test() 不断重启调试器？Zig 调试配置要点
Zig 自身没有原生调试器集成，VSCode 用的是 lldb（macOS/Linux）或 vscode-cpptools 提供的 cppdbg（Windows），所以调试行为本质是“用 C++ 调试器跑 Zig 二进制”。这导致 zig test 这类子命令容易卡死或反复重启。
实操建议：
- 不要直接调试
zig test命令；改用zig build test生成可执行测试文件，再对那个 binary 下断点 -
launch.json中program必须指向已编译的二进制（如./zig-out/test），不能写"program": "zig test src/main.zig" - 确保
zig build输出带调试信息：zig build -Doptimize=Debug -Dtarget=native，否则断点无效 - Windows 上若报
Unable to start debugging. Exception: Error: spawn lldb ENOENT，说明没装vscode-cpptools或没配miDebuggerPath
为什么 zig fmt 不生效？格式化配置陷阱
zig fmt 是 Zig 官方唯一认可的格式化工具，VSCode 的格式化功能必须调用它，而不是用任何第三方插件模拟。但默认情况下，VSCode 不知道该用哪个命令、在哪找 zig、是否要传参数。
实操建议：
- 在工作区根目录加
.vscode/settings.json，写死路径和参数："editor.formatOnSave": true, "editor.defaultFormatter": "mitchellh.zig", "[zig]": { "editor.formatOnSave": true, "editor.formatOnType": false }, "zig.zigPath": "/usr/local/bin/zig", "zig.formatArgs": ["--stdin-file-path"] -
"zig.formatArgs": ["--stdin-file-path"]是关键：VSCode 传内容给zig fmt时会附带当前文件路径，不加这个参数会导致格式化后光标乱跳甚至内容丢失 - 如果用
homebrew（macOS）或apt（Linux）装的 Zig，zig.zigPath可能是/opt/homebrew/bin/zig或/usr/bin/zig，务必which zig确认 - 常见错误现象：
Format Document按了没反应、保存后缩进没变、报错Failed to format document. Cannot read property 'trim' of undefined—— 多半是zigPath错或formatArgs缺失
zls 启动失败 / 报错 “failed to resolve root package” 怎么办
zls 启动时会扫描当前打开的文件夹，试图找到 build.zig 或 zig.mod 来确定项目根。找不到就报这个错，然后整个语言服务瘫痪 —— 补全、诊断、重命名全部失效。
实操建议：
- 确保 VSCode 打开的是**整个 Zig 项目根目录**，不是某个子文件夹。比如项目结构是
myapp/src/main.zig，就要用 VSCode 打开myapp/，而不是myapp/src/ - 项目根下至少要有
build.zig（哪怕空文件）或zig.mod（Zig 0.12+ 的模块定义），否则zls认不出这是 Zig 项目 - 如果用
zig init-exe初始化过，但删了build.zig，手动补一个最简版：const std = @import("std"); pub fn build(b: *std.build.Builder) void { _ = b; } - Windows 上路径含中文或空格时，
zls可能静默崩溃；换到C:\dev\myproject这类纯英文无空格路径再试
zls 的日志不输出到 VSCode 控制台，默认静默。真要查问题，得在终端手动跑 zls --stdio，看它读到什么路径、卡在哪一步 —— 这个细节很多人忽略，结果花半天调配置，其实只是打开的文件夹不对。
