Handy 安装部署故障排除新手快速修复高频报错【免费下载链接】HandyA free, open source, and extensible speech-to-text application that works completely offline.项目地址: https://gitcode.com/GitHub_Trending/handy11/Handy终端里飘出一行error: linker cc not found构建进度停在 87% 再不动macOS 上双击图标却弹出已损坏无法打开——如果你正卡在 Handy 的安装或源码编译环节先别慌。Handy 是一款完全离线运行的开源语音转文字桌面应用Rust Tauri 后端React 前端装不上基本都卡在环境依赖、系统权限、资源下载这三个地方。这篇 Handy 安装与部署故障排除指南覆盖 Windows / macOS / Linux按你看到了什么直接跳转大多数问题 30 分钟内能解决。30 秒定位你卡在哪一步对照报错关键词直接跳到对应章节不用从头读你看到的现象 / 报错关键词跳转到bun: command not foundbun 命令找不到linker cc not found、failed to run custom build command for tauri编译器或 Tauri 依赖缺失Windows 下缺glslc/ CMake / Vulkan 头文件Windows 构建缺工具链macOS 提示 App 已损坏 / damagedmacOS 提示 App 已损坏Handy 停在 Waiting...、快捷键无效Handy macOS 权限修复ALSA lib ... unable to open slave、麦克风没声音ALSA 音频设备打不开首次启动模型下载卡住 / 失败模型下载卡住或失败编译进程被Killed (signal: 9)编译进程被 Killed编译完成后打包报failed to run linuxdeploy/program not found打包阶段程序找不到环境依赖缺失一键补齐编译器与 Tauri 工具链编译报找不到命令、找不到库都落在这个域。源码构建的起点是 clone 仓库装依赖git clone https://gitcode.com/GitHub_Trending/handy11/Handy cd Handy bun install第一条命令拉取代码第二条装好前端依赖并顺带触发平台检查。下面三种报错按出现频率排。bun 命令找不到补上 PATH现象执行bun install直接提示bun: command not found。根因Bun 装是装了但默认安装目录~/.bun/bin不在 PATH 里。先跑这个确认一下export PATH$HOME/.bun/bin:$PATH bun --version第一条把 Bun 的安装目录临时加进当前会话的搜索路径第二条能打印出版本号就说明通了。想永久生效把export那行追加到~/.bashrc或~/.zshrc即可。编译器或 Tauri 依赖缺失现象cargo build报linker cc not found或卡在failed to run custom build command for tauri-*。根因系统缺 C/C 编译工具链或 Tauri 依赖的 GTK / WebKit / 托盘库没装。Ubuntu / Debian 上跑这条 前半段是编译器和音频库后半段是 Tauri 的图形界面依赖sudo apt install build-essential clang libevdev-dev libasound2-dev pkg-config \ libgtk-3-dev libwebkit2gtk-4.1-dev libayatana-appindicator3-dev librsvg2-devFedora / RHEL 用sudo dnf groupinstall Development Tools加对应 devel 包macOS 只需xcode-select --install。完整清单含 Vulkan、glslc、gtk-layer-shell 等 GPU 后端依赖以 BUILD.md 的 Platform-Specific Requirements 章节为准。Windows 构建缺工具链现象Windows 上编译到transcribe-cpp附近报找不到 CMake、glslc或 Vulkan 头文件。根因Vulkan GPU 后端需要 CMake 和 LunarG 的 Vulkan SDK外加 Visual Studio 的 C 构建工具。用 winget 一次装齐winget install Kitware.CMake winget install KhronosGroup.VulkanSDK装完必须开新终端让VULKAN_SDK环境变量生效然后重新bun run tauri dev。CMake 没在 PATH 里、SDK 版本过旧是另外两个常见变体先确认这两点。编译这一关过了、程序也装上了但一运行就被系统拦下来——签名、隔离属性、设备权限的问题都在下一个域。系统权限与安全限制签名绕过与设备授权macOS 提示 App 已损坏现象双击提示 Handy is damaged and cant be opened。根因自编译包用的是 ad-hoc 签名signingIdentity: -带隔离属性时会被 Gatekeeper 直接拒绝。执行这两行⚠️ 官方发布包通常不会碰到这个问题它主要影响自构建xattr -dr com.apple.quarantine /Applications/Handy.app open /Applications/Handy.app第一条递归移除整个应用的隔离标记第二条重新打开。仍打不开的话再到系统设置 → 隐私与安全性里点仍要打开。Handy macOS 权限修复Accessibility 卡住不动现象本地重新构建安装后Handy 一直停在 Waiting...全局快捷键没有任何反应。根因ad-hoc 签名每次重建都会生成新的代码身份而系统设置 → 隐私与安全性 → 辅助功能里还挂着旧版本的授权记录等于白名单失效。BUILD.md 给出的标准修复osascript -e tell application id com.pais.handy to quit || true tccutil reset Accessibility com.pais.handy open /Applications/Handy.app中间那条只清除 Handy 的 Accessibility 记录不会动麦克风等其他权限重启后按提示重新授权即可。ALSA 音频设备打不开现象Linux 上启动后录不进音日志出现ALSA lib ... (snd_pcm_dmix_open) unable to open slave。根因缺 ALSA 开发库或当前用户不在audio组。跑一下sudo apt install libasound2-dev sudo usermod -aG audio $USER第二条把用户加进音频组注意注销重新登录后才生效重新构建再试。权限都放行之后剩下的一类问题出在程序能跑但资源跟不上模型下不下来、内存不够、打包最后一步翻车。资源与运行时异常模型下载、内存与打包模型下载卡住或失败现象首次启动后模型下载长时间转圈或反复失败。根因网络不稳或模型数据目录没有写权限。开发模式下VAD 模型silero_vad_v4.onnx需要手动放到src-tauri/resources/models/下载地址在 AGENTS.md 的 Model Setup 一节里正式版则把模型文件放进各平台数据目录下的models/Windows%APPDATA%\Handy\modelsmacOS~/Library/Application Support/Handy/modelsLinux~/.local/share/Handy/models放好文件后重启应用它会跳过下载直接加载。编译进程被 Killed现象编译到一半cc1或rustc进程被Killed (signal: 9)干掉。根因内存不足Rust 编译 原生依赖同跑时建议至少 4GB 空闲。最省事的办法是临时加一块 swap下面两行分别创建 4GB swap 文件并启用它sudo fallocate -l 4G /swapfile sudo chmod 600 /swapfile sudo mkswap /swapfile sudo swapon /swapfile嫌麻烦就先关掉浏览器等其他吃内存的程序重新编译。打包阶段程序找不到现象编译全部完成能看到Built application at: ...但打包步骤报failed to run linuxdeployArch / Manjaro 等滚动发行版常见或program not foundWindows 常见。根因前者是 linuxdeploy 自带的strip太旧处理不了新版工具链的系统库后者是 Windows 打包时调用了一个只存在于发布 CI 环境的签名工具。二进制本身已经编出来了跳过打包即可# Linux 滚动发行版跳过 AppImage只出 deb bun run tauri build -- --bundles deb # Windows只编译不打包不签名 bun run tauri build --no-bundleWindows 上如果看到的是MSB3491/FTK1011/MSB6003这类 260 字符路径限制报错则是另一个病根把构建输出目录改短再试例如$env:CARGO_TARGET_DIR C:\h然后开新终端重新构建。深度排查开调试、找日志、整理 issue上面都没解决时别反复重装按这条链路收集信息开调试模式用--debug启动Trace 级日志或在应用内按CmdShiftDmacOS/CtrlShiftDWindows / Linux打开调试面板里面有实时日志查看器。看日志文件按平台定位Windows%APPDATA%\Handy\logsmacOS~/Library/Application Support/Handy/logsLinux~/.local/share/Handy/logs提 issue整理四样东西——系统版本 CPU 架构、报错完整输出至少最后 20 行、rustc --version和bun --version的输出、可复现的步骤说明。仓库对 issue 有模板要求空 issue 会被直接关闭按模板填比写一大段散文有效得多。安装前自检清单动手前把这六项过一遍能省掉 80% 的回头路CPU 支持 AVX2 指令集Intel 第 6 代及以上 / AMD Ryzen至少 4GB 空闲内存模型加载和原生依赖编译都吃内存至少 1GB 磁盘空间应用 模型文件rustc --version输出最新稳定版通过 rustup 安装bun --version能正常打印且 Bun 在 PATH 中按 BUILD.md 装齐当前平台的系统依赖含 Tauri 前置库装完按一次全局快捷键听到提示音、光标处开始蹦字——就成了 ✅【免费下载链接】HandyA free, open source, and extensible speech-to-text application that works completely offline.项目地址: https://gitcode.com/GitHub_Trending/handy11/Handy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考