wezterm

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

WezTerm Configuration

WezTerm 配置

Configure the WezTerm terminal emulator.

配置WezTerm终端模拟器。

Prerequisites

前提条件

bash

undefined

bash

undefined

Install WezTerm

安装WezTerm

brew install --cask wezterm


Config location: `~/.wezterm.lua` or `~/.config/wezterm/wezterm.lua`

brew install --cask wezterm


配置文件位置: `~/.wezterm.lua` 或 `~/.config/wezterm/wezterm.lua`

Basic Configuration

基础配置

Minimal Config

最简配置

lua

-- ~/.wezterm.lua
local wezterm = require 'wezterm'
local config = wezterm.config_builder()

-- Font
config.font = wezterm.font('JetBrains Mono')
config.font_size = 14.0

-- Colors
config.color_scheme = 'Catppuccin Mocha'

-- Window
config.window_padding = {
  left = 10,
  right = 10,
  top = 10,
  bottom = 10,
}

return config

lua

-- ~/.wezterm.lua
local wezterm = require 'wezterm'
local config = wezterm.config_builder()

-- 字体
config.font = wezterm.font('JetBrains Mono')
config.font_size = 14.0

-- 配色
config.color_scheme = 'Catppuccin Mocha'

-- 窗口
config.window_padding = {
  left = 10,
  right = 10,
  top = 10,
  bottom = 10,
}

return config

Font Configuration

字体配置

lua

-- Single font
config.font = wezterm.font('JetBrains Mono')

-- Font with fallbacks
config.font = wezterm.font_with_fallback({
  'JetBrains Mono',
  'Fira Code',
  'Nerd Font Symbols',
})

-- Font with weight
config.font = wezterm.font('JetBrains Mono', { weight = 'Medium' })

-- Different font for bold
config.font_rules = {
  {
    intensity = 'Bold',
    font = wezterm.font('JetBrains Mono', { weight = 'Bold' }),
  },
}

lua

-- 单一字体
config.font = wezterm.font('JetBrains Mono')

-- 带备选字体的配置
config.font = wezterm.font_with_fallback({
  'JetBrains Mono',
  'Fira Code',
  'Nerd Font Symbols',
})

-- 指定字重的字体
config.font = wezterm.font('JetBrains Mono', { weight = 'Medium' })

-- 为粗体文本设置不同字体
config.font_rules = {
  {
    intensity = 'Bold',
    font = wezterm.font('JetBrains Mono', { weight = 'Bold' }),
  },
}

Color Schemes

配色方案

lua

-- Use built-in scheme
config.color_scheme = 'Catppuccin Mocha'

-- List available schemes
-- wezterm show-keys --lua

-- Custom colors
config.colors = {
  foreground = '#c0caf5',
  background = '#1a1b26',
  cursor_bg = '#c0caf5',
  selection_bg = '#33467c',
  ansi = {'#15161e', '#f7768e', '#9ece6a', '#e0af68', '#7aa2f7', '#bb9af7', '#7dcfff', '#a9b1d6'},
  brights = {'#414868', '#f7768e', '#9ece6a', '#e0af68', '#7aa2f7', '#bb9af7', '#7dcfff', '#c0caf5'},
}

lua

-- 使用内置配色方案
config.color_scheme = 'Catppuccin Mocha'

-- 列出所有可用配色方案
-- wezterm show-keys --lua

-- 自定义配色
config.colors = {
  foreground = '#c0caf5',
  background = '#1a1b26',
  cursor_bg = '#c0caf5',
  selection_bg = '#33467c',
  ansi = {'#15161e', '#f7768e', '#9ece6a', '#e0af68', '#7aa2f7', '#bb9af7', '#7dcfff', '#a9b1d6'},
  brights = {'#414868', '#f7768e', '#9ece6a', '#e0af68', '#7aa2f7', '#bb9af7', '#7dcfff', '#c0caf5'},
}

Key Bindings

按键绑定

Custom Keybindings

自定义按键绑定

lua

