WezTerm `wezterm.url` 模块完全指南：在 Lua 配置中解析 URL 与使用 Url 对象

WezTermwezterm.url模块完全指南在 Lua 配置中解析 URL 与使用 Url 对象【免费下载链接】weztermA GPU-accelerated cross-platform terminal emulator and multiplexer written by wez and implemented in Rust项目地址: https://gitcode.com/GitHub_Trending/we/weztermwezterm.url是 WezTerm 在20240127-113634-bbcac864版本中引入的 Lua 模块用于在配置脚本中解析 URL 并操作其结构化的Url对象。通过它你可以安全地解码含百分号编码percent-encoding的路径、提取主机名与查询参数从而在open-uri事件处理、状态栏展示当前工作目录等场景中编写可靠的自定义逻辑。读完本文你将掌握wezterm.url.parse的用法、Url对象的全部字段语义以及如何与pane:get_current_working_dir、OSC 7 工作目录协议配合完成实战级配置。模块概览与适用场景wezterm.url模块入口见 docs/config/lua/wezterm.url/index.markdown对外暴露处理 URL 的函数与对象。其设计动机来自一个实际问题终端里的 URL尤其是file://形式的本地路径往往带有百分号编码直接对字符串做sub/gsub手工解码既繁琐又容易出错。把 URL 解析成结构化对象后读写路径、主机名、查询串都变成字段访问。该模块在实际使用中主要服务于两类场景自定义超链接行为监听open-uri事件对file://链接判断是目录还是文本文件进而执行cd、启动编辑器等操作状态栏展示在update-right-status中读取当前 pane 的工作目录展示远程主机名与路径配合 OSC 7 shell 集成。核心 APIwezterm.url.parse(URL_STRING)wezterm.url.parse是模块对外暴露的唯一函数签名与行为定义在 docs/config/lua/wezterm.url/parse.mdwezterm.url.parse(URL_STRING)它尝试把传入的字符串当作 URL 解析解析成功时返回一个 Url 对象解析失败则抛出错误。调用方式是标准的模块方法调用local wezterm require wezterm local url wezterm.url.parse file://myhost/some/path%20with%20spaces其底层实现位于 lua-api-crates/url-funcs/src/lib.rs。register函数通过get_or_create_sub_module(lua, url)注册url子模块再向其中写入parse函数。parse内部直接调用 Rust 生态的urlcrate依赖声明见 lua-api-crates/url-funcs/Cargo.toml完成解析任何解析失败都会携带原始输入字符串包装成 Lua 错误抛出例如relative URL without a base while parsing xxx as URL。这意味着传入的字符串必须是绝对 URL带 scheme不能是foo/bar这类相对路径。Url对象字段详解Url对象代表一个已被解析的 URL字段定义见 docs/config/lua/wezterm.url/Url.md对应源码实现见 lua-api-crates/url-funcs/src/lib.rs。全部字段按语义整理如下字段类型含义源码依据schemestringURL 协议名如file、httpslib.rs L48file_pathstring / nil解码path字段后的文件路径URL 无路径段时为nillib.rs L60-L81usernamestring用户名部分未指定时为空字符串lib.rs L49passwordstring / nil密码部分未指定时为nillib.rs L50-L52hoststring / nil主机名部分IDNA 解码为 UTF-8无主机时为nillib.rs L53pathstring路径部分保留百分号编码原样lib.rs L59fragmentstring / nilfragment#之后的内容部分lib.rs L56-L58querystring / nilquery?之后的内容部分lib.rs L55portnumber / nil端口号未指定时为nil文档未列出源码额外暴露lib.rs L54官方文档给出的校验示例完整如下local wezterm require wezterm local url wezterm.url.parse file://myhost/some/path%20with%20spaces assert(url.scheme file) assert(url.file_path /some/path with spaces) local url wezterm.url.parse https://github.com/rust-lang/rust/issues?labelsE-easystateopen assert(url.scheme https) assert(url.username ) assert(url.password nil) assert(url.host github.com) assert(url.path /rust-lang/rust/issues) assert(url.query labelsE-easystateopen)注意两个容易混淆的点path与file_path的区别path返回带百分号编码的原始路径如/some/path%20with%20spacesfile_path返回解码后的真实路径如/some/path with spaces。需要把 URL 当作文件系统路径使用时务必用file_path。username与password的缺省值不同无用户名时username是空字符串而无密码时password是nil。判断是否包含密码时应使用if url.password ~ nil而非真值判断。file_path的底层解码逻辑file_path的实现lib.rs L60-L81比简单调用解码函数更细致它遍历 URL 的每个路径段为每段前补上/后逐段做百分号解码并拼接。此外还有一处针对 Windows 盘符的特判——当解码结果以字母加:或|结尾时即盘符如C:会在末尾追加一个/避免C:与后续内容粘连源码注释 A windows drive letter must end with a slash。因此file_path在跨平台路径处理上比手写解码更稳妥。Url对象还支持哪些操作从源码看Url对象还做了两件额外的事实现了 Lua 的__tostring元方法lib.rs L42-L44直接tostring(url)即可得到完整的原始 URL 字符串内部通过Deref/DerefMut解引用到 Rust 的url::Urllib.rs L27-L38Rust 侧代码可以零成本复用urlcrate 的全部能力。实战一在open-uri中实现超链接点击行为wezterm.url最典型的实战用法是配合open-uri事件重写终端超链接的默认行为。仓库在 docs/recipes/hyperlinks.md 中给出了一份完整的可运行配置核心逻辑如下local wezterm require wezterm local act wezterm.action local config wezterm.config_builder() wezterm.on(open-uri, function(window, pane, uri) local editor nvim if uri:find ^file: 1 and not pane:is_alt_screen_active() then -- 链接格式应为file://[HOSTNAME]/PATH[#linenr] local url wezterm.url.parse(uri) if is_shell(pane:get_foreground_process_name()) then local success, stdout, _ wezterm.run_child_process { file, --brief, --mime-type, url.file_path, } if success then if stdout:find directory then -- 目录切换到该目录并列出内容 pane:send_text(wezterm.shell_join_args { cd, url.file_path } .. \r) pane:send_text(wezterm.shell_join_args { ls, -a, -p, --group-directories-first, } .. \r) return false end if stdout:find text then -- 文本文件用编辑器打开fragment 携带行号 local args { editor } if url.fragment then table.insert(args, .. url.fragment) end table.insert(args, url.file_path) pane:send_text(wezterm.shell_join_args(args) .. \r) return false end end end end -- 不返回值则回落到 WezTerm 默认行为 end) return config这段代码展示了Url对象在真实场景中的价值url.file_path拿到解码后的真实路径可直接传给file命令探测 MIME 类型url.fragment提取行号实现点击链接直接在编辑器第 N 行打开文件wezterm.shell_join_args负责路径转义避免空格路径被 shell 拆词。为了让超链接源真正可点击还需要在 shell 里开启超链接输出例如alias lsls --hyperlink --colorauto alias deltadelta --hyperlinks --hyperlinks-file-link-formatfile://{path}#{line} alias rgrg --hyperlink-formatkitty此外docs/recipes/hyperlinks.md还提供了可选的鼠标绑定改造默认单击即可打开链接若担心误触可要求按住CTRL才打开通过OpenLinkAtMouseCursor动作实现具体示例见 鼠标绑定配置。若使用 tmux需要启用超链接终端特性并视配置加上Shift修饰键set -sa terminal-features ,*:hyperlinks。该配方的局限是命令文本被直接注入当前 pane因此要求 pane 正处于 shell 提示符而非编辑器等交互程序内。实战二在状态栏解析当前工作目录第二个高价值场景是把Url对象用于状态栏。20240127-113634-bbcac864版本起pane:get_current_working_dir()的返回值从 URI 字符串变更为Url对象见 get_current_working_dir 文档 与 变更记录其源码实现可见 lua-api-crates/mux/src/pane.rsget_current_working_dir把底层url::Url包成url_funcs::Url返回。同时 PaneInformation.current_working_dir 字段也返回同一类型。update-right-status中的典型用法完整示例见 set_right_status 文档wezterm.on(update-right-status, function(window, pane) local cwd_uri pane:get_current_working_dir() if cwd_uri then local cwd local hostname if type(cwd_uri) userdata then -- 新版本拿到的是 Url 对象字段直接可用 cwd cwd_uri.file_path hostname cwd_uri.host or wezterm.hostname() else -- 旧版本20230712-072601-f4abf8fd 及更早字符串需手工解码 cwd_uri cwd_uri:sub(8) local slash cwd_uri:find / if slash then hostname cwd_uri:sub(1, slash - 1) cwd cwd_uri:sub(slash):gsub(%%(%x%x), function(hex) return string.char(tonumber(hex, 16)) end) end end -- ... 组装 PowerLine 风格状态栏 end end)这段代码的两处关键设计值得学习类型判断兼容旧版本用type(cwd_uri) userdata区分新版的Url对象与旧版的普通字符串旧分支里那行gsub(%%(%x%x), ...)正是对 percent-encoding 的手工解码——新版用url.file_path一行替代这也是官方引入该模块的初衷。host可能为nilfile://不带主机名时host为nil所以用cwd_uri.host or wezterm.hostname()回退到本机主机名。要让get_current_working_dir能拿到远程主机名需要在远端 shell 里启用 OSC 7 序列见 shell-integration.mdprintf \033]7;file://HOSTNAME/CURRENT/DIR\033\\OSC 7 把工作目录以file://URL 形式上报给终端本地 shell 未发送 OSC 7 时WezTerm 会通过进程组与操作系统调用自行推断 cwdUnix 与 Windows 均有支持。版本要求与兼容性注意wezterm.url模块、wezterm.url.parse与Url对象均自20240127-113634-bbcac864起可用见 index.markdown、parse.md 的since标注。同一版本起pane:get_current_working_dir()与PaneInformation.current_working_dir的返回值类型由字符串改为Url对象跨版本分发的配置请沿用上文type(cwd_uri) userdata的兼容写法。file_path对 Windows 盘符路径做了补/特判跨平台配置可以直接使用无需自行区分平台。延伸阅读模块入口与函数索引index.markdown、parse.md、Url.md底层实现lua-api-crates/url-funcs/src/lib.rs依赖url与percent-encodingcrate完整超链接配方docs/recipes/hyperlinks.md状态栏与兼容写法set_right_status 文档、get_current_working_dir 文档OSC 7 工作目录协议docs/shell-integration.md相关变更记录docs/changelog.md【免费下载链接】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），仅供参考