Handy 离线语音转文字源码构建与部署报错排查全流程【免费下载链接】HandyA free, open source, and extensible speech-to-text application that works completely offline.项目地址: https://gitcode.com/GitHub_Trending/handy11/HandyHandy 是一款免费开源、完全离线运行的语音转文字应用。这篇 Handy 安装与部署故障排查指南覆盖三类场景bun找不到、Rust 链接器与系统依赖缺失、打包阶段的平台特有报错以及首次启动时模型下载卡住、macOS 权限不生效。按阶段对号入座每一步都给出可复制的命令和验证方法。报错速查表先看信号再往下翻对应小节报错关键词所属阶段对应小节bun: command not found编译前自查bun 命令不存在linker cc not found编译前自查cc 链接器缺失webkit2gtk/alsa-lib找不到编译前自查Linux 系统依赖缺失MSB3491/FTK1011/ 路径超长构建与打包Windows 路径长度报错onnxruntime/ORT链接失败构建与打包Intel Mac 缺 ONNX Runtime模型下载卡住 / 失败首次启动修复模型下载卡住权限一直显示Waiting...首次启动macOS 权限不生效麦克风无声音 / 输入设备缺失日常使用麦克风权限问题编译前自查bun 命令不存在bun: command not found安装脚本把 bun 放进了用户目录但你的 shell 还没把那个路径加进 PATH。先确认文件是否真的在那里ls ~/.bun/bin/bun文件存在时把它写进当前 shell 的启动文件echo export PATH$HOME/.bun/bin:$PATH ~/.bashrc source ~/.bashrczsh 用户把~/.bashrc换成~/.zshrc。验证bun --version能打印版本号就说明 PATH 生效了再执行bun install拉取前端依赖。cc 链接器缺失error: linker cc not foundcc 是 Rust 调用系统 C 工具链的入口系统上没有任何 C 编译器时就会出现这条报错与代码无关。按平台装工具链# Ubuntu / Debian sudo apt install build-essential # Fedora / RHEL sudo dnf groupinstall Development ToolsmacOS 执行xcode-select --install装完后cc --version能输出 clang 版本即修复。Linux 系统依赖缺失error[E0463]: cant find crate for alsa_sys error: could not find webkit2gtk-4.1 via pkg-configHandy 的后端依赖一批系统库ALSA 音频、GTK 界面、Vulkan GPU 加速、libevdev 键鼠。完整清单写在 BUILD.md 构建指南Ubuntu/Debian 一次装齐sudo apt update sudo apt install build-essential clang libevdev-dev libasound2-dev pkg-config \ libssl-dev libvulkan-dev glslc libgtk-3-dev libwebkit2gtk-4.1-dev \ libayatana-appindicator3-dev librsvg2-dev libgtk-layer-shell-dev cmakeFedora 用dnf groupinstall Development Tools加alsa-lib-devel、libevdev-devel、vulkan-devel、gtk3-devel、webkit2gtk4.1-devel、gtk-layer-shell等同名包。验证标准重新执行bun run tauri dev能越过依赖检查进入 Rust 编译阶段。构建与打包Windows 路径长度报错error MSB3491: ... fully qualified file name must be less than 260 characters FileTracker : error FTK1011: could not create the new file tracking log file根因是 Windows 的 260 字符路径上限被嵌套很深的构建中间目录撑爆——不是代码或工具链问题。新版构建会自动建一个短路径 junction 规避如果你的环境策略拦截了它日志里会有could not create short build junction警告。此时把 Cargo 输出目录指到短路径$env:CARGO_TARGET_DIR C:\h bun run tauri dev验证重新运行后编译继续推进产物落在C:\h\release\下而不是仓库的src-tauri\target\。想一劳永逸可用[Environment]::SetEnvironmentVariable(CARGO_TARGET_DIR, C:\h, User)持久化但注意这会影响你所有 Rust 项目的输出位置且需要新开终端才生效。Intel Mac 缺 ONNX Runtimeld: library not found for -lonnxruntime预编译的 ONNX Runtime 只覆盖 Apple SiliconIntel Mac 需要自己装并显式告诉构建器去哪找动态库brew install onnxruntime ORT_LIB_LOCATION$(brew --prefix onnxruntime)/lib ORT_PREFER_DYNAMIC_LINK1 bun run tauri dev生产构建bun run tauri build前也要带上这两个环境变量否则签名后的包运行时会找不到库。验证开发窗口正常弹出终端日志里不再出现ORT相关链接错误。首次启动与日常使用修复模型下载卡住error[handy_app] Model download failed for model-id: error首次启动选中的转写模型如 parakeet 或 whisper 系列是从 Hugging Face 拉的 GGUF 文件几十到几百 MB 不等公司网络或代理环境下最容易断。日志里能看到完整错误串应用日志在 DebugPaths 调试面板 对应的目录Linux 默认~/.local/share/handy/logs也可以直接手动补齐下载好对应.gguf文件放进本机模型目录——Linux~/.local/share/handy/modelsmacOS~/Library/Application Support/handy/modelsWindows%APPDATA%\handy\models文件校验和见 catalog.json 模型目录逐项比对sha256确认下载完整。验证应用重启后该模型出现在可用列表且可直接选中加载。macOS 权限不生效Accessibility: Waiting...本地构建用 ad-hoc 签名每次重编译签名指纹都会变而系统「隐私与安全性 辅助功能」里留着旧记录的开关看起来已授权实则没覆盖新构建。清除旧记录再重新授权osascript -e tell application id com.pais.handy to quit || true tccutil reset Accessibility com.pais.handy open /Applications/Handy.app验证重新打开应用会弹出授权框勾选后Waiting...消失状态变成已授权。此操作只重置辅助功能不影响麦克风等其他权限。麦克风权限问题ALSA lib pcm_dmix.c:1032:(snd_pcm_dmix_open) unable to open slave分两种情况。macOS 上通常是首次授权时误点了拒绝或测试的是扬声器而非输入设备——到「系统设置 隐私与安全性 麦克风」给 Handy 打勾重启应用。Linux 上多半是用户不在音频组或者默认输入设备被别的软件独占sudo usermod -aG audio,video $USER改完注销重登。验证应用内麦克风下拉能列出输入设备按一次全局快捷键说话后松开能看到转写出的文字。提交 issue 前请附上这些信息确认过以上场景仍未解决时把下面这份清单一次备齐避免来回补材料操作系统与版本发行版、macOS 版本号、Windows 构建号Handy 版本号或源码构建对应的 commit构建方式bun run tauri dev还是bun run tauri build是否带额外参数完整终端日志从命令开始到最后一条错误应用日志目录里的文件位置见上节日志路径最小复现步骤干净环境里按哪几步能稳定复现 各阶段的关系可以对照这张图定位按图从上游到下游排查卡在采集层看麦克风权限卡在识别层看模型文件卡在输出层看粘贴与快捷键配置。【免费下载链接】HandyA free, open source, and extensible speech-to-text application that works completely offline.项目地址: https://gitcode.com/GitHub_Trending/handy11/Handy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考