如何安装部署 Handy 离线语音转文字，并解决 8 个常见报错

【免费下载链接】Handy A free, open source, and extensible speech-to-text application that works completely offline. 项目地址: https://gitcode.com/GitHub_Trending/handy11/Handy

Handy 是一款免费开源、完全离线运行的语音转文字桌面应用：按住快捷键说话，语音就会被转录并粘贴到任意输入框，音频和文字全程留在你自己的电脑上。本文带你完成安装、源码构建、首次启动配置，并逐一修复新手最常碰到的 8 个问题。

动手之前：5 分钟环境自检

先花两分钟确认环境，能避开后面一半的坑。

类别	要求	快速检查
运行权限	麦克风权限；macOS 额外需要"辅助功能"权限（用于把文字粘贴进其他应用）	系统设置中查看
构建工具（仅源码构建需要）	Rust 稳定版 + Bun 包管理器 + 各平台的 Tauri 系统依赖	cargo --version、bun --version
Linux 桌面依赖	GTK3、WebKit2GTK、ALSA、Vulkan 等开发库，清单见 BUILD.md	pkg-config --exists gtk+-3.0 && echo ok
网络与空间	模型下载约 0.5–1.6 GB，磁盘至少预留 2 GB	浏览器能否正常访问下载站
Linux 文本输入工具	X11 装 xdotool，Wayland 装 wtype，用于把转录结果"敲"进目标应用	which xdotool

跑起来：从零到第一次启动

路径一：安装官方版本（推荐新手）

大多数人不需要自己编译，直接装发布版即可。

# macOS：通过 Homebrew 安装
brew install --cask handy

# Windows：通过 winget 安装
winget install cjpais.Handy

Linux 用户从项目的发布页下载 AppImage 或 deb 包，双击运行或 sudo dpkg -i 安装即可。装好后首次打开授予麦克风权限，配置快捷键，就可以试说了。

路径二：源码构建（需要改代码或定制时）

# 克隆仓库
git clone https://gitcode.com/GitHub_Trending/handy11/Handy
cd Handy

# Linux 以 Ubuntu/Debian 为例，按 BUILD.md 安装系统依赖
sudo apt install build-essential libasound2-dev pkg-config libgtk-3-dev libwebkit2gtk-4.1-dev libayatana-appindicator3-dev librsvg2-dev libgtk-layer-shell0 libgtk-layer-shell-dev cmake

# 安装前端依赖，然后启动开发模式
bun install
bun run tauri dev

要点说明：

• macOS Intel 芯片需要 brew install onnxruntime，并在启动时带上 ORT_LIB_LOCATION 和 ORT_PREFER_DYNAMIC_LINK=1 两个环境变量，详见 BUILD.md。
• Windows 除了 Visual Studio C++ 构建工具，还要把 CMake 和 Vulkan SDK 装好。
• 在 Arch 等滚动更新发行版上，AppImage 打包步骤可能失败（failed to run linuxdeploy），改用 bun run tauri build -- --bundles deb 只打 deb 包即可。

Linux 源码构建的产物不能直接运行裸二进制，src-tauri/target/release/handy 缺少托盘图标、音效、VAD 模型等资源文件。正确做法是解包构建出的 deb 再安装：

# 从 deb 包中提取并安装到系统
cd /tmp && ar x /path/to/Handy/src-tauri/target/release/bundle/deb/Handy_*_amd64.deb data.tar.gz && tar xzf data.tar.gz
sudo cp usr/bin/handy /usr/bin/ && sudo cp -a usr/lib/. /usr/lib/

第一次成功启动算什么样

开发模式下浏览器窗口加载出设置界面、系统托盘出现 Handy 图标，说明启动成功。进入 设置 → 通用，选一个麦克风和转录模型，按住快捷键说一句"hello"，能看到录音状态即为跑通。

首次启动：权限、模型与"起不来"

🔑

授予权限并做初始配置

启动后应用会引导你授予两个权限：麦克风（录音用）和辅助功能（把文字写回其他应用用，macOS 必给）。快捷键行为在设置里可选三种：Hold（按住录音）、Toggle（点按开关）、Auto（按住或点按均可）。

问题 1：模型下载卡住或失败

症状：设置 → 模型 页面里模型一直转圈，或提示下载失败。 原因：模型文件体积大，代理、防火墙或断网都会让自动下载中断。

修复：

