WaveTerm 自定义小部件快速上手：三步把常用命令变成一键启动
【免费下载链接】wavetermAn open-source, AI-integrated, cross-platform terminal for seamless workflows项目地址: https://gitcode.com/GitHub_Trending/wa/waveterm
你有多久没嫌烦地重输过 speedtest，或者手动敲fish开一个新的 shell？WaveTerm 的自定义小部件（widget，即窗口侧边栏里那些点开即用的小图标）功能，可以把任意常用命令钉在 widget bar 上，点一下就跑，省掉反复输入和翻找标签页的工夫。
🎯 先看效果：widget bar 能做什么
WaveTerm 窗口左侧有一列小图标，官方叫它 widget bar，默认内置了终端、文件、网页、AI、系统监控五个。
加上自定义小部件之后，同一列图标就能变成你的"快捷方式栏"，每个图标对应一个命令或一个页面：
三步加上你的第一个自定义小部件
- 用编辑器打开
<WAVETERM_HOME>/config/widgets.json——这是所有小部件定义的唯一入口。 - 把下面这段 JSON 复制进文件（作为某个键值对，注意与已有内容用逗号隔开），保存。
- 重启 WaveTerm——widget bar 上多出一个仪表盘图标，点它直接跑一次网络测速。
"speedtest": { "icon": "gauge-high", "label": "speed", "blockdef": {"meta": {"view": "term", "controller": "cmd", "cmd": "speedtest-go --unix"}} }原理一句话就能说清：blockdef.meta里声明"打开一个终端视图，执行这条命令"，剩下的键（图标、标签、颜色）只影响显示。完整字段表在 docs/docs/customwidgets.mdx，不用死记，用到再查。
配置文件藏在哪，示例去哪抄
<WAVETERM_HOME>是 WaveTerm 的主目录，config/widgets.json在首次使用小部件功能时生成；如果没有这个文件，直接新建一个、从{}开始往里加也行。
想照抄一个规范写法？默认小部件的定义就放在仓库的 pkg/wconfig/defaultconfig/widgets.json 里，键名是defwidget@terminal、defwidget@files这类。有两个顺手的操作：
- 不想要的默认图标：在自己文件里把同名键设为
null即可移除。 - 想换成"常驻会话"而非"跑一次就结束"的命令：把
controller改成"shell"，再用term:localshellpath指向 shell 路径（比如 fish、pwsh）。
🧩 自定义小部件不生效，先查这几个坑
很多人会问："JSON 明明存了，怎么图标没出来？"高频原因有四个：
- JSON 语法断了：少一个逗号或引号，整个文件解析失败，所有图标都不变。存盘前用任意 JSON 校验工具过一遍。
- 图标名写错：
icon用的是 Font Awesome 的图标名，写错不会报错，只是图标渲染不出来。 - 命令路径找不到：widget 里的命令和终端行为一致，
fish若不在系统 PATH 里，就要写全路径，如/usr/local/bin/fish。 - 改错了文件：只有你自己
config目录下的widgets.json生效；去改仓库里pkg/wconfig/defaultconfig/下的文件，打包出来的应用根本不会读它。
另外view的值只能是term、web、sysinfo之一，填错是最常见的解析失败原因。
想一起改进它
遇到小部件不生效、或者想加某个现成功能，直接在官方仓库提一个 Issue，附上widgets.json片段和现象描述，就是最有价值的反馈。项目协作方式（什么改动受欢迎、什么要先讨论）写在 CONTRIBUTING.md 里，几分钟能看完。
更多配置细节可以翻官方文档站，仓库的社区讨论区则是遇到怪问题时最多人搭把手的地方。
【免费下载链接】wavetermAn open-source, AI-integrated, cross-platform terminal for seamless workflows项目地址: https://gitcode.com/GitHub_Trending/wa/waveterm
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
