Handy 离线语音转文字安装指南5 步从零到跑通 常见问题速查【免费下载链接】HandyA free, open source, and extensible speech-to-text application that works completely offline.项目地址: https://gitcode.com/GitHub_Trending/handy11/HandyHandy 是一款完全离线、跑在本机的语音转文字应用按住快捷键说话文字就自动贴进任意输入框全程不经过云端。这篇安装指南带你 5 步从零到跑通顺带把新手最容易卡住的几类报错一次讲清楚。先认识一下 HandyHandy 是一个跨平台桌面应用Windows、macOS、Linux 都能用底层是 Tauri——一个用 Rust 写后端、前端跑网页的轻量桌面框架。前端用 React 做设置界面后端用 Rust 处理录音、音频和模型推理。它先用 VAD语音活动检测通俗点说就是过滤掉你停顿时的静音再识别支持两类本地模型Whisper 系列有独显时能加速和更省资源的 Parakeet V3纯 CPU 就能跑。整个流程都在你电脑里完成录音、识别、贴字都不上传。上面这个浮层就是它干活的样子说话时文字实时流出来右下角能看到录音时长。按快捷键、松手出字、自动贴进当前光标处是它的全部核心。开工前30 秒检查你的电脑要自己编译而不是直接下安装包的话得先备好工具链。你只是装预编译版的话这部分可以跳过直接往下看 FAQ。三个必装工具Bun现代 JS 包管理器Handy 的前端靠它装依赖。按官网提示装好后确认能出版本号bun --versionRust后端语言和编译器装 latest stable 即可。装完确认一下cargo --version系统构建链就是 C/C 编译器加 make 这类基础工具。macOS 跑xcode-select --installWindows 装 Visual Studio Build Tools选“C 桌面开发”Linux 装build-essential。工具齐了就拉代码到本地git clone https://gitcode.com/GitHub_Trending/handy11/Handy后面所有命令都在这个目录里跑。各平台额外要装什么这些是 BUILD.md 里列的平台专属依赖按你的系统挑一份装就行LinuxTauri 需要 GTK、WebKit 和 ALSA音频库的开发包外加 Vulkan 相关库。Ubuntu/Debian 一条命令装齐sudo apt install build-essential libasound2-dev libgtk-3-dev libwebkit2gtk-4.1-dev libgtk-layer-shell-dev libvulkan-dev cmakemacOS装 Xcode 命令行工具xcode-select --install。Intel Mac 还要brew install onnxruntime否则编译 Parakeet 那步会失败。WindowsCMake 和 Vulkan SDK 都要在 PATH 里缺了 Vulkan 那一步会直接挂。跑不起来按症状对号入座装到一半或启动时报错先别慌按下面这几个场景对一下。编译 / 构建阶段报错大概率是缺系统构建链或平台专属依赖不是代码本身的问题。先确保bun install干净装完再跑bun tauri dev。Windows 报路径太长MSB3491/FTK1011这类是 260 字符路径限制把CARGO_TARGET_DIR指向一个短目录比如C:\h再编译。Linux 报缺.so库按上一条把 GTK/WebKit/Vulkan 那串开发包装齐即可。麦克风没声音或权限报错大概率是没给麦克风/辅助功能权限或蓝牙耳麦在 macOS 上切成了双向音频。首次启动按提示授予「麦克风」和「辅助功能Accessibility」权限macOS 在 系统设置 → 隐私与安全性 里。本地重新构建的 macOS 版本旧的授权会失效用tccutil reset Accessibility com.pais.handy重置后重新授权。用蓝牙耳麦时把声音输出留在耳机、麦克风选内置能避开音质和音量异常。模型下载卡住 / 初始化失败大概率是首次要拉几百 MB 模型被网络、代理或防火墙卡住了。换网络或开代理后重试下载。受限网络可以手动把模型文件放进models目录再重启Linux 是~/.config/com.pais.handy/modelsmacOS 是~/Library/Application Support/com.pais.handy/modelsWindows 在%APPDATA%\com.pais.handy\models具体做法见 README 手动装模型部分。没有独显就选 Parakeet V3CPU 就能跑放好后到 设置 → Models 确认显示“已下载”。窗口弹不出来 / 显示异常大概率Linux是缺gtk-layer-shell或 WebKit 的 DMA-BUF 渲染跟显卡驱动不兼容。先装或重装gtk-layer-shellUbuntu 装libgtk-layer-shell0。还是不显示或闪窗用下面这条启动试试它绕开有问题的渲染路径WEBKIT_DISABLE_DMABUF_RENDERER1 handy覆盖层会抢焦点导致粘贴错位的话到 设置 → 高级 把 Overlay Position 设为 None再开 Audio Feedback。启动闪退 / 运行卡顿大概率是 Linux 库缺失或显卡问题卡顿则多是模型选太大、没 GPU 或内存不足。Linux 崩溃先按上一条装好gtk-layer-shell仍崩就用HANDY_NO_GTK_LAYER_SHELL1 handy启动。转录慢、卡 → 换 Parakeet V3 或更小的 Whisper 模型Turbo/Large 留给有独显的机器。编译时内存告急把并行任务降下来例如cargo build --release --jobs2。让体验更顺手的 3 个小技巧快捷键选Auto模式同一键既能“按住录音”也能“点一下切换”新手最不容易用错。没独显就选Parakeet V3CPU 优化模型实测约 5 倍实时速度还自动识别语言不用手动选。打开Audio Feedback录音、转写状态都有提示音不用老盯着屏幕确认。一张表看懂常见坑症状大概率原因你该做什么bun: command not found没装 Bun装 Bunbun --version能出版本号即可编译报缺库 / linker 错误缺系统构建链装 C/C 工具链 Tauri 前置依赖启动报libgtk-layer-shell.so.0Linux 缺 runtime 包sudo apt install libgtk-layer-shell0麦克风没反应 / 反复弹权限没授麦克风/辅助功能权限按提示授权本地重建用 tccutil 重置模型一直下不动网络/代理限制换网络或手动放进 models 目录窗口不显示 / 渲染崩LinuxWebKit DMA-BUF 不兼容WEBKIT_DISABLE_DMABUF_RENDERER1启动录音自己开始或中断旧版监听 SIGUSR1升级新版删掉pkill -USR1绑定转录很卡模型太大 / 无 GPU / 内存不足换 Parakeet V3 或更小模型写在最后大多数装不上的问题归根结底就是依赖没装全或权限没给按“现象—原因—操作”这套顺序对下去基本都能解决。碰到解决不了的情况欢迎去项目 Issues 区提一个写清系统、桌面环境、复现步骤也可以翻翻音频、模型下载这些 源码顺便为这个还在快速迭代的项目提点小改进。【免费下载链接】HandyA free, open source, and extensible speech-to-text application that works completely offline.项目地址: https://gitcode.com/GitHub_Trending/handy11/Handy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考