我終於找到一個能讓 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 的安裝可能會更適合你。