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 后端语音在本地转成文字后直接敲进任意输入框。本文按真实操作顺序——搭工具链、跑构建、首次启动、下载模型、配快捷键——整理编译与运行阶段最常见的报错每个问题都给出报错串、修复命令和一条可执行的验证。对照下面的速查表先定位自己卡在哪一步再翻到对应章节看到的报错 / 现象对应章节command not foundbun 相关安装 Bun 并修正 PATHlinker cc not found补齐 C 编译工具链failed to run custom build command装齐 GTK 与 WebKit 开发库MSB3491/FTK1011/MSB6003Windows 路径超长failed to run linuxdeployAppImage 打包失败编译到handy.exe后报program not foundWindows 签名命令只在 CI编译中途Killed内存不足降并发进程在跑但看不到窗口先排除隐藏启动转录用着、字打不进目标应用Linux 输入工具快捷键设了但从不触发Wayland 全局快捷键libgtk-layer-shell.so.0加载失败缺运行时共享库模型下载卡住 / SHA256 失败镜像与断点续传转录进程在部分机器上崩溃换 Parakeet 系模型 搭好工具链Bun、Rust 和平台依赖Handy 从源码构建的顺序固定clone 仓库 →bun install→bun run tauri dev。仓库克隆地址如下后文所有命令默认在仓库根目录执行git clone https://gitcode.com/GitHub_Trending/handy11/Handy.git cd Handy三个前置条件缺一不可Rustlatest stable从 rustup 装、Bun 包管理器、以及 BUILD.md 列出的各平台系统依赖。以下四类报错对应缺了其中某一样。报 command not found安装 Bun 并修正 PATH第一次bun install报bun: command not found说明系统还没装 Bun前端依赖装不下去构建在第一步就会断。安装命令curl -fsSL https://bun.sh/install | bash装完仍报同样的错通常是 PATH 没生效——把安装目录显式加进去export BUN_INSTALL$HOME/.bun export PATH$BUN_INSTALL/bin:$PATH同样两行追加到~/.bashrc末尾可让新终端永久生效。验证方式bun --version能打印版本号随后bun install正常拉取依赖。cc 链接器缺失补齐 C 编译工具链cargo build阶段报linker cc not found含义很直白系统缺 C 编译器Rust 无法链接本地库。按发行版补齐工具链# Ubuntu/Debian sudo apt update sudo apt install build-essential gcc g make cmake # Fedora/RHEL sudo dnf groupinstall Development Tools sudo dnf install gcc-c cmake # macOS xcode-select --install brew install cmakeWindows 需要 Visual Studio 2019/2022 Build Tools 并勾选 C 桌面开发工作负载。验证方式gcc --version与cargo --version都能输出结果。Tauri 构建失败装齐 GTK 与 WebKit 开发库出现error: failed to run custom build command或编译日志里反复提到找不到 gtk/webkit多半是系统库不全。先用这两条命令确认缺口pkg-config --modversion gtk-3.0 pkg-config --modversion webkit2gtk-4.1哪条报 not found 就是缺哪条。Ubuntu/Debian 的完整依赖清单与仓库 BUILD.md 一致比只装 gtk 和 webkit 更长别漏 clang、vulkan 相关项sudo apt install build-essential clang libclang-dev libevdev-dev libasound2-dev pkg-config libssl-dev libvulkan-dev vulkan-tools glslc spirv-headers glslang-tools libgtk-3-dev libwebkit2gtk-4.1-dev libayatana-appindicator3-dev librsvg2-dev libgtk-layer-shell0 libgtk-layer-shell-dev patchelf cmakeFedora 与 Arch 的对应清单见 BUILD.md 的 Platform-Specific Requirements 一节。验证方式在src-tauri目录执行cargo check能无错通过。平台附加项Intel Mac 与 Windows 各有一个专属坑Intel Mac 没有预编译的 ONNX Runtime需要先装库再带上两个环境变量构建否则会因找不到 onnxruntime 而失败brew install onnxruntime ORT_LIB_LOCATION$(brew --prefix onnxruntime)/lib ORT_PREFER_DYNAMIC_LINK1 bun run tauri devWindows 则要求 CMake 在 PATH 里、Vulkan SDK 已安装GPU 后端vulkan-shaders-gen需要 SDK 的头文件和glslcwinget install Kitware.CMake winget install KhronosGroup.VulkanSDK装完 Vulkan SDK 要开一个新终端让VULKAN_SDK环境变量被识别。️ 把构建跑通四个高频构建失败Windows 路径超长MSB3491 / FTK1011 / MSB6003编译transcribe-cpp-sys中途出现MSB3491、FTK1011、MSB6003中任意一个、且错误文本提到 260 字符路径上限就不是工具链问题而是 Windows 的MAX_PATH限制被嵌套的 CMake 构建目录撑爆。transcribe-cpp0.1.3 起通常已通过 NTFS junction 自动绕过若日志里仍有could not create short build junction警告或仓库 checkout 路径过深把构建输出指到一个短路径即可$env:CARGO_TARGET_DIR C:\h之后开一个新终端再bun run tauri dev产物会落在C:\h\release\。验证方式构建走完不再出现上述任一错误码。Arch / 滚动发行版打包 AppImage 失败bun run tauri build报failed to run linuxdeploy原因通常是linuxdeploy自带的strip太旧处理不了 Arch/CachyOS 等滚动发行版上较新工具链产出的系统库。注意只有 AppImage 这一步失败binary、deb、rpm 都能正常出bun run tauri build -- --bundles deb拿到 deb 后按 BUILD.md 的 Linux Install (from source) 一节解包安装。验证方式src-tauri/target/release/bundle/deb/下生成了.deb文件。Windows 打包报 program not found签名命令只在 CI 里编译一路走到Built application at: ...\handy.exe随后报failed to bundle project program not found——这是tauri.conf.json里配置的自定义签名命令trusted-signing-cli在作怪它只存在于发布 CI 环境本地开发根本不需要签名# 开发模式不打包不签名 bun run tauri dev # 或只产出 release 二进制跳过安装包 bun run tauri build --no-bundle验证方式handy.exe出现在src-tauri\target\release\且可正常启动。编译被 Killed内存不足时降低并发编译中途进程被系统杀掉、日志留下Killed是典型内存耗尽。先用free -h确认内存确实紧张然后两手处理内存实在不够就先加 4G swapsudo fallocate -l 4G /swapfile sudo chmod 600 /swapfile sudo mkswap /swapfile sudo swapon /swapfile再在/etc/fstab追加/swapfile none swap sw 0 0持久化同时压低并行编译数export CARGO_BUILD_JOBS2 cargo build --release --jobs2验证方式本次构建全程不再出现Killed。 首次运行窗口、麦克风与权限进程在跑但看不到窗口先排除隐藏启动Handy 是托盘优先的应用。若你用了--start-hidden启动或在设置里开了 Start Hidden窗口不弹出是故意的--no-tray则会连托盘图标一起去掉。先看托盘里有没有它确认不是这两种情况后再排障用handy --debug启动拿到 verbose 日志并在 设置 → Debug 面板里打开日志目录对照分析。Linux 上还有一类看似没窗口其实一切正常录音浮层在 Linux 上默认关闭Overlay Position 为 None因为部分合成器会把浮层当作活动窗口抢走焦点导致转录文字打不回来源应用。所以在 Linux 上看不到悬浮窗是默认行为不是故障。麦克风不可用Linux 看 ALSA 和用户组macOS 看两个权限Linux 上先用这条命令确认系统到底枚举到了哪个采集设备arecord -l列表为空说明没识别到设备或没有权限装alsa-utilssudo apt install alsa-utils并把用户加入 audio 组sudo usermod -aG audio $USER改完需要重新登录生效。macOS 上要分别授予麦克风录音与辅助功能把文字注入目标应用两项权限缺后者会出现录到了、但什么都不打字。另外蓝牙耳麦会把音频切成双向模式、短暂降低播放质量录的时候建议改用 Mac 内置或外置麦克风。本地重编译后 macOS 辅助功能权限卡死本地构建装回/Applications后onboarding 卡在 Accessibility 的 Waiting...而系统设置里的开关看起来还是开的——本地构建用 ad-hoc 签名每次重编译签名都变旧的授权记录因此失效。只清 Accessibility 这一条记录再重新授权即可osascript -e tell application id com.pais.handy to quit || true tccutil reset Accessibility com.pais.handy open /Applications/Handy.app该操作不动麦克风等其他 TCC 服务。验证方式重新打开应用、再次授权后 onboarding 通过录音能出字。⬇️ 下载模型跑出第一段转录模型由应用自己从镜像下载清单文件 src-tauri/src/catalog/catalog.json 记录了镜像地址、每个模型的文件名与 SHA256下载完成后自动校验中断的下载会保留 partial 文件以便断点续传。选型上纯英文场景推荐 Parakeet Unified EN 0.6B目录里的第一推荐多语言选 Nemotron Streaming 3.5覆盖 28 种语言。下载卡住或校验失败进度长时间不动、或报错里出现 SHA256/corrupt 字样时按三步走。第一步确认镜像可达基础地址即目录文件里的mirrorscurl -sI https://blob.handy.computer走公司网络时给应用配上 HTTP 代理再试。第二步如果是 SHA256 校验失败的报错说明文件已损坏且应用已自动删掉坏文件直接在应用里点重试即可无需手动处理。第三步网络受限环境可在别的机器上把对应【免费下载链接】HandyA free, open source, and extensible speech-to-text application that works completely offline.项目地址: https://gitcode.com/GitHub_Trending/handy11/Handy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
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 后端语音在本地转成文字后直接敲进任意输入框。本文按真实操作顺序——搭工具链、跑构建、首次启动、下载模型、配快捷键——整理编译与运行阶段最常见的报错每个问题都给出报错串、修复命令和一条可执行的验证。对照下面的速查表先定位自己卡在哪一步再翻到对应章节看到的报错 / 现象对应章节command not foundbun 相关安装 Bun 并修正 PATHlinker cc not found补齐 C 编译工具链failed to run custom build command装齐 GTK 与 WebKit 开发库MSB3491/FTK1011/MSB6003Windows 路径超长failed to run linuxdeployAppImage 打包失败编译到handy.exe后报program not foundWindows 签名命令只在 CI编译中途Killed内存不足降并发进程在跑但看不到窗口先排除隐藏启动转录用着、字打不进目标应用Linux 输入工具快捷键设了但从不触发Wayland 全局快捷键libgtk-layer-shell.so.0加载失败缺运行时共享库模型下载卡住 / SHA256 失败镜像与断点续传转录进程在部分机器上崩溃换 Parakeet 系模型 搭好工具链Bun、Rust 和平台依赖Handy 从源码构建的顺序固定clone 仓库 →bun install→bun run tauri dev。仓库克隆地址如下后文所有命令默认在仓库根目录执行git clone https://gitcode.com/GitHub_Trending/handy11/Handy.git cd Handy三个前置条件缺一不可Rustlatest stable从 rustup 装、Bun 包管理器、以及 BUILD.md 列出的各平台系统依赖。以下四类报错对应缺了其中某一样。报 command not found安装 Bun 并修正 PATH第一次bun install报bun: command not found说明系统还没装 Bun前端依赖装不下去构建在第一步就会断。安装命令curl -fsSL https://bun.sh/install | bash装完仍报同样的错通常是 PATH 没生效——把安装目录显式加进去export BUN_INSTALL$HOME/.bun export PATH$BUN_INSTALL/bin:$PATH同样两行追加到~/.bashrc末尾可让新终端永久生效。验证方式bun --version能打印版本号随后bun install正常拉取依赖。cc 链接器缺失补齐 C 编译工具链cargo build阶段报linker cc not found含义很直白系统缺 C 编译器Rust 无法链接本地库。按发行版补齐工具链# Ubuntu/Debian sudo apt update sudo apt install build-essential gcc g make cmake # Fedora/RHEL sudo dnf groupinstall Development Tools sudo dnf install gcc-c cmake # macOS xcode-select --install brew install cmakeWindows 需要 Visual Studio 2019/2022 Build Tools 并勾选 C 桌面开发工作负载。验证方式gcc --version与cargo --version都能输出结果。Tauri 构建失败装齐 GTK 与 WebKit 开发库出现error: failed to run custom build command或编译日志里反复提到找不到 gtk/webkit多半是系统库不全。先用这两条命令确认缺口pkg-config --modversion gtk-3.0 pkg-config --modversion webkit2gtk-4.1哪条报 not found 就是缺哪条。Ubuntu/Debian 的完整依赖清单与仓库 BUILD.md 一致比只装 gtk 和 webkit 更长别漏 clang、vulkan 相关项sudo apt install build-essential clang libclang-dev libevdev-dev libasound2-dev pkg-config libssl-dev libvulkan-dev vulkan-tools glslc spirv-headers glslang-tools libgtk-3-dev libwebkit2gtk-4.1-dev libayatana-appindicator3-dev librsvg2-dev libgtk-layer-shell0 libgtk-layer-shell-dev patchelf cmakeFedora 与 Arch 的对应清单见 BUILD.md 的 Platform-Specific Requirements 一节。验证方式在src-tauri目录执行cargo check能无错通过。平台附加项Intel Mac 与 Windows 各有一个专属坑Intel Mac 没有预编译的 ONNX Runtime需要先装库再带上两个环境变量构建否则会因找不到 onnxruntime 而失败brew install onnxruntime ORT_LIB_LOCATION$(brew --prefix onnxruntime)/lib ORT_PREFER_DYNAMIC_LINK1 bun run tauri devWindows 则要求 CMake 在 PATH 里、Vulkan SDK 已安装GPU 后端vulkan-shaders-gen需要 SDK 的头文件和glslcwinget install Kitware.CMake winget install KhronosGroup.VulkanSDK装完 Vulkan SDK 要开一个新终端让VULKAN_SDK环境变量被识别。️ 把构建跑通四个高频构建失败Windows 路径超长MSB3491 / FTK1011 / MSB6003编译transcribe-cpp-sys中途出现MSB3491、FTK1011、MSB6003中任意一个、且错误文本提到 260 字符路径上限就不是工具链问题而是 Windows 的MAX_PATH限制被嵌套的 CMake 构建目录撑爆。transcribe-cpp0.1.3 起通常已通过 NTFS junction 自动绕过若日志里仍有could not create short build junction警告或仓库 checkout 路径过深把构建输出指到一个短路径即可$env:CARGO_TARGET_DIR C:\h之后开一个新终端再bun run tauri dev产物会落在C:\h\release\。验证方式构建走完不再出现上述任一错误码。Arch / 滚动发行版打包 AppImage 失败bun run tauri build报failed to run linuxdeploy原因通常是linuxdeploy自带的strip太旧处理不了 Arch/CachyOS 等滚动发行版上较新工具链产出的系统库。注意只有 AppImage 这一步失败binary、deb、rpm 都能正常出bun run tauri build -- --bundles deb拿到 deb 后按 BUILD.md 的 Linux Install (from source) 一节解包安装。验证方式src-tauri/target/release/bundle/deb/下生成了.deb文件。Windows 打包报 program not found签名命令只在 CI 里编译一路走到Built application at: ...\handy.exe随后报failed to bundle project program not found——这是tauri.conf.json里配置的自定义签名命令trusted-signing-cli在作怪它只存在于发布 CI 环境本地开发根本不需要签名# 开发模式不打包不签名 bun run tauri dev # 或只产出 release 二进制跳过安装包 bun run tauri build --no-bundle验证方式handy.exe出现在src-tauri\target\release\且可正常启动。编译被 Killed内存不足时降低并发编译中途进程被系统杀掉、日志留下Killed是典型内存耗尽。先用free -h确认内存确实紧张然后两手处理内存实在不够就先加 4G swapsudo fallocate -l 4G /swapfile sudo chmod 600 /swapfile sudo mkswap /swapfile sudo swapon /swapfile再在/etc/fstab追加/swapfile none swap sw 0 0持久化同时压低并行编译数export CARGO_BUILD_JOBS2 cargo build --release --jobs2验证方式本次构建全程不再出现Killed。 首次运行窗口、麦克风与权限进程在跑但看不到窗口先排除隐藏启动Handy 是托盘优先的应用。若你用了--start-hidden启动或在设置里开了 Start Hidden窗口不弹出是故意的--no-tray则会连托盘图标一起去掉。先看托盘里有没有它确认不是这两种情况后再排障用handy --debug启动拿到 verbose 日志并在 设置 → Debug 面板里打开日志目录对照分析。Linux 上还有一类看似没窗口其实一切正常录音浮层在 Linux 上默认关闭Overlay Position 为 None因为部分合成器会把浮层当作活动窗口抢走焦点导致转录文字打不回来源应用。所以在 Linux 上看不到悬浮窗是默认行为不是故障。麦克风不可用Linux 看 ALSA 和用户组macOS 看两个权限Linux 上先用这条命令确认系统到底枚举到了哪个采集设备arecord -l列表为空说明没识别到设备或没有权限装alsa-utilssudo apt install alsa-utils并把用户加入 audio 组sudo usermod -aG audio $USER改完需要重新登录生效。macOS 上要分别授予麦克风录音与辅助功能把文字注入目标应用两项权限缺后者会出现录到了、但什么都不打字。另外蓝牙耳麦会把音频切成双向模式、短暂降低播放质量录的时候建议改用 Mac 内置或外置麦克风。本地重编译后 macOS 辅助功能权限卡死本地构建装回/Applications后onboarding 卡在 Accessibility 的 Waiting...而系统设置里的开关看起来还是开的——本地构建用 ad-hoc 签名每次重编译签名都变旧的授权记录因此失效。只清 Accessibility 这一条记录再重新授权即可osascript -e tell application id com.pais.handy to quit || true tccutil reset Accessibility com.pais.handy open /Applications/Handy.app该操作不动麦克风等其他 TCC 服务。验证方式重新打开应用、再次授权后 onboarding 通过录音能出字。⬇️ 下载模型跑出第一段转录模型由应用自己从镜像下载清单文件 src-tauri/src/catalog/catalog.json 记录了镜像地址、每个模型的文件名与 SHA256下载完成后自动校验中断的下载会保留 partial 文件以便断点续传。选型上纯英文场景推荐 Parakeet Unified EN 0.6B目录里的第一推荐多语言选 Nemotron Streaming 3.5覆盖 28 种语言。下载卡住或校验失败进度长时间不动、或报错里出现 SHA256/corrupt 字样时按三步走。第一步确认镜像可达基础地址即目录文件里的mirrorscurl -sI https://blob.handy.computer走公司网络时给应用配上 HTTP 代理再试。第二步如果是 SHA256 校验失败的报错说明文件已损坏且应用已自动删掉坏文件直接在应用里点重试即可无需手动处理。第三步网络受限环境可在别的机器上把对应【免费下载链接】HandyA free, open source, and extensible speech-to-text application that works completely offline.项目地址: https://gitcode.com/GitHub_Trending/handy11/Handy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
