zigfmt 不生效需依次检查：确保 zig 在 path 中（插件调用 zig fmt 而非 zigfmt）；在 settings.json 中配置 formatonsave、[zig] defaultformatter 和 formatonsavemode；确认 zig ≥ 0.11 版本。
zigfmt 不生效？先确认它是否真的在 PATH 里
VSCode 的 Zig 插件（如 ziglang.vscode-zig）默认调用系统 PATH 中的 zigfmt，但它**不自带 zigfmt，也不从 zig 编译器自动提取**。很多人装了 zig 命令，却没意识到 zigfmt 是 zig 二进制内置的子命令，不是独立可执行文件——所以直接搜 zigfmt 是否存在会失败。
- 在终端运行
zig fmt --help，能输出帮助说明 zig 支持格式化；但which zigfmt或where zigfmt通常找不到，这是正常现象 - VSCode 插件实际调用的是
zig fmt，不是zigfmt——注意这个命名差异，配置里写错就静默失效 - 如果
zig不在 PATH，插件会报错：Cannot find zig binary，而不是“zigfmt not found”
保存时自动格式化：关键在 settings.json 三处配置
仅靠插件默认设置，zig 文件保存时大概率不会触发格式化。必须手动补全语言专属配置，且顺序和布尔值敏感。
- 确保
"editor.formatOnSave": true全局开启（或至少在工作区启用） - 为
zig语言单独指定 formatter："[zig]": { "editor.defaultFormatter": "ziglang.vscode-zig" } - 禁用 fallback 行为：
"editor.formatOnSaveMode": "file"（避免设成modifications导致部分场景跳过）
漏掉任意一项，保存时都可能无反应。特别是 [zig] 这段语言覆盖配置，不加就走不到插件逻辑。
格式化卡住或报错 zig: command not found？检查 zig 路径和 shell 环境
VSCode 在 macOS/Linux 下有时读不到 shell 的 PATH（比如用 Launchpad 启动），导致能找到 zig 的终端，VSCode 却提示 command not found。
- 在 VSCode 内置终端中运行
which zig，结果为空？说明 VSCode 没继承 shell 环境 - 临时解决：用终端启动 VSCode，例如
code .；长期解决：在settings.json中显式指定 zig 路径："zig.zigPath": "/opt/homebrew/bin/zig" - Windows 用户注意：PowerShell 和 CMD 的 PATH 可能不同，插件默认按系统环境变量读，建议统一用 Windows Terminal + PowerShell 配置好再启动 VSCode
格式化效果和 zig 版本强相关，别用太旧的 zig
zig fmt 的行为随 zig 版本变化明显：0.11 开始支持 --align-enum-variants，0.12 默认启用更多换行规则。用 0.10 或更早版本，即使配置全对，格式结果也和文档示例不一致。
- 运行
zig version确认 ≥ 0.11（推荐 0.12+） - 插件本身不校验 zig 版本，低版本下不会报错，只会默默按旧规则格式化
- 如果团队协作，建议在
.vscode/settings.json里加注释说明所需 zig 版本，避免本地格式化结果和 CI 不一致
最常被忽略的一点：zigfmt 没有配置文件（如 .zigfmt），所有样式由 zig 版本内建规则决定，想改风格只能升级或降级 zig 本身。
