Ghostty 终端配置完全指南

notes › tutorial
, ,

版本: 基于 Ghostty 1.2.0+ 官方文档整理
更新时间: 2026年2月

📋 目录

  1. 配置文件位置
  2. 基础配置
  3. 外观主题
  4. 字体设置
  5. 窗口行为
  6. 键盘快捷键
  7. 高级功能
  8. macOS 专属配置
  9. Linux/GTK 专属配置
  10. 实用配置示例

配置文件位置

macOS

1
~/Library/Application Support/com.mitchellh.ghostty/config

Linux

1
2
3
$XDG_CONFIG_HOME/ghostty/config
# 或
~/.config/ghostty/config

配置语法说明

  • 使用 key = value 格式
  • # 开头为注释
  • 布尔值：true / false
  • 颜色格式：#RRGGBB 或 X11 颜色名
  • 支持多行配置相同选项实现 fallback

基础配置

Shell 设置

1
2
3
4
5
6
7
8
9
10
11
12
13
# 指定启动的 shell（默认自动检测）
command = /bin/zsh

# 仅首次启动时使用的命令
initial-command = /opt/homebrew/bin/fish

# 工作目录继承设置
window-inherit-working-directory = true
working-directory = inherit  # 可选: home, inherit, 或绝对路径

# 环境变量
env = EDITOR=nvim
env = LANG=zh_CN.UTF-8

滚动回滚

1
2
3
4
5
# 回滚缓冲区大小（字节），默认无限
scrollback-limit = 10000000

# 是否自动滚动到底部
scroll-to-bottom-on-input = keystroke  # keystroke, output, none

外观主题

主题选择

1
2
3
4
5
6
7
8
# 使用内置主题（运行 ghostty +list-themes 查看所有主题）
theme = catppuccin-mocha

# 亮色/暗色主题分别设置
theme = light:Rose Pine Dawn,dark:Rose Pine

# 自定义主题文件路径
theme = /path/to/my-theme

颜色配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
# 前景色和背景色
foreground = #cdd6f4
background = #1e1e2e

# 透明度设置
background-opacity = 0.95          # 0-1 之间
background-blur = true             # 启用毛玻璃效果
unfocused-split-opacity = 0.8      # 非活动分屏透明度

# 光标颜色
cursor-color = #f38ba8
cursor-text = #1e1e2e              # 光标下文字颜色

# 选中文字颜色
selection-background = #353749
selection-foreground = #cdd6f4

# 256色调色板
palette = 0=#45475a
palette = 1=#f38ba8
palette = 2=#a6e3a1
palette = 3=#f9e2af
# ... 继续定义 0-255

背景图片（1.2.0+）

1
2
3
4
5
background-image = /path/to/wallpaper.png
background-image-opacity = 0.3
background-image-position = center
background-image-fit = cover       # contain, cover, stretch, none
background-image-repeat = false

字体设置

基础字体

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 主字体（可多次指定实现 fallback）
font-family = JetBrains Mono
font-family = Maple Mono           # Fallback 字体

# 特定样式字体
font-family-bold = JetBrains Mono Bold
font-family-italic = JetBrains Mono Italic
font-family-bold-italic = JetBrains Mono Bold Italic

# 字体大小（点）
font-size = 13

# 字重调整（可变字体）
font-variation = wght=450

字体特性

1
2
3
4
5
6
7
8
9
10
11
12
13
# 禁用编程连字（如将 != 显示为 ≠）
font-feature = -calt
font-feature = -liga
font-feature = -dlig

# 禁用合成粗体/斜体
font-style = no-bold,no-italic

# 字形微调
adjust-cell-height = 10%           # 单元格高度调整
adjust-cell-baseline = 2           # 基线位置
adjust-underline-position = 1      # 下划线位置
adjust-underline-thickness = 1     # 下划线粗细

字体渲染

1
2
3
4
5
# 抗锯齿色彩空间（macOS）
alpha-blending = linear-corrected  # native, linear, linear-corrected

# FreeType 设置（Linux）
freetype-load-flags = hinting,force-autohint

窗口行为

窗口尺寸与位置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
# 初始窗口大小（字符网格）
window-width = 120
window-height = 35

# 初始窗口位置（像素，macOS 专用）
window-position-x = 100
window-position-y = 100

# 窗口内边距
window-padding-x = 8
window-padding-y = 8
window-padding-balance = true      # 平衡四周留白
window-padding-color = background  # background, extend, extend-always

# 全屏设置
fullscreen = false

窗口装饰

1
2
3
4
5
6
# 标题栏样式（通用）
window-decoration = auto           # auto, client, server, none

# 标签页设置
tab-bar = auto                     # always, auto, never
tab-position = top                 # GTK 专用

窗口状态

1
2
3
4
5
6
7
8
9
10
# 窗口状态保存
window-save-state = default        # default, never, always