config.keys = {
  -- Split panes
  { key = 'd', mods = 'CMD', action = wezterm.action.SplitHorizontal { domain = 'CurrentPaneDomain' } },
  { key = 'd', mods = 'CMD|SHIFT', action = wezterm.action.SplitVertical { domain = 'CurrentPaneDomain' } },

  -- Navigate panes
  { key = 'LeftArrow', mods = 'CMD', action = wezterm.action.ActivatePaneDirection 'Left' },
  { key = 'RightArrow', mods = 'CMD', action = wezterm.action.ActivatePaneDirection 'Right' },
  { key = 'UpArrow', mods = 'CMD', action = wezterm.action.ActivatePaneDirection 'Up' },
  { key = 'DownArrow', mods = 'CMD', action = wezterm.action.ActivatePaneDirection 'Down' },

  -- Tabs
  { key = 't', mods = 'CMD', action = wezterm.action.SpawnTab 'CurrentPaneDomain' },
  { key = 'w', mods = 'CMD', action = wezterm.action.CloseCurrentPane { confirm = true } },

  -- Font size
  { key = '=', mods = 'CMD', action = wezterm.action.IncreaseFontSize },
  { key = '-', mods = 'CMD', action = wezterm.action.DecreaseFontSize },
  { key = '0', mods = 'CMD', action = wezterm.action.ResetFontSize },
}

lua

config.keys = {
  -- 拆分窗格
  { key = 'd', mods = 'CMD', action = wezterm.action.SplitHorizontal { domain = 'CurrentPaneDomain' } },
  { key = 'd', mods = 'CMD|SHIFT', action = wezterm.action.SplitVertical { domain = 'CurrentPaneDomain' } },

  -- 切换窗格
  { key = 'LeftArrow', mods = 'CMD', action = wezterm.action.ActivatePaneDirection 'Left' },
  { key = 'RightArrow', mods = 'CMD', action = wezterm.action.ActivatePaneDirection 'Right' },
  { key = 'UpArrow', mods = 'CMD', action = wezterm.action.ActivatePaneDirection 'Up' },
  { key = 'DownArrow', mods = 'CMD', action = wezterm.action.ActivatePaneDirection 'Down' },

  -- 标签页
  { key = 't', mods = 'CMD', action = wezterm.action.SpawnTab 'CurrentPaneDomain' },
  { key = 'w', mods = 'CMD', action = wezterm.action.CloseCurrentPane { confirm = true } },

  -- 字体大小调整
  { key = '=', mods = 'CMD', action = wezterm.action.IncreaseFontSize },
  { key = '-', mods = 'CMD', action = wezterm.action.DecreaseFontSize },
  { key = '0', mods = 'CMD', action = wezterm.action.ResetFontSize },
}

Leader Key

引导键（Leader Key）

lua

-- Define leader key (like tmux prefix)
config.leader = { key = 'a', mods = 'CMD', timeout_milliseconds = 1000 }

config.keys = {
  -- Leader + c = new tab
  { key = 'c', mods = 'LEADER', action = wezterm.action.SpawnTab 'CurrentPaneDomain' },
  -- Leader + | = vertical split
  { key = '|', mods = 'LEADER', action = wezterm.action.SplitHorizontal { domain = 'CurrentPaneDomain' } },
  -- Leader + - = horizontal split
  { key = '-', mods = 'LEADER', action = wezterm.action.SplitVertical { domain = 'CurrentPaneDomain' } },
}

lua

-- 定义引导键（类似tmux前缀键）
config.leader = { key = 'a', mods = 'CMD', timeout_milliseconds = 1000 }

config.keys = {
  -- 引导键 + c = 新建标签页
  { key = 'c', mods = 'LEADER', action = wezterm.action.SpawnTab 'CurrentPaneDomain' },
  -- 引导键 + | = 垂直拆分
  { key = '|', mods = 'LEADER', action = wezterm.action.SplitHorizontal { domain = 'CurrentPaneDomain' } },
  -- 引导键 + - = 水平拆分
  { key = '-', mods = 'LEADER', action = wezterm.action.SplitVertical { domain = 'CurrentPaneDomain' } },
}

Advanced Features

高级功能

Tab Bar Customization

标签栏自定义

lua

config.use_fancy_tab_bar = false
config.tab_bar_at_bottom = true
config.hide_tab_bar_if_only_one_tab = true

-- Custom tab title
wezterm.on('format-tab-title', function(tab)
  local title = tab.tab_title
  if title and #title > 0 then
    return title
  end
  return tab.active_pane.title
end)

lua

config.use_fancy_tab_bar = false
config.tab_bar_at_bottom = true
config.hide_tab_bar_if_only_one_tab = true

-- 自定义标签页标题
wezterm.on('format-tab-title', function(tab)
  local title = tab.tab_title
  if title and #title > 0 then
    return title
  end
  return tab.active_pane.title
end)

