我终于找到了一个能让 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 正常协作。

更改 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.

若想使用最前沿的 Zig 预发布版本，请将版本设为 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 安装可能是更好的选择。