wezterm.plugin.list()：枚举已安装插件仓库的完整指南

wezterm.plugin.list()：枚举已安装插件仓库的完整指南

【免费下载链接】weztermA GPU-accelerated cross-platform terminal emulator and multiplexer written by @wez and implemented in Rust项目地址: https://gitcode.com/GitHub_Trending/we/wezterm

导读

wezterm.plugin.list()是 WezTerm 插件管理体系中一个轻量但关键的查询接口：它不安装、不更新、不删除任何东西，而是枚举运行时目录中所有已 checkout 的插件仓库，并返回包含url、component、plugin_dir三项字段的数组。在实战中，它是定位插件绝对路径、构建多模块插件的package.path、以及确认某个 Git URL 是否已被成功克隆的“侦察工具”。读完本文，你将掌握该函数的返回结构、目录命名规则、底层实现原理，以及将其接入 Lua 配置的三种典型用法。

函数签名与返回结构

wezterm.plugin.list()自20230320-124340-559cb7b0版本起可用。它不接受任何参数，调用后返回一个table array（数组型 Lua 表），其中每一项对应插件目录下的一个插件仓库，包含三个字段：

一个典型的返回结果如下（来自 docs/config/plugins.md 的官方示例）：

-- 伪代码形式展示返回结构（可在 Lua REPL 中直接打印观察） [ { "component": "filesCssZssZssZsUserssZsdevelopersZsprojectssZsmysDsPlugin", "plugin_dir": "/Users/alec/Library/Application Support/wezterm/plugins/filesCssZssZssZsUserssZsalecsZsprojectssZsbarsDswezterm", "url": "file:///Users/developer/projects/my.Plugin", }, ]

注意：list()只会枚举已 clone 的插件仓库。一个 URL 只有在被wezterm.plugin.require()首次引用（并成功克隆）之后，才会出现在插件目录中，进而被list()感知。

component字段：URL 到目录名的编码规则

component字段是整个机制的关键：WezTerm 需要把任意 Git URL（可能包含://、/、.、:等对文件系统不友好的字符）编码成单一合法的目录名。该逻辑实现在 lua-api-crates/plugin/src/lib.rs 的compute_repo_dir函数中：

• /与\→ 编码为sZs
• :→ 编码为sCs
• .→ 编码为sDs
• -与_→ 原样保留
• 字母与数字 → 原样保留
• 其他字符 → 编码为u+ 该字符的 Unicode 码点（如u32）
• 若末尾恰好是sZs，则将其截断，避免目录名以“目录分隔符编码”结尾

配套的单测用例给出了最直观的印证（见 lib.rs 测试模块）：

("foo", "foo"), ("githubsDscom/wezterm/wezterm-plugins", "githubsDscomsZsweztermsZswezterm-plugins"), ("localhost:8080/repo", "localhostsCs8080sZsrepo"),

这就是上例中file:///Users/developer/projects/my.Plugin会被编码为filesCssZssZssZsUserssZsdevelopersZsprojectssZsmysDsPlugin的原因——观察可见.变成了sDs、/变成了sZs、:变成了sCs。理解这条规则，你就能在手动查看磁盘目录时反推某个目录对应哪个插件 URL，也能避免在脚本里硬编码错误目录名。

plugin_dir字段：插件在磁盘上的真实位置

plugin_dir返回的是插件 checkout 的绝对路径。从 RepoSpec::plugins_dir 的源码可以看到，该路径由两部分拼接而成：

DATA_DIR/plugins/<component>

其中DATA_DIR由 config/src/config.rs 的compute_data_dir计算：优先使用平台标准的用户数据目录下的wezterm子目录（如 macOS 的~/Library/Application Support/wezterm、Linux 的$XDG_DATA_HOME/wezterm），无标准目录时回退到~/.local/share/wezterm。

由此可以推断实际磁盘布局：

• Linux：~/.local/share/wezterm/plugins/<component>/（或$XDG_DATA_HOME/wezterm/plugins/<component>/）
• macOS：~/Library/Application Support/wezterm/plugins/<component>/
• Windows：以dirs_next::data_dir()结果为准，通常在用户数据目录下的wezterm\plugins\<component>\

与list()配套的还有两个函数，便于理解该目录的管理闭环：