Startup Actions

启动动作

lua

-- Start with specific layout
wezterm.on('gui-startup', function(cmd)
  local tab, pane, window = mux.spawn_window(cmd or {})
  -- Split right
  pane:split { direction = 'Right' }
end)

lua

-- 以特定布局启动
wezterm.on('gui-startup', function(cmd)
  local tab, pane, window = mux.spawn_window(cmd or {})
  -- 向右拆分
  pane:split { direction = 'Right' }
end)

SSH Domains

SSH 域

lua

config.ssh_domains = {
  {
    name = 'my-server',
    remote_address = 'server.example.com',
    username = 'user',
  },
}

-- Connect with: wezterm connect my-server

lua

config.ssh_domains = {
  {
    name = 'my-server',
    remote_address = 'server.example.com',
    username = 'user',
  },
}

-- 连接方式: wezterm connect my-server

Multiplexer

多路复用器

lua

-- Unix domain for persistent sessions
config.unix_domains = {
  { name = 'unix' },
}

-- Default to multiplexer
config.default_gui_startup_args = { 'connect', 'unix' }

lua

-- 用于持久化会话的Unix域
config.unix_domains = {
  { name = 'unix' },
}

-- 默认使用多路复用器
config.default_gui_startup_args = { 'connect', 'unix' }

Useful Snippets

实用代码片段

Quick Theme Toggle

快速切换主题

lua

local function toggle_theme()
  local overrides = window:get_config_overrides() or {}
  if overrides.color_scheme == 'Catppuccin Latte' then
    overrides.color_scheme = 'Catppuccin Mocha'
  else
    overrides.color_scheme = 'Catppuccin Latte'
  end
  window:set_config_overrides(overrides)
end

config.keys = {
  { key = 't', mods = 'CMD|SHIFT', action = wezterm.action_callback(toggle_theme) },
}

lua

local function toggle_theme()
  local overrides = window:get_config_overrides() or {}
  if overrides.color_scheme == 'Catppuccin Latte' then
    overrides.color_scheme = 'Catppuccin Mocha'
  else
    overrides.color_scheme = 'Catppuccin Latte'
  end
  window:set_config_overrides(overrides)
end

config.keys = {
  { key = 't', mods = 'CMD|SHIFT', action = wezterm.action_callback(toggle_theme) },
}

Background Image

背景图片

lua

config.window_background_image = '/path/to/image.png'
config.window_background_image_hsb = {
  brightness = 0.02,
  saturation = 0.5,
}

lua

config.window_background_image = '/path/to/image.png'
config.window_background_image_hsb = {
  brightness = 0.02,
  saturation = 0.5,
}

Status Bar

状态栏

lua

wezterm.on('update-right-status', function(window, pane)
  window:set_right_status(wezterm.format({
    { Text = wezterm.strftime('%H:%M') },
  }))
end)

lua

wezterm.on('update-right-status', function(window, pane)
  window:set_right_status(wezterm.format({
    { Text = wezterm.strftime('%H:%M') },
  }))
end)

Command Line

命令行操作

bash

undefined

bash

undefined

Open with specific config

使用指定配置文件启动

wezterm --config-file path/to/config.lua

Connect to multiplexer

连接到多路复用器

wezterm connect unix

List color schemes

列出所有配色方案

wezterm ls-colors

Show key bindings

显示按键绑定

wezterm show-keys wezterm show-keys --lua

CLI utilities

CLI 工具

wezterm cli list # List panes wezterm cli spawn # Spawn new pane wezterm cli split-pane # Split current pane

undefined

wezterm cli list # 列出窗格 wezterm cli spawn # 新建窗格 wezterm cli split-pane # 拆分当前窗格

undefined

Best Practices

最佳实践

Start simple - Add features as needed
Use config_builder - Better error messages
Test incrementally - WezTerm reloads on save
Backup your config - Keep in dotfiles repo
Use leader keys - Avoid conflicts with apps
Check logs -
```
wezterm --config-file ~/.wezterm.lua
```
shows errors

从简开始 - 根据需要逐步添加功能
使用config_builder - 获得更友好的错误提示
增量测试 - WezTerm会在保存配置后自动重载
备份配置 - 将配置文件保存在dotfiles仓库中
使用引导键 - 避免与其他应用的快捷键冲突
查看日志 -
```
wezterm --config-file ~/.wezterm.lua
```
会显示错误信息