Handy 安装与构建失败？4 类卡点的完整排错指南

Handy 安装与构建失败4 类卡点的完整排错指南【免费下载链接】HandyA free, open source, and extensible speech-to-text application that works completely offline.项目地址: https://gitcode.com/GitHub_Trending/handy11/HandyHandy 是一款完全离线运行的语音转文字桌面应用按一下快捷键说话文字直接粘贴进任意输入框覆盖 Windows、macOS、Linux。当你从源码安装 Handy 时遇到 Handy 安装构建失败依赖缺失、编译报错、首次启动无窗口这篇文章按卡住的阶段带你逐一排查每步给出一条可直接执行的修复命令。30 秒自查先定位你卡在哪一步报错现象卡住阶段跳到哪一节bun: command not found/rustc not found环境准备环境准备阶段linker cc not found、error: failed to run custom build command for tauri...依赖安装依赖安装阶段MSB3491/FTK1011/MSB6003编译构建Windows编译构建阶段failed to bundle project编译构建打包编译构建阶段Waiting...不消失首次启动macOS 权限首次启动阶段error while loading shared libraries: libgtk-layer-shell.so.0首次启动Linux首次启动阶段模型下载卡住或失败首次启动首次启动阶段按卡住的位置排查环境准备报错发生在bun install之前还是之后先确认两个基础工具真实可用装过也可能不在 PATH 里bun -v rustc --version看到bun: command not found把 bun 安装目录加进 PATH 并写进 shell 配置然后新开终端重试Linux/macOSexport PATH$HOME/.bun/bin:$PATH看到rustc not found用官方工具链补装 Rustcurl --proto https --tlsv1.2 -sSf https://sh.rustup.rs | shIntel Mac 编译时报 ONNX Runtime 相关链接错误Intel 机型没有预编译的 ONNX Runtime必须用 Homebrew 安装并动态链接macOSbrew install onnxruntime ORT_LIB_LOCATION$(brew --prefix onnxruntime)/lib ORT_PREFER_DYNAMIC_LINK1 bun run tauri devWindows 上构建transcribe-cpp-sys时缺 CMake 或 Vulkan 头文件两个都要装装完新开终端让VULKAN_SDK生效Windowswinget install Kitware.CMake winget install KhronosGroup.VulkanSDK依赖安装卡住时装完系统依赖再跑bun install判断问题bun install有报错先看输出末尾确认代理/网络正常没有 bun 本身则回到上一节。看到linker cc not found或 Tauri 依赖编译失败如error: failed to run custom build command for tauri...这是系统库缺失不是 bun 的问题。按发行版一次性装齐再重试Linux# Ubuntu/Debian sudo apt install build-essential clang libasound2-dev libgtk-3-dev \ libwebkit2gtk-4.1-dev libgtk-layer-shell-dev # Fedora/RHELsudo dnf groupinstall Development Tools 再装 alsa、gtk3、webkit2gtk4.1 等看到npm ERR! missing script: tauri说明tauri-apps/cli没装全。项目用 bun删掉node_modules重新装全平台rm -rf node_modules bun install编译构建报错在 cargo 编译、生成handy.exe、还是 bundle 打包三个位置对应三种原因修复方式完全不同。Arch / Manjaro 等滚动发行版上 AppImage 打包失败Bundling Handy_*_amd64.AppImage ... failed to bundle projectlinuxdeploy自带的工具链过旧二进制、deb、rpm 其实都构建成功了跳过 AppImage 即可bun run tauri build -- --bundles debWindows 出现MSB3491、FTK1011或MSB6003这是 Windows 260 字符路径上限被深层构建目录撑爆不是代码问题。新版transcribe-cpp0.1.3会自动用短 junction 规避若你的日志里仍有could not create short build junction警告把 cargo 输出目录改短然后新开终端重跑Windows[Environment]::SetEnvironmentVariable(CARGO_TARGET_DIR, C:\h, User)编译到Built application at: ...\handy.exe后报Signing ... failed to bundle project program not foundsignCommand指向的签名工具只存在于发布 CI本地构建不需要跳过打包即可Windowsbun run tauri build --no-bundle首次启动权限、模型下载、共享库macOS 本地构建后一直Waiting...ad-hoc 签名让每次重建都换新的代码标识旧的 Accessibility 授权记录不会自动更新。清掉旧记录再重新授权macOStccutil reset Accessibility com.pais.handy open /Applications/Handy.app模型下载卡住或失败多为代理/防火墙拦了下载。按 README 的Manual Model Installation手动下载模型文件放进 App 数据目录下的models文件夹后重启 Handy。目录参考macOS~/Library/Application Support/com.pais.handy/、WindowsC:\Users\{用户名}\AppData\Roaming\com.pais.handy\、Linux~/.config/com.pais.handy/。Linux 启动报error while loading shared libraries: libgtk-layer-shell.so.0缺运行时库Linuxsudo apt install libgtk-layer-shell0 # Debian/UbuntuFedora 为 sudo dnf install gtk-layer-shell装了库仍启动即崩、窗口不显示或报 Wayland 协议错误先试绕过 layer-shellLinuxHANDY_NO_GTK_LAYER_SHELL1 handy窗口黑屏、渲染失败或随机崩溃再叠加 WebKit 渲染器开关验证有效后写进 shell 配置或.desktop文件的Exec行LinuxWEBKIT_DISABLE_DMABUF_RENDERER1 handyLinux 上转录完成但文字没有粘回没装文本输入工具X11 装xdotool、Wayland 装wtype同时把 Settings → Advanced 里Overlay Position设为Noneoverlay 会抢焦点导致粘贴落空。 排查不了的报错通用兜底三步开详细日志重跑一次拿到完整输出而不是终端里的最后几行handy --debug应用内按CtrlShiftDmacOS 为CmdShiftD打开 Debug 菜单查看 App Data Directory 与运行日志应用主界面也可能没有显示这条菜单是拿信息的保底路径。提 issue 时按模板写社区能直接上手系统信息发行版/版本、桌面环境、Wayland 还是 X11、CPU/GPU完整错误日志复现步骤从哪条命令开始、在哪一步失败。如果错误只在旧版本复现先把 Handy 升到最新再试——例如 0.9.4 及更早版本用SIGUSR1做远程触发会误伤 WebKit 的垃圾回收信号导致自己开始/停止录音新版已移除该监听记得删掉所有pkill -USR1 -n handy的键位绑定。⚠️ 开始之前避坑项目要求CPUParakeet V3 模型最低需 Intel Skylake6 代或同档 AMDWhisper 模型建议有 Intel/AMD/NVIDIA GPU内存编译过程建议预留空闲内存内存不足时编译会被系统杀掉磁盘单个模型 500 MB1.6 GB给源码构建 模型留出至少几 GB 空间权限macOS 麦克风 AccessibilityLinux Wayland 下系统级快捷键要在桌面环境里配置安装路径建议优先用发布页的预编译包macOS 也可brew install --cask handyWindows 可winget install cjpais.Handy可绕开全部编译问题必须源码编译时严格对照仓库自带的 BUILD.md 检查清单Rustrustup 最新 stable Bun 各平台 Tauri 系统依赖一条都不能少需要克隆仓库时使用git clone https://gitcode.com/GitHub_Trending/handy11/Handy cd Handy bun install bun run tauri dev卡住不可怕报错都是线索每个阶段的高频报错基本都对应一个缺失的环境组件按上表对号入座多数问题十分钟就能恢复。若仍无法解决带着--debug日志和项目 issue 模板去社区提问维护者会优先处理信息完整的报告——你贴的每段日志都会帮下一个遇到同样问题的人少走弯路。【免费下载链接】HandyA free, open source, and extensible speech-to-text application that works completely offline.项目地址: https://gitcode.com/GitHub_Trending/handy11/Handy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考