• wezterm.plugin.require：首次调用时把仓库克隆到plugins/NAME，此后不再自动更新；
• wezterm.plugin.update_all：对插件目录中的每个仓库执行 fast-forward 或 pull-rebase 更新，但不会自动重载配置，更新后需手动调用wezterm.reload_configuration()。

底层实现：list 的调用链与依赖

list()的注册代码位于 lua-api-crates/plugin/src/lib.rs，其核心调用链清晰可循：

1. 用户调用wezterm.plugin.list()；
2. 进入list_plugins()：先create_dir_all确保plugins目录存在（即使为空也返回空数组而非报错），然后遍历该目录，仅对目录项调用RepoSpec::load_from_dir；
3. load_from_dir从目录名取出component，用git2::Repository::open打开仓库、读取其第一个 remote 的 URL 得到url字段；
4. 结果经to_lua序列化为 Lua 数组返回。

两点值得注意的实现细节：

• 依赖 libgit2：url字段并不是缓存，而是实时从仓库的 git remote 配置中读出的。这意味着如果某个仓库的origin被改动，list()返回的url也会随之变化；
• 无需联网：整个list()过程只做本地目录遍历与 git 元数据读取，不发起任何网络请求，可以安全地在离线环境下使用。

此外，该函数只遍历插件目录的直接子目录，不递归扫描，因此返回的数组长度即为已安装插件数量。

实战用法一：定位插件绝对路径

最直接的用途就是拿到某个插件的磁盘位置，便于排查、修改或删除：

local wezterm = require 'wezterm' for _, plugin in ipairs(wezterm.plugin.list()) do print(plugin.url, '->', plugin.plugin_dir) end

若要卸载插件，可结合 docs/config/plugins.md 的说明：用list()查得plugin_dir后，直接删除对应的插件目录即可（注意该目录为本地运行时缓存，删除后下次require会重新克隆）。

实战用法二：为多模块插件更新 package.path

list()在文档中出现频率最高的实战场景，是支持带多个 Lua 模块的本地插件开发。当你的插件除了plugin/init.lua还需要require其他模块时，必须先获得插件目录并把它加入package.path（此写法来自 docs/config/plugins.md）：

function findPluginPackagePath(myProject) local separator = package.config:sub(1, 1) == '\\' and '\\' or '/' for _, v in ipairs(wezterm.plugin.list()) do if v.url == myProject then return v.plugin_dir .. separator .. 'plugin' .. separator .. '?.lua' end end --- #TODO 在此补充错误处理 end package.path = package.path .. ';' .. findPluginPackagePath 'file:///Users/developer/projects/my.Plugin'

关键点在于：

• 用v.url == myProject精确匹配，而不是依赖component的编码名，避免手写出错；
• package.config:sub(1, 1)用于探测当前平台的路径分隔符（\或/），保证跨平台可用；
• 因为list()返回的plugin_dir是绝对路径，拼接出的路径对 Lua 的require完全有效。

实战用法三：批量检查并联动 update_all

list()返回的数组结构也可以直接与更新流程联动。例如在 DebugOverlay（Lua REPL）中先查看有哪些插件，再执行批量更新：

-- 查看当前已安装的插件及其磁盘路径 wezterm.plugin.list() -- 更新所有插件（注意：不会自动重载配置） wezterm.plugin.update_all() -- 手动重载配置使更新生效 wezterm.reload_configuration()

wezterm.reload_configuration()的用法与注意事项见 docs/config/lua/wezterm/reload_configuration.md：切勿在配置文件顶层直接调用它（会造成无限重载循环），应放在事件或定时器回调中使用。

总结

wezterm.plugin.list()虽小，却是插件管理链路上不可替代的一环：它把磁盘上“编码后”的目录名还原为可直接用于匹配的url、可安全拼接路径的plugin_dir，为插件路径定位、多模块package.path构建和更新联动提供了统一入口。配合 index.md 中列出的require与update_all，即可完整覆盖“安装—查询—更新”的插件生命周期。

【免费下载链接】weztermA GPU-accelerated cross-platform terminal emulator and multiplexer written by @wez and implemented in Rust项目地址: https://gitcode.com/GitHub_Trending/we/wezterm