4 个场景跑通 WezTerm 插件开发：从 2 行加载到 10 行写插件

4 个场景跑通 WezTerm 插件开发：从 2 行加载到 10 行写插件

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

WezTerm 是用 Rust 编写的 GPU 加速终端模拟器与多路复用器，WezTerm 插件开发说白了就是把一段 Lua 文件塞进配置，让 WezTerm 从 git 仓库自动拉取加载。痛点在于：你想改快捷键、加状态栏，却不确定改动到底生效没有。下面按 4 个具体需求走一遍从加载现成插件到自己写、交付给同事的流程，每节都以验证方法收尾。

加载现成的 WezTerm Lua 插件：2 行配置生效

配置里加两行就能用别人的插件：

local wezterm = require 'wezterm' local clip = wezterm.plugin.require 'https://git.example.com/you/clip-copy' local config = wezterm.config_builder() clip.apply_to_config(config, { clipboard = 'Clipboard' }) return config

加载后代码在哪：第一次require时 WezTerm 会把仓库克隆到运行时目录的plugins/子目录，检出默认分支；目录名由 URL 编码而来，想确认每个插件的实际路径，在 DebugOverlay 的 Lua REPL 里跑wezterm.plugin.list()。

传参方式：apply_to_config第二个参数是任意 Lua table，插件内部按需读取。支持哪些字段只有插件自己的 README 说得清，用之前看一眼。

同类需求一个套路：如果插件做的是 WezTerm 状态栏自定义（比如在update-status事件里调window:set_left_status），加载方式完全一样，差别只在apply_to_config内部改了什么。机制细节见 docs/config/plugins.md。

从零写一个 WezTerm 快捷键插件：入口文件只有 10 行

目标：把 Ctrl+Shift+C 绑到"复制"，并且复制目标（终端缓冲区还是系统剪贴板）可以在配置里切换。

入口文件怎么写

建个目录跑mkdir clip-copy && cd clip-copy && git init，然后写plugin/init.lua——WezTerm 的加载器只认这一个约定：该文件必须返回一张包含apply_to_config的表。

local plugin = {} -- WezTerm 启动时调用这个唯一入口，config 是配置构建器 function plugin.apply_to_config(config, opts) opts = opts or {} -- 复制目的地：Wezterm 是终端缓冲区，Clipboard 是系统剪贴板 local dest = opts.clipboard or 'Wezterm' table.insert(config.keys, { key = 'C', mods = 'CTRL|SHIFT', action = wezterm.action.CopyTo(dest), }) end return plugin

怎么验证快捷键生效

在配置里用file://URL 引用本地目录：

local clip = wezterm.plugin.require 'file:///home/you/projects/clip-copy' clip.apply_to_config(config, { clipboard = 'Clipboard' })

启动后选中一段文本，按 Ctrl+Shift+C，再到别的窗口粘贴——能贴出来，说明这条 WezTerm 快捷键配置已生效。不生效的话，先确认wezterm.plugin.list()里有没有这条记录，再对照 docs/config/keys.md 检查key/mods写法。

多模块插件：package.path 怎么修

问题：init.lua里require 'notify'找不到同目录的notify.lua，因为 Lua 搜索路径不包含插件的安装目录，这是多模块插件最常见的挂法。

修法：从wezterm.plugin.list()里找出本插件的plugin_dir，把它拼进package.path：

-- plugin/init.lua 顶部 local PLUGIN_URL = 'file:///home/you/projects/clip-copy' for _, entry in ipairs(wezterm.plugin.list()) do if entry.url == PLUGIN_URL then package.path = package.path .. ';' .. entry.plugin_dir .. '/plugin/?.lua' break end end local notify = require 'notify'

⚠️plugin_dir末尾的目录名是从 URL 编码出来的，所以千万别硬编码绝对路径，否则换台机器必挂。

本地开发循环：update_all 和 list 怎么用

改完代码不自动生效：本地仓库里的改动要先同步到运行时目录才有效。流程是：在 DebugOverlay 的 Lua REPL 里执行wezterm.plugin.update_all()，再重启 WezTerm 让配置重新加载，然后重复"验证"那一步。

查状态：wezterm.plugin.list()对每个插件返回三个字段——component（编码后的目录名）、plugin_dir（安装路径）、url（来源地址）。调试路径问题全靠它。

移除插件：配置里删掉require那行，再去运行时目录的plugins/下删掉对应文件夹（路径用list()查），留着的只是垃圾。

把插件交给别人用：交付前核对 3 点

默认分支就是交付面：加载器只克隆仓库的默认分支，update_all也只拉默认分支，所以别指望对方"钉版本"；需要稳定版就提醒对方自行切分支。

参数写进 README：apply_to_config(config, opts)第二个表支持哪些字段，对方没有任何旁路可以得知，README 不说就是黑盒。

入口契约别破坏：仓库里必须有plugin/init.lua，返回带apply_to_config的表，且仓库地址用 HTTPS 或 file 协议可拉取——三者缺一，对方那里第一行require就会报错。

最快的起步方式：找一个开源 WezTerm 插件把它 clone 下来通读plugin/init.lua，照它的目录结构改出你的第一版，比从空白文件开始省一半时间。

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