` 与 OSC 1337 数据通道)
WezTerm 用户变量User Vars完全指南pane:get_user_vars()与 OSC 1337 数据通道【免费下载链接】weztermA GPU-accelerated cross-platform terminal emulator and multiplexer written by wez and implemented in Rust项目地址: https://gitcode.com/GitHub_Trending/we/wezterm本文围绕 WezTerm 的pane:get_user_vars()API 展开讲解如何通过 iTerm2 风格的 OSC 1337SetUserVar转义序列在 shell 与 WezTerm 配置Lua之间建立一条可靠的“用户变量”数据通道。读完本文你将掌握从 shell 侧写入、在配置侧读取用户变量的完整流程并能基于user-var-changed、update-status事件与多路复用multiplexer传播机制实现诸如动态标签标题、状态栏自定义信息等实战方案。一、什么是用户变量User Varspane:get_user_vars()是 Pane 对象上提供的一个方法用于返回一个 Lua table其中保存着已经赋值给该 pane 的所有用户变量user variables。该方法自版本20210502-130208-bff6815d起可用。用户变量在语义上与环境变量environment variables有些相似但有几个关键区别它们作用域是终端 pane而非操作系统进程运行在 pane 里的应用程序只能写入、不能读取它们只有 WezTerm 自身以及你的 Lua 配置才能读取。用户变量由 iTerm2 定义、WezTerm 同样支持的转义序列来设置。由于它走的是标准的转义序列通道因此跨平台、跨进程模型都可用无论是本地 pane、SSH 远程 pane还是通过 tmux 嵌套运行需启用 tmux 透传都能正常工作。在源码层面用户变量的存储位置是终端状态中的一张HashMapterm/src/terminalstate/mod.rs 中声明了user_vars: HashMapString, String并通过 term/src/terminalstate/mod.rs 的user_vars()访问器对外提供只读访问。二、设置用户变量OSC 1337 SetUserVar 转义序列WezTerm 对操作系统中规定的转义序列Operating System CommandOSC进行解析。其中 OSC 1337 的SetUserVar子命令专门用于设置用户变量格式为ESC ] 1337 ; SetUserVarnamebase64-encoded-value BEL即\033]1337;SetUserVar名字Base64编码后的值\007\007为 BEL 终止符也可使用\033\\形式的 ST 终止符。值必须经过 base64 编码名称则保持明文。在解析侧wezterm-escape-parser/src/osc.rs 中实现了对keyword SetUserVar的匹配以分割出名称与值对值调用base64_decode解码后构造出ITermProprietary::SetUserVar { name, value }。该解析器还带有单元测试见 wezterm-escape-parser/src/osc.rs使用SetUserVarfooaGVsbG8这样的样例验证了往返编码与解码逻辑。2.1 在 shell 中封装设置函数为了在日常使用中方便地设置用户变量官方文档提供了一个 shell 函数__wezterm_set_user_var。该函数同样被收录在 WezTerm 的 shell integration 脚本 assets/shell-integration/wezterm.sh 中# 该函数发射 OSC 1337 序列为当前终端 pane 设置用户变量。 # 它要求 PATH 中存在 base64 工具。 # 该函数包含在 wezterm 的 shell integration 脚本中此处为清晰起见单独复现。 __wezterm_set_user_var() { if hash base64 2/dev/null ; then if [[ -z ${TMUX} ]] ; then printf \033]1337;SetUserVar%s%s\007 $1 echo -n $2 | base64 else # 使用 tmux 透传转义序列详见 tmux FAQ # 注意同时需要在 tmux.conf 中添加 set -g allow-passthrough on printf \033Ptmux;\033\033]1337;SetUserVar%s%s\007\033\\ $1 echo -n $2 | base64 fi fi } __wezterm_set_user_var foo bar代码要点检测 base64hash base64确保工具存在避免在精简环境中报错区分 tmux 场景当环境变量TMUX非空时说明当前运行在 tmux 内部需要用 tmux 的 passthrough 转义序列\033Ptmux;\033...\033\\将 OSC 1337 原样透传给外层终端。使用该方式前还需在tmux.conf中启用set -g allow-passthrough onecho -n去除换行避免把换行符编进 base64 结果。如果直接使用一条命令也可以写成来自 user-var-changed 与 passing-data 配方 中的等价写法printf \033]1337;SetUserVar%s%s\007 foo echo -n bar | base64这将把名为foo的用户变量设置为bar。2.2 base64 换行的注意事项在某些系统上base64命令默认会在输出一定长度后进行换行包裹从而限制值的最大长度。如果遇到值被截断或解析异常的情况可以给 base64 加上不换行参数例如-w 0GNU 版本或-b 0BSD 版本。三、读取用户变量pane:get_user_vars()设置好用户变量之后就可以在 WezTerm 的 Lua 配置中读取它。在任意拿到pane对象的地方如各种事件回调中调用pane:get_user_vars()即可返回包含全部用户变量的 tablewezterm.log_info(foo var is .. pane:get_user_vars().foo)get_user_vars()返回的是一个键值对 table键是用户变量名字符串值同样是字符串。访问不存在的键会得到nil因此实践中常用or 默认值或(var or )来兜底。3.1 源码级实现get_user_vars在 Lua API 层注册于 lua-api-crates/mux/src/pane.rs通过methods.add_method(get_user_vars, ...)绑定实际调用底层 pane 的copy_user_vars()方法methods.add_method(get_user_vars, |_, this, _: ()| { let mux get_mux()?; let pane this.resolve(mux)?; Ok(pane.copy_user_vars()) });注意其命名为copy_user_vars复制语义它返回的是用户变量集合的一个快照副本而非对内部状态的引用这保证了 Lua 侧拿到的是一个不受后续变更影响的独立 table。对于本地 panecopy_user_vars的实现位于 mux/src/localpane.rs直接克隆终端状态中的用户变量表fn copy_user_vars(self) - HashMapString, String { self.terminal.lock().user_vars().clone() }而对于通过多路复用协议连接的远端 pane则在 wezterm-client/src/pane/clientpane.rs 中有对应的客户端侧实现保证在 SSH 远程 pane 上同样可以读取到用户变量。四、设置用户变量触发的事件链在 pane 中设置或修改用户变量并非“写入即止”它还会在包含该 pane 的窗口内联动触发一系列事件与 UI 更新具体包括user-var-changed变量被设置或修改时直接触发允许你立即采取行动。该事件自版本20220903-194523-3bb1ed61起可用update-status触发左右状态栏status items的更新可在状态栏中展示用户变量信息标题与标签栏title / tab bar区域随之更新并在更新过程中触发与之关联的其他事件多路复用客户端传播用户变量的变更事件会传播到所有已连接的多路复用multiplexer客户端因此在远端窗口、多客户端场景下同样保持一致。user-var-changed事件的回调签名与使用示例如下来自 user-var-changedlocal wezterm require wezterm wezterm.on(user-var-changed, function(window, pane, name, value) wezterm.log_info(var, name, value) end) return {}当 shell 侧执行SetUserVar把foo设为bar时该处理器会被调用参数分别为name foo、value bar。五、实战让用户变量真正为你所用5.1 利用 shell integration 自动注入的内置变量安装并启用 shell integration 之后脚本 assets/shell-integration/wezterm.sh 会自动为每个 pane 设置一组内置用户变量无需手工编写任何代码变量名含义设置时机WEZTERM_PROG当前前台程序的名称每次执行命令时也用于在命令退出后清空WEZTERM_USER当前登录用户名id -un会话初始化时WEZTERM_HOST主机名Linux 读取/proc/sys/kernel/hostnamemacOS 用hostname也可从WEZTERM_HOSTNAME环境变量取会话初始化时WEZTERM_IN_TMUX是否运行在 tmux 内1/0会话初始化时例如__wezterm_set_user_var WEZTERM_USER $(id -un) __wezterm_set_user_var WEZTERM_HOST $(cat /proc/sys/kernel/hostname)这些内置变量可以直接在配置中通过pane:get_user_vars()读取用于状态栏、标签标题等展示场景。5.2 追踪前台程序PROG 变量与动态标签标题passing-data 配方 给出了一个非常经典的用法通过 alias trap 在 shell 中维护一个PROG用户变量记录当前正在运行的程序然后据此定制 tab 标题。shell 侧使用前面定义好的__wezterm_set_user_varfunction _run_prog() { # 将 PROG 设为正在运行的程序名 __wezterm_set_user_var PROG $1 # 程序结束时清除它 trap __wezterm_set_user_var PROG EXIT # 执行对应命令注意用 command 避免与 alias 定义循环 command $ } alias vim_run_prog vim alias tmux_run_prog tmux alias nvim_run_prog nvimwezterm 侧在format-tab-title事件中读取user_vars.PROG来拼接标签标题local wezterm require wezterm wezterm.on(format-tab-title, function(tab) local prog tab.active_pane.user_vars.PROG return tab.active_pane.title .. [ .. (prog or ) .. ] end) return {}注意这里的tab.active_pane.user_vars来自 PaneInformation 结构中的user_vars字段——这是获取用户变量的另一条等价途径与pane:get_user_vars()返回相同的底层数据。在format-tab-title这类以tab为入参的事件里使用该字段往往比自行持有 pane 引用更直接。5.3 在状态栏中展示用户变量借助update-status事件与pane:get_user_vars()可以在左右状态栏中实时展示变量。例如local wezterm require wezterm wezterm.on(update-status, function(window, pane) local vars pane:get_user_vars() local host vars.WEZTERM_HOST or unknown local user vars.WEZTERM_USER or window.set_right_status(wezterm.format { { Text user .. .. host }, }) end) return {}由于设置用户变量会触发update-status事件状态栏能够在变量变化时自动刷新无需手动轮询。六、注意事项与适用边界必须由 shell 主动配合用户变量只能由 pane 内的程序通过转义序列写入WezTerm 不会凭空产生它们。除了安装 shell integration 自动注入的内置变量外其他变量都需要你自行在 shell 配置如.bashrc、.zshrc、alias、函数中安排发射对应的 OSC 1337 序列。这是该机制唯一需要付出的“成本”base64 依赖设置函数依赖base64工具存在于 PATH 中且注意部分系统 base64 输出的换行包裹问题可用-w 0等参数规避tmux 透传在 tmux 内使用时必须使用 tmux passthrough 转义序列并在tmux.conf中开启set -g allow-passthrough on否则转义序列会被 tmux 吞掉版本要求pane:get_user_vars()需要版本20210502-130208-bff6815d及以上user-var-changed事件需要版本20220903-194523-3bb1ed61及以上跨客户端传播用户变量变更事件会传播到所有连接的多路复用客户端这让远端 pane、多窗口场景下的状态同步成为可能但请记住这依赖逃逸序列链路的完整透传包括经过 SSH、tmux 等中间层。七、与其他方案的关系用户变量并非 WezTerm 中 pane → 配置信息传递的唯一途径但它是最通用、跨场景能力最强的一个。在同一主题下仓库还提供了这些可对比参考的机制OSC 0/1/2 标题序列用于设置窗口标题与标签标题可用pane:get_title()读取OSC 7 工作目录序列用于上报当前工作目录可用pane:get_current_working_dir()读取本地进程探测pane:get_foreground_process_info()等不需要修改 shell 配置即可获取前台进程信息但仅对本地进程有效无法用于 SSH 远程或多路复用场景。相比之下用户变量是其中少数能“穿透” SSH 与多路复用连接的方案且用途完全由你定义——这正是它作为 pane 与配置间“自定义信号通道”的价值所在。更多对比细节可参考 passing-data 配方。【免费下载链接】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），仅供参考 WezTerm 用户变量（User Vars）完全指南：`pane:get_user_vars()` 与 OSC 1337 数据通道
WezTerm 用户变量User Vars完全指南pane:get_user_vars()与 OSC 1337 数据通道【免费下载链接】weztermA GPU-accelerated cross-platform terminal emulator and multiplexer written by wez and implemented in Rust项目地址: https://gitcode.com/GitHub_Trending/we/wezterm本文围绕 WezTerm 的pane:get_user_vars()API 展开讲解如何通过 iTerm2 风格的 OSC 1337SetUserVar转义序列在 shell 与 WezTerm 配置Lua之间建立一条可靠的“用户变量”数据通道。读完本文你将掌握从 shell 侧写入、在配置侧读取用户变量的完整流程并能基于user-var-changed、update-status事件与多路复用multiplexer传播机制实现诸如动态标签标题、状态栏自定义信息等实战方案。一、什么是用户变量User Varspane:get_user_vars()是 Pane 对象上提供的一个方法用于返回一个 Lua table其中保存着已经赋值给该 pane 的所有用户变量user variables。该方法自版本20210502-130208-bff6815d起可用。用户变量在语义上与环境变量environment variables有些相似但有几个关键区别它们作用域是终端 pane而非操作系统进程运行在 pane 里的应用程序只能写入、不能读取它们只有 WezTerm 自身以及你的 Lua 配置才能读取。用户变量由 iTerm2 定义、WezTerm 同样支持的转义序列来设置。由于它走的是标准的转义序列通道因此跨平台、跨进程模型都可用无论是本地 pane、SSH 远程 pane还是通过 tmux 嵌套运行需启用 tmux 透传都能正常工作。在源码层面用户变量的存储位置是终端状态中的一张HashMapterm/src/terminalstate/mod.rs 中声明了user_vars: HashMapString, String并通过 term/src/terminalstate/mod.rs 的user_vars()访问器对外提供只读访问。二、设置用户变量OSC 1337 SetUserVar 转义序列WezTerm 对操作系统中规定的转义序列Operating System CommandOSC进行解析。其中 OSC 1337 的SetUserVar子命令专门用于设置用户变量格式为ESC ] 1337 ; SetUserVarnamebase64-encoded-value BEL即\033]1337;SetUserVar名字Base64编码后的值\007\007为 BEL 终止符也可使用\033\\形式的 ST 终止符。值必须经过 base64 编码名称则保持明文。在解析侧wezterm-escape-parser/src/osc.rs 中实现了对keyword SetUserVar的匹配以分割出名称与值对值调用base64_decode解码后构造出ITermProprietary::SetUserVar { name, value }。该解析器还带有单元测试见 wezterm-escape-parser/src/osc.rs使用SetUserVarfooaGVsbG8这样的样例验证了往返编码与解码逻辑。2.1 在 shell 中封装设置函数为了在日常使用中方便地设置用户变量官方文档提供了一个 shell 函数__wezterm_set_user_var。该函数同样被收录在 WezTerm 的 shell integration 脚本 assets/shell-integration/wezterm.sh 中# 该函数发射 OSC 1337 序列为当前终端 pane 设置用户变量。 # 它要求 PATH 中存在 base64 工具。 # 该函数包含在 wezterm 的 shell integration 脚本中此处为清晰起见单独复现。 __wezterm_set_user_var() { if hash base64 2/dev/null ; then if [[ -z ${TMUX} ]] ; then printf \033]1337;SetUserVar%s%s\007 $1 echo -n $2 | base64 else # 使用 tmux 透传转义序列详见 tmux FAQ # 注意同时需要在 tmux.conf 中添加 set -g allow-passthrough on printf \033Ptmux;\033\033]1337;SetUserVar%s%s\007\033\\ $1 echo -n $2 | base64 fi fi } __wezterm_set_user_var foo bar代码要点检测 base64hash base64确保工具存在避免在精简环境中报错区分 tmux 场景当环境变量TMUX非空时说明当前运行在 tmux 内部需要用 tmux 的 passthrough 转义序列\033Ptmux;\033...\033\\将 OSC 1337 原样透传给外层终端。使用该方式前还需在tmux.conf中启用set -g allow-passthrough onecho -n去除换行避免把换行符编进 base64 结果。如果直接使用一条命令也可以写成来自 user-var-changed 与 passing-data 配方 中的等价写法printf \033]1337;SetUserVar%s%s\007 foo echo -n bar | base64这将把名为foo的用户变量设置为bar。2.2 base64 换行的注意事项在某些系统上base64命令默认会在输出一定长度后进行换行包裹从而限制值的最大长度。如果遇到值被截断或解析异常的情况可以给 base64 加上不换行参数例如-w 0GNU 版本或-b 0BSD 版本。三、读取用户变量pane:get_user_vars()设置好用户变量之后就可以在 WezTerm 的 Lua 配置中读取它。在任意拿到pane对象的地方如各种事件回调中调用pane:get_user_vars()即可返回包含全部用户变量的 tablewezterm.log_info(foo var is .. pane:get_user_vars().foo)get_user_vars()返回的是一个键值对 table键是用户变量名字符串值同样是字符串。访问不存在的键会得到nil因此实践中常用or 默认值或(var or )来兜底。3.1 源码级实现get_user_vars在 Lua API 层注册于 lua-api-crates/mux/src/pane.rs通过methods.add_method(get_user_vars, ...)绑定实际调用底层 pane 的copy_user_vars()方法methods.add_method(get_user_vars, |_, this, _: ()| { let mux get_mux()?; let pane this.resolve(mux)?; Ok(pane.copy_user_vars()) });注意其命名为copy_user_vars复制语义它返回的是用户变量集合的一个快照副本而非对内部状态的引用这保证了 Lua 侧拿到的是一个不受后续变更影响的独立 table。对于本地 panecopy_user_vars的实现位于 mux/src/localpane.rs直接克隆终端状态中的用户变量表fn copy_user_vars(self) - HashMapString, String { self.terminal.lock().user_vars().clone() }而对于通过多路复用协议连接的远端 pane则在 wezterm-client/src/pane/clientpane.rs 中有对应的客户端侧实现保证在 SSH 远程 pane 上同样可以读取到用户变量。四、设置用户变量触发的事件链在 pane 中设置或修改用户变量并非“写入即止”它还会在包含该 pane 的窗口内联动触发一系列事件与 UI 更新具体包括user-var-changed变量被设置或修改时直接触发允许你立即采取行动。该事件自版本20220903-194523-3bb1ed61起可用update-status触发左右状态栏status items的更新可在状态栏中展示用户变量信息标题与标签栏title / tab bar区域随之更新并在更新过程中触发与之关联的其他事件多路复用客户端传播用户变量的变更事件会传播到所有已连接的多路复用multiplexer客户端因此在远端窗口、多客户端场景下同样保持一致。user-var-changed事件的回调签名与使用示例如下来自 user-var-changedlocal wezterm require wezterm wezterm.on(user-var-changed, function(window, pane, name, value) wezterm.log_info(var, name, value) end) return {}当 shell 侧执行SetUserVar把foo设为bar时该处理器会被调用参数分别为name foo、value bar。五、实战让用户变量真正为你所用5.1 利用 shell integration 自动注入的内置变量安装并启用 shell integration 之后脚本 assets/shell-integration/wezterm.sh 会自动为每个 pane 设置一组内置用户变量无需手工编写任何代码变量名含义设置时机WEZTERM_PROG当前前台程序的名称每次执行命令时也用于在命令退出后清空WEZTERM_USER当前登录用户名id -un会话初始化时WEZTERM_HOST主机名Linux 读取/proc/sys/kernel/hostnamemacOS 用hostname也可从WEZTERM_HOSTNAME环境变量取会话初始化时WEZTERM_IN_TMUX是否运行在 tmux 内1/0会话初始化时例如__wezterm_set_user_var WEZTERM_USER $(id -un) __wezterm_set_user_var WEZTERM_HOST $(cat /proc/sys/kernel/hostname)这些内置变量可以直接在配置中通过pane:get_user_vars()读取用于状态栏、标签标题等展示场景。5.2 追踪前台程序PROG 变量与动态标签标题passing-data 配方 给出了一个非常经典的用法通过 alias trap 在 shell 中维护一个PROG用户变量记录当前正在运行的程序然后据此定制 tab 标题。shell 侧使用前面定义好的__wezterm_set_user_varfunction _run_prog() { # 将 PROG 设为正在运行的程序名 __wezterm_set_user_var PROG $1 # 程序结束时清除它 trap __wezterm_set_user_var PROG EXIT # 执行对应命令注意用 command 避免与 alias 定义循环 command $ } alias vim_run_prog vim alias tmux_run_prog tmux alias nvim_run_prog nvimwezterm 侧在format-tab-title事件中读取user_vars.PROG来拼接标签标题local wezterm require wezterm wezterm.on(format-tab-title, function(tab) local prog tab.active_pane.user_vars.PROG return tab.active_pane.title .. [ .. (prog or ) .. ] end) return {}注意这里的tab.active_pane.user_vars来自 PaneInformation 结构中的user_vars字段——这是获取用户变量的另一条等价途径与pane:get_user_vars()返回相同的底层数据。在format-tab-title这类以tab为入参的事件里使用该字段往往比自行持有 pane 引用更直接。5.3 在状态栏中展示用户变量借助update-status事件与pane:get_user_vars()可以在左右状态栏中实时展示变量。例如local wezterm require wezterm wezterm.on(update-status, function(window, pane) local vars pane:get_user_vars() local host vars.WEZTERM_HOST or unknown local user vars.WEZTERM_USER or window.set_right_status(wezterm.format { { Text user .. .. host }, }) end) return {}由于设置用户变量会触发update-status事件状态栏能够在变量变化时自动刷新无需手动轮询。六、注意事项与适用边界必须由 shell 主动配合用户变量只能由 pane 内的程序通过转义序列写入WezTerm 不会凭空产生它们。除了安装 shell integration 自动注入的内置变量外其他变量都需要你自行在 shell 配置如.bashrc、.zshrc、alias、函数中安排发射对应的 OSC 1337 序列。这是该机制唯一需要付出的“成本”base64 依赖设置函数依赖base64工具存在于 PATH 中且注意部分系统 base64 输出的换行包裹问题可用-w 0等参数规避tmux 透传在 tmux 内使用时必须使用 tmux passthrough 转义序列并在tmux.conf中开启set -g allow-passthrough on否则转义序列会被 tmux 吞掉版本要求pane:get_user_vars()需要版本20210502-130208-bff6815d及以上user-var-changed事件需要版本20220903-194523-3bb1ed61及以上跨客户端传播用户变量变更事件会传播到所有连接的多路复用客户端这让远端 pane、多窗口场景下的状态同步成为可能但请记住这依赖逃逸序列链路的完整透传包括经过 SSH、tmux 等中间层。七、与其他方案的关系用户变量并非 WezTerm 中 pane → 配置信息传递的唯一途径但它是最通用、跨场景能力最强的一个。在同一主题下仓库还提供了这些可对比参考的机制OSC 0/1/2 标题序列用于设置窗口标题与标签标题可用pane:get_title()读取OSC 7 工作目录序列用于上报当前工作目录可用pane:get_current_working_dir()读取本地进程探测pane:get_foreground_process_info()等不需要修改 shell 配置即可获取前台进程信息但仅对本地进程有效无法用于 SSH 远程或多路复用场景。相比之下用户变量是其中少数能“穿透” SSH 与多路复用连接的方案且用途完全由你定义——这正是它作为 pane 与配置间“自定义信号通道”的价值所在。更多对比细节可参考 passing-data 配方。【免费下载链接】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），仅供参考