我终于找到了一种能让 VS Code 与 Zig 稳定协作的方法，在此分享我的配置，希望能帮其他人少走些弯路。

在找到可行方案之前，我一直被 Zig 版本不匹配的问题所困扰，有时 VS Code 甚至完全无法识别 Zig 的语义，只能回退到简陋的自动补全。

在多项目间管理不同的 Zig 版本

Zig 尚未发布稳定的 1.0 版本。如果你要开发 Zig 项目，就必须使用与该项目对应的 Zig 编译器版本。

如果你同时参与多个项目，就需要在同一系统上管理多个不同的 Zig 版本。

目前最流行的 Zig 版本管理工具似乎是 Zig Version Manager，不过我没有试过，不清楚它与 VS Code 的兼容性如何。

我个人是通过 Nix 开发环境来按项目管理 Zig 版本的，下面分享的就是这套方案。

问题：VS Code 找不到 ZLS

每当我打开一个 Zig 项目，VS Code 都会贴心地提示我启用 Zig Language Server，但当我点击确认后，却收到了这样一条错误信息：

问题在于，我通常是在启动 Nix 开发环境之前就打开了 VS Code，因此 Zig 的 VS Code 插件找不到本地的 Zig 编译器以及 Zig Language Server 的可执行文件 zls。

解决方案：使用 direnv 的 VS Code 扩展

更新（2025-02-14）：这里有一个更简单的方案，无需依赖 Nix。

起初，我想出了一个有点离奇的办法：让我的 Nix flake 在每次进入开发环境时自动重写 VS Code 的配置。这样 VS Code 就总能获取到最新的 Zig 和 ZLS 可执行文件路径。

后来，我读到一篇 fasterthanlime 的文章，才发现其实有更简单的解决办法。

有一个direnv VS Code 扩展可以轻松地将 Zig 的路径同步到 VS Code 中。而且，这也意味着该方案同样适用于通过 Remote SSH 使用 VS Code 的场景。

我的完整可用方案

下面我会详细解释我的方案，如果你不想看完整介绍、只想直接拿去用，我也提供了一个可直接复用的模板，见下文。

flake.nix

核心工作都由我的 Nix flake 来完成：

{
  description = "Zig development environment";

  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-24.11";
    flake-utils.url = "github:numtide/flake-utils";
    zig-overlay.url = "github:mitchellh/zig-overlay";
    # Keep in sync with zigVersion below.
    zls-overlay.url = "github:zigtools/zls/0.13.0";
  };

  outputs = {
    self,
    nixpkgs,
    flake-utils,
    ...
  } @ inputs:
    flake-utils.lib.eachSystem (builtins.attrNames inputs.zig-overlay.packages) (system: let
      pkgs = import nixpkgs {
        inherit system;
        overlays = [
          (final: prev: {
            zigpkgs = inputs.zig-overlay.packages.${prev.system};
          })
        ];
      };
      zigVersion = "0.13.0";
      zig = pkgs.zigpkgs.${zigVersion};
      zls = inputs.zls-overlay.packages.${system}.zls.overrideAttrs (old: {
        nativeBuildInputs = [zig];
      });
    in {
      devShells.default = pkgs.mkShell {
        packages = with pkgs; [
          zig
          zls
        ];

        shellHook = ''
          echo 'zls' "$(zls --version)"
          echo 'zig' "$(zig version)"
        '';
      };
    });
}

下载 flake.nix

这个 Nix flake 会创建一个包含 Zig 编译器和 Zig Language Server（ZLS）的开发环境。

我将其设置为 Zig 0.13.0，但你可以改成任意已发布的版本。如果想使用 Zig 的预发布开发版，只需将两处 0.13.0 都改成 master 即可。

我曾尝试了多种方法来消除 0.13.0 的重复定义，希望能只在一处定义版本号，但以我目前的 Nix 语言水平还没能找到实现方法。如果有人知道怎么做，欢迎告知。

.envrc

我的方案依赖 direnv，在进入项目目录时自动启动 Nix 开发环境。配置非常简单：

use_flake

.vscode/extensions.json

要让 VS Code 与 Zig 集成，我需要安装两个 VS Code 扩展：

{
  "recommendations": ["mkhl.direnv", "ziglang.vscode-zig"]
}

下载 extensions.json

第一个是官方的 Zig VS Code 扩展。

第二个不那么显眼的是 direnv VS Code 扩展，它能让 VS Code 识别到 Nix 开发环境中的路径。

.vscode/settings.json

最后，只需一项配置就能让 VS Code 启用 Zig Language Server：

{
  "zig.zls.enabled": "on"
}

下载 settings.json

复用我的模板

我创建了一个 Nix flake 模板，方便大家快速复现我的这套配置。

环境要求

• Nix（我使用的是 2.24.12）
  • 已启用 flakes
• direnv（我使用的是 2.35.0）
• VS Code（我使用的是 1.96.4）

Zig VS Code Nix flake 模板

我创建了一个 Nix flake 模板，其中包含了我这套 Zig + VS Code 的完整方案。你可以通过运行以下命令来使用它：

nix flake init \
  --template git+https://codeberg.org/mtlynch/zig-vscode-flake.git

执行 nix flake init 之后，运行 direnv allow，正常情况下会显示 zig 和 zls 已可用：

$ direnv allow
...
direnv: nix-direnv: Renewed cache
Alejandra 3.0.0
zls 0.13.0
zig 0.13.0

最后，在 VS Code 中打开“Extensions: Show Recommended Extensions”并安装推荐的扩展。

到这一步，你就可以运行 zig init 创建新项目了，此时 Zig 的 VS Code 扩展应该已经能正常工作。

切换 Zig 版本

我的 flake 默认设置为 Zig 0.13.0，也就是撰写本文时的最新版本。

如果你想使用其他已发布的版本，只需将 0.13.0 替换为目标版本号：

EXISTING_ZIG_VERSION='0.13.0' # Set to whatever the version in the flake.nix is.
NEW_ZIG_VERSION='0.12.0'      # Set to your desired Zig version.

如果想使用最前沿的预发布版本，请将版本号设为 master：

NEW_ZIG_VERSION='master'      # Set if you want bleeding edge Zig.

在 flake.nix 文件中更新 Zig 版本后，运行以下命令使改动生效：

sed \
  --in-place \
  "s/${EXISTING_ZIG_VERSION}/${NEW_ZIG_VERSION}/g" \
  flake.nix && \
  nix flake update zig zls-overlay && \
  nix develop

你可能需要重启（而不仅仅是重新加载）VS Code，改动才会生效。

更新：更简单的非 Nix 方案

一位 Zig VS Code 扩展的开发者回复了本文，表示其实仅通过该扩展本身就能管理 Zig 版本。

我之前并不知道 Zig VS Code 扩展本身就能管理 Zig 的安装，于是便尝试了一下。要通过 VS Code 扩展安装 Zig，请打开 VS Code 的命令面板并选择：

• Zig Setup: Install Zig

然后选择你想要的 Zig 版本，应该就能正常工作了。我当时还需要手动设置 settings.json并重新加载 VS Code 才能生效。

我个人还是喜欢用 Nix 开发环境，所以会继续沿用自己的方案，但如果你只想要一个简单的配置，让 Zig VS Code 扩展来管理 Zig 安装可能是更好的选择。