GTK OpenGL 上下文错误

Ghostty GTK 应用使用 OpenGL 进行渲染。要用 OpenGL 渲染，Ghostty 需要先从 GTK 获取一个 “OpenGL 上下文”。 它为我们提供了执行 OpenGL 命令所需的命名空间。

在极少数情况下，GTK 可能无法为 Ghostty 提供 OpenGL 上下文。发生这种情况时，Ghostty 无法渲染任何内容，只能 显示此错误。

这始终是环境问题。 OpenGL 上下文由 GTK 提供给 Ghostty，Ghostty 自身通常没有 直接解决它的办法。最常见的报错原因是库、驱动或操作 系统包版本的问题。本页将尽力提供一些定位问题的帮助。

如果你想尽快让 Ghostty 跑起来，可以尝试以下方法。

1. 安装二进制包。 如果你正在 从源码构建，请尝试改用二进制包。二进制包通常构建在 更可控的环境中，与特定发行版及其库兼容。

2. 检查你的 GPU 驱动。 GPU 驱动是导致 OpenGL 问题的常见原因。尝试更新或降级你的 GPU 驱动，尤其当你 正在使用专有驱动时。

3. 仅使用系统包从源码构建 Ghostty。 如果你正在使用 Nix 开发环境构建 Ghostty，请尝试 仅用系统包从源码构建。具体做法参见 从源码构建 的说明 （但请忽略“使用 Nix 构建”一节）。

Important

本节有意避免深入说明该问题的根本原因。如果你想更好地了解 根本原因，请阅读本节以下内容。

导致此错误的一个常见原因是库版本不匹配。GTK、 Mesa、libX11/libwayland 与内核之间的平衡十分脆弱。

导致此错误最常见的第一原因，是使用 Nix 开发环境 构建 Ghostty。 我们推荐在开发时使用该环境， 但它会固定这些库的多个版本，它们可能与 你的全局系统不兼容。修复方法：尝试仅使用系统依赖包构建 Ghostty，或直接使用系统包中的 Ghostty。 你可以按照 从源码构建 的说明 进行操作（但请忽略“使用 Nix 构建”一节）。

另一个常见原因是系统包过旧。 Linux 发行版往往会为你处理好这种脆弱的平衡，因此 请尝试更新整个系统（或者至少更新 上面提到的那几个包）。这通常会让系统恢复到 可以让 Ghostty 正常工作的一致状态。

检查你的 GPU 驱动。 尝试更新或降级你的 GPU 驱动。 我们遇到过很多因 GPU 驱动变更导致 GTK 中 OpenGL 失效的情况。

• Mesa 25.2.0 回归。 Ghostty 不打包 libwayland 客户端库，但使用 Nix 开发环境从源码构建 Ghostty 时 会使用与系统不同的 libwayland 客户端库。

• GTK4 + Nvidia + X11。 我们不清楚触发该问题的确切组合，但似乎在某些场景下， GTK4（Ghostty 所必需）、Nvidia 和 X11 的组合会引发此问题。 更换驱动版本或改用 Wayland 可以解决。