# 新窗口继承设置
window-inherit-font-size = true
window-inherit-working-directory = true

# 关闭确认
confirm-close-surface = true       # true, false, always
quit-after-last-window-closed = false

键盘快捷键

快捷键语法

1
2
keybind = <trigger>=<action>
keybind = <trigger>=<action>:<parameter>

常用快捷键配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
# 复制粘贴
keybind = ctrl+shift+c=copy_to_clipboard
keybind = ctrl+shift+v=paste_from_clipboard

# 新建窗口/标签页
keybind = ctrl+shift+n=new_window
keybind = ctrl+shift+t=new_tab

# 分屏操作
keybind = ctrl+shift+d=new_split:right
keybind = ctrl+shift+minus=new_split:down
keybind = ctrl+shift+w=close_surface

# 切换标签页
keybind = ctrl+tab=next_tab
keybind = ctrl+shift+tab=previous_tab
keybind = ctrl+1=goto_tab:1
keybind = ctrl+2=goto_tab:2

# 缩放字体
keybind = ctrl+plus=increase_font_size:1
keybind = ctrl+minus=decrease_font_size:1
keybind = ctrl+0=reset_font_size

# 快速终端（Quake 模式）
keybind = f12=toggle_quick_terminal

# 重新加载配置
keybind = ctrl+shift+r=reload_config

快捷键前缀修饰符

1
2
3
4
5
6
7
8
9
10
11
# global: - 全局快捷键（即使 Ghostty 未聚焦）
keybind = global:ctrl+grave=toggle_quick_terminal

# all: - 应用到所有终端表面
keybind = all:ctrl+l=clear_screen

# unconsumed: - 不消费输入（同时发送给程序）
keybind = unconsumed:ctrl+a=reload_config

# performable: - 仅在可执行时生效
keybind = performable:ctrl+c=copy_to_clipboard

序列快捷键（Leader Key）

1
2
3
4
# 类似 Vim 的 leader key
keybind = ctrl+a>n=new_tab
keybind = ctrl+a>d=new_split:right
keybind = ctrl+a>q=quit

高级功能

鼠标设置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
# 鼠标点击超时（毫秒）
mouse-click-timeout = 500

# 右键菜单行为
mouse-right-click = context-menu   # context-menu, paste, copy, copy-or-paste, ignore

# Shift+点击行为
mouse-shift-capture = false        # true, false, always, never

# 滚轮滚动倍数
mouse-scroll-multiplier = 3

# 选中文本自动复制
clipboard-read = allow             # ask, allow, deny
clipboard-write = allow            # ask, allow, deny
copy-on-select = true

链接与高亮

1
2
3
4
5
6
# URL 识别与打开
link-url = true
link-url-previews = true           # 显示链接预览

# 自定义链接匹配（暂不可用）
# link = regex:pattern,action:open

图像协议

1
2
# Kitty 图像协议内存限制
image-storage-limit = 320MB        # 每个屏幕的最大图像数据

提示音

1
2
3
bell-features = attention,title    # system, audio, attention, title, border
bell-audio-path = /path/to/sound.wav
bell-audio-volume = 0.5

自定义着色器（GLSL）

1
2
custom-shader = /path/to/shader.glsl
custom-shader-animation = true     # true, false, always

着色器 Uniform 变量：

  • iChannel0 - 终端屏幕纹理
  • iResolution - 输出尺寸
  • iTime / iTimeDelta - 时间
  • iCurrentCursor - 当前光标信息
  • iPreviousCursor - 上一帧光标信息

macOS 专属配置

标题栏样式

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 标题栏风格
macos-titlebar-style = transparent  # native, transparent, tabs, hidden

# 窗口按钮
macos-titlebar-buttons = visible    # visible, hidden

# 代理图标（当前文件夹图标）
macos-titlebar-proxy-icon = visible

# 非原生全屏
macos-non-native-fullscreen = false  # true, false, visible-menu, padded-notch

# 窗口阴影
macos-window-shadow = true

Option 键行为

1
2
# 将 Option 视为 Alt 键
macos-option-as-alt = true          # true, false, left, right

Dock 与应用切换器

1
2
3
4
5
6
# 隐藏 Dock 图标（适合快速终端用户）
macos-hidden = never                # never, always

# 自动安全输入（密码框）
macos-auto-secure-input = true
macos-secure-input-indicator = true

应用图标自定义

1
2
3
4
5
6
7
8
9
10
11
12
# 预设图标风格
macos-icon = blueprint              # official, blueprint, chalkboard, microchip, glass, holographic, paper, retro, xray

# 自定义样式
macos-icon = custom-style
macos-icon-frame = aluminum         # aluminum, beige, plastic, chrome
macos-icon-ghost-color = #89b4fa
macos-icon-screen-color = #1e1e2e,#313244

# 完全自定义图标
macos-icon = custom
macos-custom-icon = ~/.config/ghostty/Ghostty.icns

