企业官网建设流程全解析

WezTerm 插件完全指南：3 分钟装好第一个插件，再亲手写一个

【免费下载链接】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 源码。WezTerm 插件就是干这个的：在配置文件里加几行 Lua，就能把终端的外观和行为改到你满意为止。

这篇指南带你走完一条完整的路：先 30 秒搞懂插件是什么，再花 3 分钟装好第一个插件，然后抄配方做配置、亲手写一个自己的，最后把新手最常踩的坑一次性排掉。

30 秒看懂：WezTerm 插件到底是什么

别想复杂。一个 WezTerm 插件，本质就是三样东西：

• 一个 Lua 文件包。不用编译，不用装依赖。
• 一个 Git 仓库。你把仓库 URL 交给 WezTerm，它自动克隆到运行时目录的plugins/下。
• 一个核心函数。每个插件都必须导出apply_to_config(config, ...)，启动时 WezTerm 把配置对象交给你，你想改什么就在里面改什么。

整条链路一句话讲完：你在配置文件里写wezterm.plugin.require 'URL'→ WezTerm 克隆仓库 → 启动时调用插件的apply_to_config，你的配置被改写好。

插件系统自带三个管理函数，覆盖了日常 90% 的操作：

3 分钟跑通：装好你的第一个 WezTerm 插件

不需要任何环境准备，三步就能见效：

1. 打开配置文件。Linux 上通常是~/.config/wezterm/config.lua，没有就新建一个。
2. 写入下面这几行，指向某个 Git 仓库里的插件：

local wezterm = require 'wezterm' local a_plugin = wezterm.plugin.require 'https://git.example.com/owner/repo' local config = wezterm.config_builder() a_plugin.apply_to_config(config) return config

3. 重启 WezTerm（或触发配置重载）。插件对配置做的修改立即生效。

两个细节先记一下：

• 首次加载时，WezTerm 会克隆仓库并检出默认分支（一般是main）。之后再require同一个插件不会自动更新。
• URL 只接受https和file两种协议，git@那种 SSH 地址不行。

配置即玩法：3 个可直接抄的 WezTerm 插件配方

配方一：最简加载

就是上一节的写法：require一个 URL，调一次apply_to_config(config)。插件不接参数时，这已经够了。

配方二：带参数表加载

大多数插件支持自定义，方式是把一张 Lua table 作为第二个参数传进去：

local myPluginConfig = { enable = true, location = 'right' } a_plugin.apply_to_config(config, myPluginConfig)

具体能传哪些字段，看那个插件仓库里的 README。这是你"调口味"的主要入口。

配方三：加载本地插件

开发或魔改插件时用这个：

local a_plugin = wezterm.plugin.require 'file:///home/user/projects/myPlugin'

注意file:///后面是绝对路径。后面写插件、改现有插件都从这一行开始。

插件装完之后，想核对装了什么、装在哪，随时用wezterm.plugin.list()查一遍。

动手造轮子：写一个自己的 WezTerm 插件

最小的插件就一个文件。四步走：

1. 建目录结构。插件仓库里必须有plugin/子目录，入口放在其中的init.lua：

my-wezterm-plugin/ └── plugin/ └── init.lua

2. 写init.lua。它必须return一个模块，模块里导出apply_to_config：

local plugin = {} function plugin.apply_to_config(config, opts) opts = opts or {} -- 在这里改配置，比如换个配色 config.color_scheme = opts.color_scheme or 'Dracula' end return plugin

apply_to_config至少要接收 config 这一个参数，额外的参数你自己定义。

3. 在配置文件里用file:///引用它：

local my_plugin = wezterm.plugin.require 'file:///home/user/projects/my-wezterm-plugin' my_plugin.apply_to_config(config, { color_scheme = 'Tomorrow Night' })

4. 记住：改完本地代码要手动同步。在 Lua REPL 里跑一次wezterm.plugin.update_all()，WezTerm 才会把你的最新改动同步进运行时目录。

插件不止一个 Lua 文件时怎么办

当init.lua需要require同目录的其他模块，Lua 的package.path默认不认识插件的位置，需要手动加。用wezterm.plugin.list()查到插件目录后这样拼：

local function findPluginPackagePath(url) local sep = package.config:sub(1, 1) == '\\' and '\\' or '/' for _, v in ipairs(wezterm.plugin.list()) do if v.url == url then return v.plugin_dir .. sep .. 'plugin' .. sep .. '?.lua' end end end package.path = package.path .. ';' .. findPluginPackagePath('file:///home/user/projects/my-wezterm-plugin')

这段直接照抄官方文档的写法即可。

避坑清单：这 5 个坑最容易被你踩

1. 仓库更新了，终端里却没变化。require只在首次使用时克隆，之后不会自动更新。跑一次wezterm.plugin.update_all()，或者删掉该插件目录让它重新克隆。
2. 想卸载插件，只删了配置里那行 require。配置行删了，克隆下来的目录还在。用wezterm.plugin.list()查到对应目录，把那个文件夹删掉才算移除。
3. 改了本地插件却没生效。运行时目录里放的是副本，不是你的源码。每次改动后都要跑update_all()同步。
4. 多模块插件里require自己的文件报错。就是package.path没配，回看上一节的代码。
5. 报错了但不知道去哪看。按Ctrl+Shift+L打开 Debug Overlay，能看到最近的日志，还内置 Lua REPL——上面那些插件命令都可以在里面跑。想看更多日志，用WEZTERM_LOG=debug wezterm启动。

资源清单：下一步往哪走

先把这几份文档收进书签：

• 插件官方文档：docs/config/plugins.md，本文所有用法的原始出处
• 三个 API 的详细说明：require、list、update_all
• 排错入口：docs/troubleshooting.md
• 配置思路参考：docs/recipes/workspaces.md

然后给自己排个顺序：

1. 今天就装一个插件，把require→ 重启 → 生效的链路走熟
2. 用配方二改一次参数表，体验"调口味"
3. 找一个现成插件，用file://拉到本地，试着只改一行代码再update_all()

插件系统的门槛就在"一个 Lua 文件 + 一个函数"，写完第一个之后，你会发现剩下的都是熟练度问题。

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