Handy 离线语音转文字完整排障指南编译报错、模型下载卡住、快捷键失灵怎么办【免费下载链接】HandyA free, open source, and extensible speech-to-text application that works completely offline.项目地址: https://gitcode.com/GitHub_Trending/handy11/HandyHandy 是一款完全离线运行的语音转文字桌面应用按住或点按快捷键说话识别结果直接打进你当前正在用的任意输入框音频全程不出本机。它用 Tauri React 做界面Rust 后端驱动 Whisper 或 Parakeet 模型做本地推理。如果你是直接装预编译包的用户可能永远用不到这篇文章如果你需要自己编译或者装完遇到问题下面按构建 → 首次运行 → 日常使用三个阶段把常见的坑一次讲清。动手之前先确认你缺什么从源码构建 Handy 的依赖不少但先别全装一遍花一分钟对照下表确认缺口再补依赖哪个平台需要用途Ruststable 工具链全平台编译后端Bun全平台前端依赖 调用 Tauri CLIGTK3 / WebKit2GTK 4.1 / gtk-layer-shell 开发库Linux窗口与录音覆盖层ALSA 开发库Linux音频采集C Build Tools CMake Vulkan SDKWindows编译 GPU 后端与着色器Xcode Command Line ToolsIntel 机器另需 Homebrew 的 onnxruntimemacOS编译与推理运行时完整清单见仓库里的 BUILD.md。确认环境只需要两条命令rustc --version bun --version # 缺哪个装哪个 pkg-config --modversion gtk-3.0 webkit2gtk-4.1 libgtk-layer-shell-0 # 仅 Linux环境齐了就开始构建git clone https://gitcode.com/GitHub_Trending/handy11/Handy cd Handy bun install bun tauri dev这一步最容易卡住先别慌——构建阶段的报错基本都是缺东西而不是坏了。构建阶段报错基本都指向缺失的依赖Bun 未安装一条命令装好bun: command not found说明前端依赖根本没法装。执行curl -fsSL https://bun.sh/install | bash然后重开终端用bun --version确认版本号出现即可。注意装完要新终端旧 shell 里没有 PATH。Linux 编译报 linker 或 GTK/WebKit 缺失症状可能是linker cc not found也可能是failed to run custom build command后面跟着一堆找不到 gtk 库的日志。前者是缺 C 工具链sudo apt install build-essential后者是缺 Tauri 的平台库。Ubuntu/Debian 上一条命令补齐sudo apt install build-essential libgtk-3-dev libwebkit2gtk-4.1-dev \ libayatana-appindicator3-dev librsvg2-dev libgtk-layer-shell-dev \ libasound2-dev pkg-config libssl-dev验证方式很直接重新bun tauri dev能进到前端页面加载就过了。Windows 构建报 MSB3491 / FTK1011 路径错误这三个错误码看起来吓人其实是同一个根因Windows 的 260 字符路径上限被 Vulkan 着色器生成的嵌套目录撑爆了。transcribe-cpp0.1.3 之后会自动用 NTFS junction 绕开所以先升级依赖再试。如果仍然失败junction 被安全策略挡住把编译输出目录改短$env:CARGO_TARGET_DIR C:\h在新终端里重新bun run tauri dev产物会出现在C:\h\release\...。Windows 编译成功、打包却报 program not found日志停在Built application at: ...\handy.exe之后报failed to bundle projectprogram not found说明卡的是代码签名步骤——src-tauri/tauri.conf.json 里配置的signCommand只在官方发布 CI 里存在。本地开发不需要签名bun run tauri build --no-bundle滚动发行版上 AppImage 打包失败Arch、Manjaro 这类系统上打包到 AppImage 步骤报failed to run linuxdeploy是 linuxdeploy 自带的 strip 太老处理不了新工具链的库。二进制、deb、rpm 其实都正常直接跳过 AppImagebun run tauri build -- --bundles deb再用 BUILD.md 里Linux Install (from source)一节的 deb 解包方法安装即可。macOS Intel 机器构建失败缺 ONNX RuntimeIntel Mac 没有预编译的 ONNX Runtime需要 Homebrew 装好后显式指向它brew install onnxruntime ORT_LIB_LOCATION$(brew --prefix onnxruntime)/lib ORT_PREFER_DYNAMIC_LINK1 bun run tauri devApple Silicon 机器不受此影响。编译到一半被系统杀掉Killed: cc1内存不够时 Rust 的并行编译最容易把机器压死。降并发即可cargo build --release --jobs2同时在 BUILD.md 提到的发布优化参数里配合lto thin使用。如果连开发机内存都紧张说明你更适合直接用预编译包。首次运行阶段模型、启动崩溃与权限模型下载卡住或失败手动放置到 models 目录Handy 首次启动会下载语音识别模型代理或受限网络下这一步经常卡死。手动方案先确认数据目录macOS 是~/Library/Application Support/com.pais.handy/Linux 是~/.config/com.pais.handy/Windows 是%APPDATA%\com.pais.handy\在其下建models文件夹然后从其他设备把模型拷进来。Whisper 的.bin文件、Parakeet 的.gguf文件直接丢进目录就行Parakeet 的.tar.gz解压后目录名必须精确匹配如parakeet-tdt-0.6b-v3-int8文件也不许改名。下载源地址在 README.md 的Manual Model Installation一节里列得清清楚楚浏览器里都能直接打开。 放好后重启 HandySettings → Models 里对应模型显示Downloaded就说明识别成功了选它测一句转录即可。Linux 启动崩溃libgtk-layer-shell.so.0 找不到启动就闪退、报error while loading shared libraries: libgtk-layer-shell.so.0这是运行时包没装构建时装的是 dev 包运行时要的是 runtime 包。按发行版补上sudo apt install libgtk-layer-shell0 # Ubuntu/Debian sudo dnf install gtk-layer-shell # Fedora sudo pacman -S gtk-layer-shell # Arch装完再启动能进主界面就解决了。窗口不显示或偶发崩溃试两个环境变量某些 GPU/驱动组合下 WebKitGTK 的 DMA-BUF 渲染器会让窗口渲染失败部分合成器下 gtk-layer-shell 又和覆盖层打架。两个开关各试一次HANDY_NO_GTK_LAYER_SHELL1 handy WEBKIT_DISABLE_DMABUF_RENDERER1 handy哪个生效就把它写进你的启动方式shell profile 或.desktop文件的Exec行前缀。macOS 权限麦克风与辅助功能装完首次运行会依次请求麦克风和辅助功能权限拒绝过一次的话要去系统设置 → 隐私与安全性里重新勾选。如果你是本地重新编译过再安装的本地构建用 ad-hoc 签名旧的辅助功能授权记录会变成僵尸状态应用停在等待授权界面。清掉重授即可tccutil reset Accessibility com.pais.handy open /Applications/Handy.app这条命令只清辅助功能一项不会动麦克风授权。日常使用阶段快捷键、覆盖层与自己动的录音Wayland 下全局快捷键要自己绑Wayland 出于安全考虑不让应用随意注册全局热键所以 Handy 在 Wayland 下不替你管这件事得由桌面环境来绑。GNOME/KDE 在自定义快捷键里把命令填成handy --toggle-transcription就行tiling 窗口管理器则是写进配置bindsym $modo exec handy --toggle-transcriptionX11 下不需要这些应用自己注册快捷键。另外 Linux 上文本粘贴依赖辅助工具X11 装xdotoolWayland 装wtypedotool两者通吃但要把用户加进input组不装的话会退回 enigoWayland 下兼容性很差。录音自己开始或中途被掐断SIGUSR1 的坑如果你升级前绑过pkill -USR1 -n handy来切换带后处理转录升级后务必删掉这个绑定。WebKitGTK 内部用 SIGUSR1 协调 JS 垃圾回收旧版本把它当热键于是每隔几分钟幻影录音一次新版本已不再监听这个信号但绑定留着的话信号会直接打到 WebKit 内部处理器上可能直接把应用打崩。带后处理的切换用handy --toggle-post-process或pkill -USR2 -n handy注意 USR2 只发信号、不会杀进程替代。转录结果没粘进目标窗口Linux录音覆盖层在部分 Linux 合成器下会抢焦点导致粘贴落到错误的位置或者干脆失败。所以 Linux 默认关闭覆盖层Overlay Position: None。如果你开了它又遇到粘不进去回 Settings → Advanced 把Overlay Position设为None同时打开Audio Feedback用声音确认录音状态。老版本或从其他平台导入设置的用户可能需要手动改这一项升级后记得检查一下。快捷键行为不符合预期Auto / Hold / Toggle0.9.7 起新装用户默认是 Auto 模式按住说话松开停止点按一下开始、再按一下停止。老用户升级后保留原行为。想要哪种去 General → Shortcut Behavior 里切换fn / Globe 键在第三方键盘上永远没反应这是硬件限制不是 bugfn走的是 Apple 的厂商私有 HID 通道第三方键盘的 Fn 在固件里就被消化了系统根本收不到事件Handy 无键可听。在 Apple 键盘和第三方键盘之间切换的话改用ctrl/option/shift/command加普通键组合的快捷键。macOS 上蓝牙耳机录音时音质变差蓝牙耳机录音时蓝牙会切到双向音频模式播放音质和音量暂时下降。想避开就在 Handy 的麦克风设置里选 Mac 自带或外接麦克风输出仍走耳机。快速自检表症状最快定位动作bun: command not found装 Bun 后重开终端bun --version验证linker cc not found/ GTK、WebKit 缺失对照开头依赖表补齐系统包Windows 报 MSB3491 / FTK1011升级 transcribe-cpp ≥ 0.1.3仍报错就设短的CARGO_TARGET_DIR编译成功、打包报program not foundbun run tauri build --no-bundle跳过签名滚动发行版 AppImage 打包失败--bundles deb改用 deb 安装启动报libgtk-layer-shell.so.0装发行版对应的运行时包Wayland 下窗口异常 / 崩溃依次试HANDY_NO_GTK_LAYER_SHELL1、WEBKIT_DISABLE_DMABUF_RENDERER1模型下不动手动下载到 models 目录重启后看 Settings → Models转录没粘进目标窗口LinuxOverlay Position 设为 None录音自己开始/被掐断升级版本并删除pkill -USR1绑定Wayland 快捷键无反应在桌面环境绑handy --toggle-transcription下一步建议不打算改源码就别从源码构建。直接装官方预编译包能绕开这里 80% 的问题留到确实需要定制时再回来按图施工。提 issue 前先备好三样东西系统版本与桌面环境、复现步骤、日志。日志文件名就是handy在应用数据目录的logs子目录下数据目录路径在 Settings → About 里能看到需要更多细节时按CtrlShiftDmacOS 为CmdShiftD开调试模式再复现一次。升级后检查旧绑定和设置。特别是 Linux 用户删掉所有pkill -USR1的键位确认覆盖层位置和粘贴方式符合当前版本的默认行为。【免费下载链接】HandyA free, open source, and extensible speech-to-text application that works completely offline.项目地址: https://gitcode.com/GitHub_Trending/handy11/Handy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考