從原始碼建置 Ghostty

自行從原始碼建置 Ghostty。僅建議給無法取得二進位或套件的人， 以及想為 Ghostty 做貢獻的開發者。

Tip

不建議大多數使用者從原始碼建置 Ghostty。 如果你可以取得預先建置的二進位或套件，應當改用後者。請查看二進位與套件頁面，看你的平台是否有預先建置的二進位或套件。

如果你打算開發或打包 Ghostty，也請分別查看我們的「開發 Ghostty」與「打包 Ghostty」文件。本頁更面向為了個人使用而想要或必須從原始碼建置 Ghostty 的終端使用者。

要建置 Ghostty，你需要先安裝 Zig。

Important

由於 Zig 仍是一門快速演進的語言，每個 Ghostty 版本只保證能用一個特定版本的 Zig 建置。更舊或更新的 Zig 編譯器都可能無法建置 Ghostty。 如果你的套件管理器維護的 Zig 版本與 Ghostty 所要求的不同，可以使用 Zig 下載頁上的靜態二進位發行版的 Zig 編譯器。

每個 Ghostty 版本所需的 Zig 版本如下：

Ghostty 版本Zig 版本
1.0.x0.13.0
1.1.x0.13.0
1.2.x0.14.1
1.3.x0.15.2
tip0.15.2

官方建置環境由 Nix定義。建置 Ghostty 不需要使用 Nix，但 Nix 環境是執行 CI 測試與建置發行工件的環境，因此它是建置 Ghostty 最可靠的方式。如何設定 Nix 環境見用 Nix 建置一節。

依平台不同，你還可能需要安裝其他相依套件來建置 Ghostty。Linux 見 Linux，macOS 見 macOS。

取得原始碼

首先下載 Ghostty 的原始碼 tarball。

Warning

雖然你可以透過 checkout Git 儲存庫從原始碼編譯 Ghostty，但這不建議給除 Ghostty 開發者與貢獻者之外的任何人。這是因為原始碼 tarball 包含各種預先處理的檔案，使 Ghostty 編譯所需的相依套件少得多。

如果你打算為 Ghostty 做貢獻，請查閱「開發 Ghostty」文件了解如何在開發環境中建置 Ghostty。雖然多數步驟完全相同，但為簡單起見，從這裡開始我們都假定基於原始碼 tarball 的建置。

對穩定發行版而言，原始碼 tarball 及其隨附的校驗和可在 release.files.ghostty.org 透過以下路徑找到，其中 VERSION 是不帶前綴的版本號，如 1.0.0：

https://release.files.ghostty.org/VERSION/ghostty-VERSION.tar.gz
https://release.files.ghostty.org/VERSION/ghostty-VERSION.tar.gz.minisig

簽署檔案由 minisign用以下公鑰簽署：

RWQlAjJC23149WL2sEpT/l0QKy7hMIFhYdQOFy0Z7z7PbneUgvlsnYcV

對開發（"tip"）版本而言，原始碼 tarball 可透過 GitHub 上的 tip release取得，名為 ghostty-source.tar.gz。

Important

原始碼 tarball 與 GitHub 自動產生的標為 "Source code (zip)" 或 "Source code (tar.gz)" 的 tarball 不同：後者不含任何預先處理的檔案，與 Git checkout 無差別。

解壓發行 tarball，然後進入解包後的原始碼資料夾：

tar -xf ghostty-VERSION.tar.gz
cd ghostty-VERSION/

# Or when using a tip source tarball:
# (REVISION is the commit SHA of the latest commit)

tar -xf ghostty-source.tar.gz
cd ghostty-VERSION-main+REVISION/

安裝好 Zig 與必要相依套件後，即可用 zig build 建置二進位：

zig build -Doptimize=ReleaseFast

在 Linux 上，這會在 zig-out/bin/ghostty產生就緒可用的二進位。在 macOS 上，這會在 zig-out/Ghostty.app產生 app bundle。

Tip

對 Linux 使用者：要安裝到系統層級或你的使用者帳戶，見安裝目錄。

Tip

要建置除錯版本，省略 -Doptimize=ReleaseFast 旗標。除錯建置極慢（比 release 建置慢 100 倍以上），所以只用於開發。

Linux

相依套件

在 Linux 上，建置 Ghostty 之前需要安裝 Ghostty 相依套件的前置檔套件。原始碼建置只需要少量相依套件，因為 Ghostty 預設會把其餘一切都以靜態方式建置。

必備相依套件：

  • gtk4
  • libadwaita
  • gtk4-layer-shell
  • pkg-config 或 pkgconf
  • gettext

Important

如果用的是 Git checkout，也需安裝這些相依套件：

Tip

如果你的發行版尚未打包 gtk4-layer-shell（如 Ubuntu 24.04、Debian 12、Linux Mint 22.1、OpenSUSE 等），你需要允許 Ghostty 從原始碼編譯 gtk4-layer-shell，方法是向 zig build新增旗標 -fno-sys=gtk4-layer-shell。

Alpine 

doas apk add \
  gtk4.0-dev \
  libadwaita-dev \
  pkgconf \
  ncurses \
  gettext

Arch Linux 

sudo pacman -S \
  gtk4 \
  gtk4-layer-shell \
  pkgconf \
  libadwaita \
  gettext