快捷指令集成

1
macos-shortcuts = ask               # ask, allow, deny

快速终端（Quake 模式）

1
2
3
4
5
6
quick-terminal-position = top       # top, bottom, left, right, center
quick-terminal-size = 50%,100%      # 高度,宽度
quick-terminal-screen = main        # main, mouse, macos-menu-bar
quick-terminal-animation-duration = 0.2
quick-terminal-autohide = true
quick-terminal-space-behavior = move  # move, remain

Linux/GTK 专属配置

单实例模式

1
gtk-single-instance = detect        # true, false, detect

标签页设置

1
2
3
4
5
6
7
8
# 标签页位置
gtk-tabs-location = top             # top, bottom, hidden

# 标签页样式
gtk-wide-tabs = true                # true, false

# 最大化时隐藏标题栏
gtk-titlebar-hide-when-maximized = false

标题栏样式

1
gtk-titlebar-style = native         # native, tabs

标签栏外观

1
gtk-adwaita-toolbar-style = flat    # flat, raised, raised-border

自定义 CSS

1
gtk-css = /path/to/custom.css

桌面通知

1
2
3
gtk-desktop-notifications = true
notification = clipboard-copy       # clipboard-copy, config-reload
notification = no-config-reload     # 禁用某项

Cgroup 隔离（资源管理）

1
2
3
4
linux-cgroup = single-instance      # never, always, single-instance
linux-cgroup-memory-limit = 1GB
linux-cgroup-processes-limit = 100
linux-cgroup-hard-fail = false

实用配置示例

🎨 开发环境推荐配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
# 主题与外观
theme = catppuccin-mocha
background-opacity = 0.95
background-blur = true

# 字体
font-family = JetBrainsMono Nerd Font
font-family = Maple Mono CN
font-size = 13
font-feature = -calt

# 窗口
window-padding-x = 8
window-padding-y = 8
window-width = 120
window-height = 35

# Shell
command = /opt/homebrew/bin/fish
window-inherit-working-directory = true

# 快捷键
keybind = ctrl+shift+t=new_tab
keybind = ctrl+shift+d=new_split:right
keybind = ctrl+shift+minus=new_split:down
keybind = f12=toggle_quick_terminal

🖥️ 极简透明风格

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
# 完全透明
theme = ""
background = #000000
background-opacity = 0.85
background-blur = true
window-decoration = false

# 无边框
window-padding-x = 0
window-padding-y = 0
window-padding-balance = true

# 细字体
font-family = SF Mono
font-size = 12
font-thicken = false

⌨️ Vim 用户优化

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# Leader key 风格快捷键
keybind = ctrl+a>n=new_tab
keybind = ctrl+a>d=new_split:right
keybind = ctrl+a>s=new_split:down
keybind = ctrl+a>h=goto_split:left
keybind = ctrl+a>j=goto_split:bottom
keybind = ctrl+a>k=goto_split:top
keybind = ctrl+a>l=goto_split:right

# 禁用可能与 Vim 冲突的快捷键
keybind = ctrl+h=unbind
keybind = ctrl+j=unbind
keybind = ctrl+k=unbind
keybind = ctrl+l=unbind

🔒 安全优先配置

1
2
3
4
5
6
7
8
9
# 禁用潜在风险功能
clipboard-read = ask
clipboard-write = ask
title-report = false
confirm-close-surface = always

# OSC 52 剪贴板控制
clipboard-read = deny
clipboard-write = deny

常用 CLI 命令

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
# 列出所有可用主题
ghostty +list-themes

# 列出系统字体
ghostty +list-fonts

# 列出所有可绑定动作
ghostty +list-actions

# 验证配置文件
ghostty +validate-config

# 打印最终配置
ghostty +show-config

# 以特定配置启动
ghostty --config-file=/path/to/config

# 临时覆盖配置启动
ghostty --font-size=15 --theme="Dracula"

故障排除

配置热重载

修改配置文件后，使用以下方式重新加载：

  • 快捷键：ctrl+shift+r（如果配置了）
  • 菜单：Ghostty → Reload Configuration
  • 命令：killall -USR1 ghostty

调试配置问题

1
2
3
4
5
# 查看详细日志
ghostty --log-level=debug

# GTK 调试模式（Linux）
GTK_DEBUG=interactive ghostty

常见问题

Q: 字体显示模糊？
A: 尝试调整 alpha-blending = native 或 font-thicken = true

Q: 透明背景无效？
A: 确保 background-opacity < 1，某些桌面环境可能需要额外配置

Q: 快捷键不生效？
A: 检查是否有 global: 前缀需要系统权限，或使用 ghostty +list-actions 确认动作名称

💡 提示: 本文档基于 Ghostty 1.2.0 版本编写，部分功能可能需要更新版本支持。建议定期查看官方文档获取最新信息。