WezTerm 配置指南：使用 `default_prog` 自定义终端默认启动程序

WezTerm 配置指南使用default_prog自定义终端默认启动程序【免费下载链接】weztermA GPU-accelerated cross-platform terminal emulator and multiplexer written by wez and implemented in Rust项目地址: https://gitcode.com/GitHub_Trending/we/weztermdefault_prog是 WezTerm 中用于决定「新开标签页 / 新窗口时默认运行哪个程序」的核心配置项。当你在命令行中没有显式指定prog时WezTerm 会使用default_prog定义的命令来替代系统默认 shell。阅读本文后你将掌握default_prog的完整语义、与命令行参数及默认 shell 的优先级关系并能结合default_cwd、set_environment_variables、launch_menu等配置构建一套完整的程序启动方案。default_prog是什么根据官方文档 default_prog.md 的定义如果在命令行上未指定prog则使用default_prog指定的命令而不是运行用户的 shell。在配置文件中它是一个 Lua 数组-- 让 wezterm 新开窗口时默认运行 top 进程监控工具 config.default_prog { top }其核心语义为第 0 个元素是要执行的命令executable其余元素作为该命令的位置参数positional arguments依次传入。例如让 WezTerm 默认启动一个登录模式的 fish shell-- 数组第一个元素是程序路径后面的元素是它的参数 config.default_prog { /usr/local/bin/fish, -l }在 config/src/config.rs 中该配置项被声明为OptionVecString其注释与文档描述完全一致即default_prog以数组形式实现第 0 个元素是要运行的命令其余元素作为位置参数传给该命令。这意味着你可以在配置中传入任意数量的参数而不必受限于命令 单个字符串的简单形式。不设置default_prog时WezTerm 默认运行什么如果不设置default_progWezTerm 在新建标签页或窗口时会启动你的 shell。具体 shell 的确定规则在 Launching Programs 中有明确说明在 Posix 系统Linux / macOS 等上使用密码数据库中为当前用户配置的 shell即/etc/passwd中的记录有意忽略$SHELL环境变量——这样用户在通过chsh之类的方式修改默认 shell 后无需重启 WezTerm 也能生效同时 WezTerm 会将$SHELL环境变量设置为它从密码数据库中解析出的那个 shell该 shell 以-SHELL形式启动即在 argv0 前加上-前缀使其以登录 shelllogin shell方式运行从而加载额外的启动文件并配置更完整的环境。这一行为在 pty/src/cmdbuilder.rs 的 Unix 实现中得到印证当命令构建器处于默认程序状态is_default_prog()返回 true时会使用从 shell 解析逻辑得到的 shell 路径将 shell 的 basename 加上-前缀作为 argv0并以-basename形式调用。在 Windows 系统上如果设置了%COMSPEC%环境变量则使用其值文档并不推荐修改 COMSPEC否则回退到cmd.exe。配置实战常见default_prog用法由于default_prog是一个数组你可以组合命令与参数实现各种启动场景-- 启动 tmux让每个新窗口都进入 tmux 会话 config.default_prog { tmux, new-session, -A, -s, main } -- 启动 zsh 并加载额外配置 config.default_prog { zsh, -l } -- 启动一个交互式 Python REPL config.default_prog { python3, -i } -- 使用绝对路径以避免 PATH 解析歧义 config.default_prog { /usr/local/bin/fish, -l }提示从 pty/src/cmdbuilder.rs 的实现看非默认程序会经过search_path在 PATH 中解析可执行文件路径。若你希望完全规避 PATH 环境差异可以在数组中直接写绝对路径。一次性启动其它程序wezterm start如果只是偶尔需要让某个程序跑在 WezTerm 里而并非改变默认行为则不必修改default_prog直接用start子命令# 打开一个运行 vim 编辑 wezterm 配置的新窗口 $ wezterm start -- vim ~/.wezterm.lua这条命令中--之后的内容会作为prog传给 WezTerm。根据 config/src/config.rs 中build_prog的逻辑命令行显式指定的prog拥有最高优先级只要命令行提供了 prog就直接使用它只有在命令行没有 prog 时才会回退到default_prog若两者都没有才使用CommandBuilder::new_default_prog()去解析默认 shell。命令行参数、default_prog、默认 shell 三者的优先级关系可以概括为命令行 prog如 wezterm start -- prog config.default_prog 系统默认 shell这一规则同样适用于wezterm record录制 asciicast等场景在 wezterm/src/asciicast.rs 中--prog参数为空时才回退到config.default_prog。从源码看default_prog的调用链在 WezTerm 的 GUI 主流程wezterm-gui/src/main.rs与 asciicast 录制wezterm/src/asciicast.rs中都通过config.build_prog(...)来组装最终的命令let mut cmd match prog { Some(args) { /* 使用命令行 prog */ } None { if let Some(prog) default_prog { // 第 0 个元素作为可执行文件其余作为参数 let mut args prog.iter(); let mut cmd CommandBuilder::new(args.next().expect(executable name)); cmd.args(args); cmd } else { CommandBuilder::new_default_prog() // 回退到系统默认 shell } } };而在apply_cmd_defaultsconfig/src/config.rs中还有一个值得注意的细节default_prog只会替换默认程序状态的命令构建器。也就是说如果某个 SpawnCommand 或命令行已经显式指定了程序default_prog不会覆盖它而是尊重已显式给出的程序。这与我们前面总结的优先级规则一致。对应地pty/src/cmdbuilder.rs 中的CommandBuilder设计为new_default_prog()创建一个默认程序构建器args 为空is_default_prog()通过args.is_empty()判断是否处于默认程序状态对默认程序构建器调用arg()会直接 panic防止错误地追加参数replace_default_prog()专门用于把默认程序替换为default_prog中定义的命令。此外Lua 层在解析os.getenv时也会借助CommandBuilder::new_default_prog()来获取与默认 shell一致的当前环境见 config/src/lua.rs确保配置中读取到的$SHELL等变量与最终 spawn 的进程环境一致。与其它配置项的组合使用default_prog通常不是孤立使用的把它与以下配置联动可以形成更完整的启动体验详见 Launching Programs。指定默认工作目录default_cwd如果你希望default_prog启动的程序落在特定目录下可以配合default_cwdconfig.default_prog { fish, -l } config.default_cwd /some/path在apply_cmd_defaultsconfig/src/config.rs中default_cwd只在命令未设置 cwd 时才生效因此--cwd命令行选项拥有更高优先级。而对于第一个窗口之后新建的标签页/窗格WezTerm 会优先解析当前 pane 的工作目录优先使用 Shell Integration 中由 OSC 7 上报的值其次才是default_cwd最后回退到用户主目录。为启动程序注入环境变量set_environment_variablesset_environment_variables会在wezterm进程环境的基础上为 spawn 出的程序追加指定的变量config.set_environment_variables { -- 让 cmd.exe 的提示符通过 OSC 7 上报当前目录并显示彩色时间与路径 prompt $E]7;file://localhost/$P$E\\$E[32m$T$E[0m $E[35m$P$E[36m$_$G$E[0m , }在启动器菜单中提供更多选项launch_menudefault_prog定义的是全局默认而launch_menu见 launch_menu.md则允许你在标签栏按钮右键点击弹出的启动器菜单中为不同场景准备多套启动命令。每个条目是一个 SpawnCommand 对象config.launch_menu { { args { top }, }, { label Bash, -- 省略时由 args 自动推导 args { bash, -l }, -- 省略 args 时使用 default_prog 定义的默认程序 -- cwd /some/path -- 可指定工作目录否则回退到 OSC 7 / 主目录 -- set_environment_variables { FOO bar }, -- 仅对该命令生效的变量覆盖 }, }其中args省略时默认程序即default_prog会被使用。你还可以通过绑定 ShowLauncher / ShowLauncherArgs 键位来唤起该菜单或使用 SpawnCommandInNewTab、SpawnCommandInNewWindow 按键分配直接以指定程序开新标签页/窗口。常见误区与注意事项default_prog是数组而不是字符串写成config.default_prog top会得到错误行为。数组的第一项必须是可执行文件本身因此{ top }正确而{ top -n 10 }会把top -n 10当作一个不存在的可执行文件。多个参数要拆成多个数组元素{ top, -n, 10 }。命令行 prog 优先于配置通过wezterm start -- prog、wezterm record -- prog显式指定的程序不会被default_prog覆盖。修改 shell 无需重启Posix 上 WezTerm 会从密码数据库重新解析默认 shell这也是文档中故意忽略 $SHELL的设计动机如需控制子进程中的$SHELL值请改用set_environment_variables。配置修改后需要重载修改default_prog后可在 WezTerm 配置~/.wezterm.lua中执行重载Reload Configuration新标签页/窗口即会采用新的默认程序。小结default_prog用数组形式的{ 可执行文件, 参数1, 参数2, ... }优雅地解决了默认启动哪个程序的问题它是命令行prog与系统默认 shell 之间的中间层优先级为命令行 prog default_prog 默认 shell。配合 Launching Programs 文档与 config.rs、cmdbuilder.rs 的源码你可以精确预测每一次 spawn 的行为并用default_cwd、set_environment_variables、launch_menu构建完整的启动工作流。【免费下载链接】weztermA GPU-accelerated cross-platform terminal emulator and multiplexer written by wez and implemented in Rust项目地址: https://gitcode.com/GitHub_Trending/we/wezterm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考