macOS Zig开发环境搭建需完成Zig编译器安装、ZLS配置及VSCode扩展启用：可选Homebrew或手动下载二进制安装Zig；必须匹配版本安装ZLS（通过Homebrew或zigpkg）；最后安装Zig官方扩展并配置zlsPath与格式化选项。

如果您希望在 macOS 系统上启用 Zig 编程语言开发能力，但尚未完成编译器安装与编辑器协同配置，则可能是由于 Zig 二进制未加入系统路径、Zig Language Server（ZLS）未就位或 VSCode 扩展未正确绑定所致。以下是完成 macOS Zig 开发环境搭建的多种可行路径：

一、使用 Homebrew 安装 Zig 编译器

Homebrew 是 macOS 上最主流的包管理器，安装 Zig 可实现版本可控、升级便捷、依赖自动解析。该方式适用于偏好统一工具链管理且已安装 Homebrew 的用户。

1、在终端中执行 brew update 更新本地公式库。

2、运行 brew install zig 下载并安装最新稳定版 Zig 编译器（当前为 0.14.1）。

3、验证安装：执行 zig version，输出应类似 0.14.1。

4、确认 Zig 可执行文件路径：执行 which zig，典型返回为 /opt/homebrew/bin/zig（Apple Silicon）或 /usr/local/bin/zig（Intel）。

二、手动下载预编译二进制安装

此方式绕过包管理器，直接获取官方构建的跨平台二进制，适合需指定架构、离线部署或验证签名完整性的场景。Zig 官方提供 macOS ARM64 和 x86_64 两种架构压缩包。

1、访问 https://ziglang.org/download/，定位 macOS 区域，选择对应芯片架构的 .tar.xz 文件（如 zig-macos-aarch64-0.14.1.tar.xz）。

2、在终端中执行 mkdir -p ~/zig && cd ~/zig 创建安装目录。

3、使用 curl -L [下载链接] | tar -xJ 解压至当前目录（或先下载再用 tar -xvf）。

4、将解压后生成的 zig 可执行文件所在目录（如 ~/zig/zig-macos-aarch64-0.14.1）添加至 PATH：编辑 ~/.zshrc，追加 export PATH="$HOME/zig/zig-macos-aarch64-0.14.1:$PATH"。

5、执行 source ~/.zshrc 并再次运行 zig version 验证。

三、安装并配置 Zig Language Server（ZLS）

ZLS 是 Zig 在 VSCode 中实现智能提示、跳转定义、错误实时标记等核心语言功能的后台服务。必须与已安装的 Zig 编译器版本严格匹配，否则 LSP 通信会失败。

1、通过 Homebrew 安装 ZLS：执行 brew install zls，安装完成后运行 brew --prefix zls 获取其二进制路径（如 /opt/homebrew/opt/zls/bin/zls）。

2、打开 VSCode 设置（Cmd + ,），切换至“工作区”标签页，在搜索框中输入 zig.zlsPath，点击“在 settings.json 中编辑”。

3、在 JSON 中添加键值对："zig.zlsPath": "/opt/homebrew/opt/zls/bin/zls"（请替换为上一步实际路径）。

4、重启 VSCode，新建一个 main.zig 文件，观察输出面板中 Zig Language Server 是否显示 Connected。

四、使用 zigpkg 安装 ZLS（替代方案）

zigpkg 是 Zig 社区维护的轻量级包管理工具，支持一键拉取预编译 ZLS 二进制，避免从源码构建耗时，适用于希望快速启用语言服务的用户。

1、安装 zigpkg：执行 curl -sSf https://raw.githubusercontent.com/zigtools/zigpkg/main/install.sh | sh。

2、安装 ZLS：运行 zigpkg install zls，二进制默认置于 ~/.zigpkg/bin/zls。

3、将该路径加入 shell：向 ~/.zshrc 追加 export PATH="$HOME/.zigpkg/bin:$PATH"，并执行 source ~/.zshrc。

4、在 VSCode 的 settings.json 中配置 "zig.zlsPath": "/Users/yourname/.zigpkg/bin/zls"（注意：必须使用绝对路径，不可保留 ~ 符号）。

五、启用 VSCode Zig 官方扩展与格式化

VSCode 的 Zig 支持由官方扩展提供，它封装了 ZLS 连接逻辑、zig fmt 格式化器调用及测试运行器。必须启用并正确关联本地 Zig 工具链，否则仅呈现基础语法高亮。

1、在 VSCode 扩展市场中搜索 Zig，安装发布者为 Zig Team 的扩展（ID: ziglang.zig）。

2、安装后重启 VSCode，新建 hello.zig，确认右下角状态栏显示 Zig 语言模式。

3、按下 Cmd + Shift + P，输入 Preferences: Configure Language Specific Settings，选择 zig，在弹出的 JSON 中添加："editor.formatOnSave": true 与 "editor.defaultFormatter": "ziglang.zig"。

4、保存文件，观察是否自动触发 zig fmt 并重排代码缩进与空格。