1. 打开 设置 → 关于，复制"App Data Directory"路径（Linux 通常是 ~/.config/com.pais.handy/，macOS 是 ~/Library/Application Support/com.pais.handy/，Windows 是 %APPDATA%\com.pais.handy\）。
2. 在其中手动创建 models 目录，用浏览器把想要的模型下载到该目录：Whisper 系列是单个 .bin 文件（如 ggml-small.bin、whisper-medium-q4_1.bin），Parakeet 是 .tar.gz 压缩包，解压后目录名必须恰好是 parakeet-tdt-0.6b-v3-int8 这类格式。
3. 文件名不要改，放好后完全退出并重启 Handy。

验证：设置 → 模型 中，手动放的模型显示为"已下载"，选中后试录一句话有文字输出。

问题 2：Linux 启动崩溃或窗口出不来

症状：进程一闪就退、一直转圈不出窗口，或报 libgtk-layer-shell.so.0 加载失败。 原因：Handy 在 Linux 上链接了 gtk-layer-shell 库（负责录音悬浮窗），运行库缺失是启动失败的头号原因。

修复：

1. 安装对应发行版的运行库：Ubuntu/Debian 执行 sudo apt install libgtk-layer-shell0，Fedora 执行 sudo dnf install gtk-layer-shell，Arch 执行 sudo pacman -S gtk-layer-shell；已安装仍报错就重装一次。
2. 仍不行就用环境变量绕过悬浮窗初始化，改回普通置顶窗口：HANDY_NO_GTK_LAYER_SHELL=1 handy。
3. 若窗口能出但画面异常，再叠加 WEBKIT_DISABLE_DMABUF_RENDERER=1 handy（WebKit 渲染层兼容问题）。
4. 确认哪个变量有效后，把 Exec=env HANDY_NO_GTK_LAYER_SHELL=1 handy 写进桌面启动项或 shell 配置里长期生效。

验证：命令能正常弹出主窗口和托盘图标；启动终端不再打印 shared libraries 报错。

问题 3：转录成功但文字"贴"不进去

症状：Handy 里能看到转录结果，但目标应用（浏览器、编辑器）里什么都没有。 原因：Linux 上把文字写入其他应用依赖辅助工具，缺失时回退方案在部分桌面环境无效，Wayland 下尤其明显。

修复：

1. X11 会话安装 xdotool：sudo apt install xdotool。
2. Wayland 会话安装 wtype：sudo apt install wtype；两者都想用就装 dotool 并执行 sudo usermod -aG input $USER 后重新登录。
3. Ubuntu 26.04 起默认 Wayland 且 wtype 不可用，需要按 README 的说明安装 ydotool 并配置 systemd 服务。
4. 另外确认 设置 → 高级 里 Overlay Position 为 None（悬浮窗会抢焦点导致粘贴丢失），想听录音提示音就打开 Audio Feedback。

验证：在任意文本框触发转录，松开后文字直接出现在光标处。

问题 4：全局快捷键没反应

症状：设置的快捷键按了没反应，其他应用却能用同一组合键。 原因：Wayland 下系统级快捷键不归应用注册，必须由桌面环境接管；macOS 上含 fn（地球键）的组合只在苹果自家键盘上生效。

修复：

1. GNOME：设置 → 键盘 → 自定义快捷键，新增一条命令为 handy --toggle-transcription，绑定想要的组合键（如 Super+O）。KDE、Sway、Hyprland 同理，各自在自定义快捷键/配置文件里写 exec handy --toggle-transcription。
2. 不想动桌面环境就用信号方式，绑定 pkill -USR2 -n handy（它只是发信号，不会杀进程）。
3. macOS 用户把快捷键改成 ctrl/option/shift/command 加普通键的组合。

验证：在任意输入框按下绑定键，录音指示出现；再按一下停止并出文字。

问题 5：macOS 源码构建后权限一直"Waiting"

症状：本地构建安装后，应用提示等待辅助功能授权，勾了也没用。 原因：本地构建用的是 ad-hoc 签名，每次重新编译代码签名身份都会变，系统里旧的授权记录对不上号。

修复：

1. 把最终构建产物装到 /Applications/Handy.app，退出 Handy。
2. 执行 tccutil reset Accessibility com.pais.handy 清除过期的辅助功能记录（不影响麦克风等其他权限）。
3. 重新打开应用，按提示再次授权。

验证：授权后应用不再显示 Waiting，转录文字能正常写入其他应用。官方发布版通常不需要这一步。

问题 6：Windows 构建报路径过长（MSB3491 / FTK1011）