Debian 與 Ubuntu 

sudo apt install \
  libgtk-4-dev \
  libgtk4-layer-shell-dev \
  libadwaita-1-dev \
  gettext \
  libxml2-utils

在 Debian unstable/testing 上，建置時還需要 gcc-multilib 套件。

Fedora

在 Fedora 變體上，使用

sudo dnf install \
  gtk4-devel \
  gtk4-layer-shell-devel \
  zig \
  libadwaita-devel \
  gettext

在 Fedora Atomic 變體上，使用

rpm-ostree install \
  gtk4-devel \
  gtk4-layer-shell-devel \
  zig \
  libadwaita-devel \
  gettext

Gentoo 

emerge -av \
  libadwaita \
  gtk \
  blueprint-compiler \
  gettext

openSUSE Tumbleweed 

sudo zypper install \
  gtk4-devel \
  libadwaita-devel \
  pkgconf \
  ncurses-devel \
  zig \
  gettext \
  gtk4-layer-shell-devel

openSUSE Leap 

sudo zypper install \
  gtk4-devel \
  libadwaita-devel \
  pkgconf \
  ncurses-devel \
  zig \
  gettext

Solus 

sudo eopkg install \
  libgtk-4-devel \
  libadwaita-devel \
  pkgconf \
  zig \
  gettext

Void 

sudo xbps-install \
  gtk4-devel \
  gtk4-layer-shell-devel \
  libadwaita-devel \
  pkg-config \
  zig \
  gettext

安裝目錄

用 -p（prefix）旗標配合 zig build，把 Ghostty 安裝到目標目錄。這會設定正確的 FHS 目錄結構，確保 shell 整合、圖示、GTK 快捷鍵等功能都正常運作。

對本地、無特權的安裝，我們推薦 $HOME/.local：

zig build -p $HOME/.local -Doptimize=ReleaseFast

在典型的 Freedesktop 相容桌面環境（如 GNOME、KDE）下，這會讓 Ghostty 作為應用程式出現在你的應用程式啟動器裡。如果沒有立刻看到，可能需要登出再登入，甚至重新啟動。

如果 Ghostty 透過應用程式啟動器中的應用程式圖示啟動失敗，請確保 ~/.local/bin 位於你 系統 的 PATH上。桌面環境本身必須在 PATH中包含該路徑。針對你的具體桌面環境與發行版搜尋一下吧。

如果你用 -fno-sys=gtk4-layer-shell 旗標建置了 Ghostty，可能還需要把 LD_LIBRARY_PATH 環境變數設為 $HOME/.local/lib。為避免從桌面環境啟動時污染全域的 LD_LIBRARY_PATH，可以直接用 patchelf為已安裝的 Ghostty elf 打修補：

patchelf --set-rpath '$ORIGIN/../lib' $HOME/.local/bin/ghostty

對系統層級安裝，我們推薦 /usr（很可能需要 sudo）：

zig build -p /usr -Doptimize=ReleaseFast

用 Nix 建置

Nix 建置環境可以像任何其他 Nix dev shell那樣，透過 nix develop 命令進入（若未啟用 nix-command 實驗特性，則用 nix-shell）。

如果你使用 nix-direnv，Ghostty 提供了一個 .envrc 檔案，執行 direnv allow即可 source 它。這讓你進入和離開 Ghostty 儲存庫時無縫地進入和離開 Ghostty 開發環境。Direnv 非必需。

設定好 Nix 環境後，可以執行與其他發行版相同的 zig build，或者也可以用 Nix 建置套件：

nix build .#ghostty

之後二進位位於 ./result/bin/ghostty下。

用 Nix 建置應得到與用 Zig 建置相同的結果，但具有更高的可重現性保證，確保 Ghostty 的每個部件都能可靠建置。

macOS

相依套件

Xcode

要建置 macOS 應用程式，必須在裝有 Xcode、且活動開發者目錄指向它的 macOS 機器上建置。如果你不能確定是否如此，檢查 xcode-select --print-path 的輸出：

xcode-select --print-path
/Library/Developer/CommandLineTools        # <-- BAD

sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
xcode-select --print-path
/Applications/Xcode.app/Contents/Developer # <-- GOOD

如果在安裝 Xcode 之後 才安裝 Xcode Command Line Tools，可能發生上述情況。

接下来，確保已安裝 macOS SDK、iOS SDK 與 Metal Toolchain（在 Xcode → Settings → Components 內）。

其他相依套件

Ghostty 還需要安裝一些額外的函式庫相依套件。安裝方式隨意，但最簡單的是透過 Homebrew：

brew install gettext

Note

如果你使用 Nix 開發環境，這些相依套件會自動處理，無需手動安裝。

Mac .app 

zig build -Doptimize=ReleaseFast

這會把應用程式輸出到 zig-out/Ghostty.app。

建立的應用程式使用 "ReleaseLocal" Xcode 建置配置。該配置專用於本地 release 建置，並停用一些安全特性（如 "Library Validation"），以便在沒有程式碼簽署身分等情況下更容易執行。這些建置不用於散布。如果你想要帶全部安全特性的 release 建置，使用官方二進位建置。


Edit on GitHub