fuzzel：为 Wayland 打造的轻量级应用启动器 #
fuzzel 是什么？ #
Fuzzel 是一款运行在 Wayland 环境下的轻量级应用启动器（Launcher），同时也是一个可直接替代 dmenu 的通用文本选择器。它由开发者 dnkl 以 C 语言编写，托管于 Codeberg，采用 MIT 开源许可证发布。
它从 XDG 桌面条目中读取已安装应用，弹出一个小巧的输入框，用户输入关键词后即可通过模糊匹配快速定位并启动程序；配合 --dmenu 模式，它还能从标准输入读取候选项，被脚本、Shell 管道和各类自动化工具调用。对于使用 Sway、River、Wayfire 等 wlroots 系合成器的 Linux 用户来说，Fuzzel 解决了传统 dmenu/rofi 在 Wayland 下兼容性差、依赖体积大、渲染不够原生的问题，用极低的资源占用换来毫秒级的启动体验。
fuzzel 有哪些亮点特色？ #
-
Wayland 原生实现：直接基于 Wayland 客户端库与 Cairo/Pango 渲染，运行在支持
wlr-layer-shell协议的合成器上（如 Sway、River、Wayfire、Hyprland 等），不经过 XWayland，窗口定位、缩放与键盘输入都更加可靠。 -
不依赖 GTK / Qt：整个程序只依赖基础的 Wayland、Cairo、Pango、libxkbcommon、fcft 等底层库，没有庞大的图形框架拖累，安装体积与常驻内存都极小，启动几乎“瞬开”。
-
fzf 风格模糊匹配：输入“ffx”也可以匹配到“Firefox”，并按匹配质量自动排序，无需精确输入完整名称；匹配模式与模糊匹配的阈值可通过命令行或配置文件调整。
-
dmenu 兼容模式：使用
fuzzel --dmenu可从 STDIN 读取候选项列表，把选中的一行输出到 STDOUT，可直接替换脚本中的dmenu，与 Sway 的menu命令、Shell 管道、密码管理器等工具无缝衔接。 -
高度可配置的外观：通过
~/.config/fuzzel/fuzzel.ini可自定义字体、字号、行高、字间距、窗口宽度、内边距与外边距、提示符、配色方案等，轻松融入不同的桌面主题风格。 -
图标与多显示器支持：支持按照 XDG 图标主题显示应用图标，并可设置图标尺寸；窗口会出现在当前聚焦的输出上，也支持在多显示器环境下指定显示位置，并适配 HiDPI 高分屏缩放。
-
轻量而完整的命令行接口：提供
--prompt、--lines、--width、--font、--terminal、--no-icons、--match-mode、--log-level等参数，无需修改配置文件也能临时改变行为，方便写进快捷键绑定与脚本。 -
开源免费，活跃维护：MIT 许可证，源码公开、可自行编译审计；项目在 Codeberg 上持续迭代，本文档对应的源码包版本为 1.15.0（来自下载信息）。
免费下载 fuzzel #
以下为官方提供的源码安装包与签名文件，点击链接即可下载。源码包需要在本地自行编译安装，具体步骤见下文“fuzzel 如何安装？”。
| 文件名 | 描述 | 大小 | 下载 |
|---|---|---|---|
| fuzzel-1.15.0.tar.gz | fuzzel 1.15.0 源码压缩包，需自行编译 | 503.8 KB | 夸克网盘 |
| fuzzel-1.15.0.tar.gz.sig | 对应源码包的 GPG 签名文件，用于校验完整性与来源 | 584 B | 夸克网盘 |
提示：各 Linux 发行版的官方仓库通常已收录 fuzzel，可直接用包管理器安装（版本号可能与本页源码包不同，具体以发行版仓库为准，官网未逐一说明）。
fuzzel 如何使用？ #
Fuzzel 的使用方式非常直觉，核心只有“唤出 → 输入 → 回车”三步。以下以 Sway 等 wlroots 合成器为例：
-
绑定快捷键：在合成器配置文件中为 fuzzel 绑定一个快捷键。例如在 Sway 的
~/.config/sway/config中加入：bindsym $mod+d exec fuzzel保存后重新加载配置（
swaymsg reload），按下Super+D即可唤出启动器。 -
输入关键词筛选：窗口出现后直接键入程序名的一部分，例如输入
fire或ffx，列表会根据模糊匹配实时过滤并按相关度排序，匹配到的字符会高亮显示。 -
选择并启动：用
↑/↓（或Tab/Shift+Tab）在候选项中移动，按Enter启动选中的程序；按Esc或Ctrl+G取消本次操作。 -
作为 dmenu 使用：把候选内容通过管道传给它即可：
printf '选项一\n选项二\n选项三\n' | fuzzel --dmenu选中的那一行会输出到标准输出，可以继续交给其他命令处理，例如：
choice=$(ls ~/Documents | fuzzel --dmenu -p "打开文件: ") -
常用命令行长选项（无需改配置文件即可临时生效）：
-p, --prompt="文本"：自定义输入框左侧的提示符；-l, --lines=N：设置一次最多显示多少行候选项；-w, --width=N：设置窗口宽度；-f, --font="字体:size=12"：临时指定字体；-T, --terminal=终端名：指定启动终端类程序时使用的终端模拟器；--no-icons：本次运行不显示图标；--log-level=info|warning|error：调整日志输出级别，便于排查问题。
-
持久化配置：创建
~/.config/fuzzel/fuzzel.ini，把常用设置写进[main]段，例如（选项名示例，实际可用项请以man fuzzel.ini为准）：[main] font=monospace:size=12 terminal=foot lines=10 width=30 horizontal-pad=20 vertical-pad=20 inner-pad=10 line-height=20 icons-enabled=yes icon-theme=Papirus也可用
fuzzel --config=/path/to/fuzzel.ini指定非默认位置的配置文件。
fuzzel 的常见问题？ #
Fuzzel 和 dmenu、rofi 有什么区别？
dmenu 与 rofi 主要面向 X11，在 Wayland 下通常需要借助 XWayland 才能运行，窗口定位、缩放和键盘处理都不够原生。Fuzzel 是纯 Wayland 客户端，不依赖 GTK/Qt，体积和内存占用更小；同时它保留了 --dmenu 兼容模式，脚本迁移成本很低。若需要更复杂的脚本插件体系，rofi 的生态仍然更庞大。
为什么在 X11 会话下运行不了？
Fuzzel 是 Wayland 专用程序，需要合成器支持 wlr-layer-shell 协议来创建面板式窗口。X11 环境下没有对应的 Wayland 协议支持，无法启动；请改用 dmenu、rofi 等 X11 工具，或切换到 Wayland 会话。
输入中文或非拉丁字符时列表没有结果怎么办？
请确认系统已安装可渲染该字符集的字体，并在配置中把 font 指向包含对应字形的字体（可配置字体回退）。此外，应用名称取自 .desktop 文件的 Name 字段，若某个程序在列表中名称是英文，用英文关键词搜索才更容易命中。
应用图标不显示或显示为空白方块？
通常有两个原因：一是系统未安装 XDG 图标主题，或 icon-theme 指定的主题名称不存在；二是图标主题缺少对应尺寸的图标文件。可尝试安装常见图标主题（如 Papirus、Adwaita），或在配置中调整 icon-theme 与图标尺寸，也可以直接用 --no-icons 关闭图标显示。
fuzzel 启动后出现在错误的显示器上怎么办？
默认情况下窗口会出现在当前聚焦的输出上。在多显示器环境中，可以通过配置文件或命令行参数指定使用哪一个输出，确保启动器出现在你期望的屏幕上；具体选项名称以 man fuzzel 与 man fuzzel.ini 为准（官网未在本页说明）。
回车后程序没有启动，或者退出码不是 0？
Fuzzel 的退出码有明确含义：正常选中并启动通常返回 0，用户按 Esc 取消返回 1，出现其他错误返回 2。若脚本中依赖退出码判断，请按此约定处理。程序无法启动时，可用 --log-level=info 查看详细日志，确认是 .desktop 文件缺失、Exec 路径错误还是终端未配置。
fuzzel 如何安装？ #
Fuzzel 目前仅支持 Linux 平台，且只能运行在支持 wlr-layer-shell 协议的 Wayland 合成器上。推荐优先使用发行版仓库安装，也可从源码包编译。
一、通过发行版仓库安装（推荐） #
-
Arch Linux / Manjaro：
sudo pacman -S fuzzel -
Fedora：
sudo dnf install fuzzel -
Debian / Ubuntu：
sudo apt update sudo apt install fuzzel -
Alpine Linux：
sudo apk add fuzzel -
Void Linux：
sudo xbps-install -S fuzzel -
openSUSE：
sudo zypper install fuzzel -
Nix / NixOS：
nix-env -iA nixpkgs.fuzzel或在 NixOS 配置中加入
programs.fuzzel.enable = true;（具体属性以当前 nixpkgs 为准）。
不同发行版仓库中收录的版本号可能与本页源码包不一致，请以发行版仓库显示为准（官网未逐一说明）。
二、从源码编译安装 #
-
安装编译依赖：需要 C 编译器、Meson、Ninja，以及 Wayland 客户端库、Wayland protocols、Cairo、Pango、libxkbcommon、fcft、tllist 等开发包（文档生成可选 scdoc）。以 Debian/Ubuntu 为例：
sudo apt install build-essential meson ninja-build pkg-config \ libwayland-dev wayland-protocols libcairo2-dev libpango1.0-dev \ libxkbcommon-dev libfcft-dev libtllist-dev scdoc -
解压源码包：
tar -xzf fuzzel-1.15.0.tar.gz cd fuzzel-1.15.0 -
（可选）校验签名：如果你下载了
.sig签名文件，可用 GPG 验证源码包来源与完整性。 -
配置构建目录：
meson setup --buildtype=release build -
编译：
ninja -C build -
安装到系统：
sudo ninja -C build install -
验证：
fuzzel --version能正常打印版本号即安装成功。若要在不安装的情况下试运行，可直接执行
./build/fuzzel。
三、安装后的必要配置 #
- 确保当前会话是 Wayland 会话（
echo $XDG_SESSION_TYPE应输出wayland）。 - 在合成器配置中为 fuzzel 绑定快捷键（见“如何使用”一节）。
- 如需个性化外观，创建
~/.config/fuzzel/fuzzel.ini。
fuzzel 如何卸载？ #
卸载方式取决于你当初的安装途径。
一、包管理器安装的卸载 #
-
Arch Linux / Manjaro：
sudo pacman -Rns fuzzel -
Fedora：
sudo dnf remove fuzzel -
Debian / Ubuntu：
sudo apt remove fuzzel如需同时清除自动安装的依赖：
sudo apt autoremove。 -
Alpine Linux：
sudo apk del fuzzel -
Void Linux：
sudo xbps-remove -R fuzzel -
openSUSE：
sudo zypper remove fuzzel -
Nix：
nix-env -e fuzzel
二、源码编译安装的卸载 #
如果你是按上文用 Meson 安装的，且 build 目录仍然保留，可直接执行：
sudo ninja -C build uninstall
若 build 目录已被删除，卸载信息随之丢失，需要手动清理安装文件，通常包括 /usr/local/bin/fuzzel、/usr/local/share/man/man1/fuzzel*、/usr/local/share/fuzzel/ 等路径（实际路径取决于安装时设置的 --prefix，可用 which fuzzel 辅助定位）。删除前建议确认这些文件确实属于 fuzzel。
三、清理残留配置与缓存 #
包管理器与 ninja uninstall 一般不会删除用户目录下的个人配置和缓存，如需彻底清理，可手动删除：
~/.config/fuzzel/：主配置文件目录（含fuzzel.ini）；~/.cache/fuzzel/：运行时缓存目录（若存在）。
此外，别忘了把合成器配置文件（如 Sway 的 ~/.config/sway/config）中绑定 fuzzel 的那一行快捷键删除或注释掉，避免留下无用的按键绑定。