我在 VS Code 上的 Zig 設定
我終於找到了一個能讓 VS Code 與 Zig 穩定協作的解決方案，因此在此分享我的設定，希望能幫其他人省去一些麻煩。
正常運作的 VS Code Zig 擴充套件
在找到可行的解決方案之前，我一直遇到 Zig 版本不符的問題，或是 VS Code 完全無法辨識 Zig 的語意，只能退回陽春的自動完成。
跨專案管理多個 Zig 版本
Zig 尚未推出穩定的 1.0 正式版本。如果你正在開發以 Zig 撰寫的軟體，就必須使用與該專案相符的 Zig 編譯器版本。
如果你同時處理多個專案，就需要在同一套系統上切換不同 Zig 版本的方法。
目前管理 Zig 版本最熱門的方法似乎是 Zig Version Manager，我還沒試過，所以不確定它與 VS Code 的相容性如何。
我個人是透過 Nix development shells(Nix 開發殼層) 以專案為單位來管理 Zig 版本，因此以下分享的就是這個做法。
問題：VS Code 找不到 ZLS
當我開啟 Zig 專案時，VS Code 會貼心地提示我啟用 Zig Language Server(Zig 語言伺服器)，但當我按下同意後，卻出現了這個錯誤訊息：
ZLS 安裝失敗
問題在於，我是在啟動 Nix 開發環境之前就先開啟 VS Code，因此 Zig VS Code 外掛不知道該去哪裡找本地的 Zig 編譯器或 Zig Language Server 的執行檔 zls。
解法：使用 direnv VS Code 擴充套件
更新（2025-02-14）：有一個更簡單的解法，無需依賴 Nix。
一開始我想出一個有點瘋狂的解法：讓我的 Nix flake 在每次進入 dev shell 時自動重寫我的 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)"
'';
};
});
}這個 Nix flake 會建立一個包含 Zig 編譯器與 Zig Language Server（ZLS）的 dev shell。
我將它設為 Zig 0.13.0，但你可以改成任何已標記的發行版本。若想使用 Zig 的預發行開發版本，請將兩處的 0.13.0 都改為 master。
我試過好幾種方法想消除 0.13.0 的重複，讓它只需定義一次，但我的 Nix 語言能力還不足以想出辦法。如果有人有解法，煩請告訴我。
.envrc
我的解法仰賴 direnv 在我進入專案目錄時自動啟動 Nix dev shell。定義非常簡單：
use_flake.vscode/extensions.json
要讓 VS Code 與 Zig 整合，我需要兩個 VS Code 擴充套件：
{
"recommendations": ["mkhl.direnv", "ziglang.vscode-zig"]
}第一個是官方的 Zig VS Code 擴充套件。
第二個比較不明顯的是 direnv VS Code 擴充套件，它能讓 VS Code 存取我 Nix dev shell 內的路徑。
.vscode/settings.json
最後，我只需要一項設定來告訴 VS Code 使用 Zig Language Server：
{
"zig.zls.enabled": "on"
}複製我的範本
我建立了一個 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 正常搭配運作。
如果一切正常，你應該會在 src/main.zig 中看到語言覆疊效果，並且能夠跳至 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 dev shells，所以我會繼續使用自己的設定，但如果你只是想要簡單的設定，讓 Zig VS Code 擴充套件來管理 Zig 安裝可能會更好。