症状：transcribe-cpp-sys 阶段失败，提示路径超过 260 字符。 原因：Vulkan 着色器生成器的 CMake 目录嵌套太深，撞上 Windows 传统路径长度上限。

修复：

1. 新版 transcribe-cpp 已自动用短目录软链接规避，先确认依赖是新的。
2. 仍报错就把 Cargo 输出目录换到短路径：PowerShell 中执行 $env:CARGO_TARGET_DIR = "C:\h"，然后开新终端再 bun run tauri dev。

验证：编译继续推进，产物出现在 C:\h\release\ 下。

问题 7：Windows 打包阶段报 "program not found"

症状：编译到 Built application at: ...\handy.exe 后失败，提示签名命令找不到。 原因：tauri.conf.json 配置了只在发布 CI 环境存在的代码签名工具，本地开发用不上。

修复：

1. 日常开发直接用 bun run tauri dev，不走打包。
2. 只要可执行文件、不要安装器时用 bun run tauri build --no-bundle。

验证：命令完整跑完且 target\release\handy.exe 可正常启动。

问题 8：录音自己开始/中断（Linux 老版本）

症状：Handy 隔几分钟自己开始录音，或说到一半被切断。 原因：0.9.4 及更早版本监听 SIGUSR1 作为遥控信号，而 WebKitGTK 内部正好用这个信号做垃圾回收，于是被误当成热键。

修复：

1. 升级到最新发布版。
2. 把之前绑定的 pkill -USR1 -n handy 换成 handy --toggle-post-process——新版 Linux 已不再监听该信号，旧绑定还可能直接崩掉应用。

验证：静置半小时无自启录音；带后处理的开关由 CLI 命令正常触发。

进阶与维护：性能、日志、升级和备份

🔧

选模型就是调性能

Whisper 系列（Small/Medium/Turbo/Large）在有 GPU 的机器上最快，但部分 Windows/Linux 环境偶发崩溃；CPU 较老或没有 GPU 时选 Parakeet V3——纯 CPU 优化、自动识别语言，中端硬件约 5 倍实时速度。

日志与调试模式

• 全局按 Ctrl+Shift+D（macOS 为 Cmd+Shift+D）进入调试模式，界面会出现实时日志和诊断项。
• 文件日志在 设置 → 调试 → 日志目录，点击"打开"直接定位；核心音频与推理逻辑见 src-tauri/src/managers/，设置页面对应 src/components/settings/debug/。
• 提 bug 时附上：版本、操作系统、CPU/GPU 型号、复现步骤和调试日志。

遥控与自动化

handy --toggle-transcription   # 开关录音
handy --toggle-post-process    # 开关"录音+后处理"
handy --start-hidden --no-tray # 开机静默自启
handy --help                   # 查看全部参数

这些参数在所有平台可用，也是 Wayland 下做快捷键绑定的标准姿势。

升级与备份

• 升级走应用内更新器，更新包签名公钥在 src-tauri/tauri.conf.json 里可核对；手动装新包前建议整体退出旧进程。
• 备份两样东西就够：配置文件 settings_store.json（在 App Data 目录内）和 models 目录。换机后原样拷回，模型不用重新下载。

常见问题速查

现象	最可能原因	处理
说话后没有任何文字	麦克风选错或权限未给	设置里切换麦克风，重新授权
macOS 蓝牙耳机录音时音量变小	蓝牙切成了双向音频	输出设备保持耳机，麦克风选 Mac 内置/外接
转录文字很长，CPU 占用高	模型太大	换 Parakeet V3 或 Whisper Small
Wayland 下按快捷键无反应	系统快捷键被桌面环境接管	按上文在 GNOME/KDE 里绑定 handy --toggle-transcription

社区与贡献

项目目前处于功能冻结期，修 bug 和稳定性优先，新功能 PR 需要社区支持才会被考虑，细节见 CONTRIBUTING.md。新手可以认领带 good first issue 标签的问题，提问可走项目的 Discussions 或 Discord。参与前请先搜索已有 issue 和 PR，避免重复劳动。

关键词

• 核心关键词：Handy 离线语音转文字、Handy 本地语音识别
• 长尾关键词：Handy 安装教程、Handy 源码编译构建、Handy 模型手动下载、Handy Linux gtk-layer-shell 启动失败、Handy Wayland 快捷键配置、Handy macOS 辅助功能权限、Handy 日志目录位置

【免费下载链接】Handy A free, open source, and extensible speech-to-text application that works completely offline. 项目地址: https://gitcode.com/GitHub_Trending/handy11/Handy