企业官网建设流程全解析

Handy 离线语音转文字：源码构建与部署报错排查全流程

【免费下载链接】HandyA free, open source, and extensible speech-to-text application that works completely offline.项目地址: https://gitcode.com/GitHub_Trending/handy11/Handy

Handy 是一款免费开源、完全离线运行的语音转文字应用。这篇 Handy 安装与部署故障排查指南覆盖三类场景：bun找不到、Rust 链接器与系统依赖缺失、打包阶段的平台特有报错，以及首次启动时模型下载卡住、macOS 权限不生效。按阶段对号入座，每一步都给出可复制的命令和验证方法。

报错速查表

先看信号，再往下翻对应小节：

编译前自查

bun 命令不存在

bun: command not found

安装脚本把 bun 放进了用户目录，但你的 shell 还没把那个路径加进 PATH。先确认文件是否真的在那里：

ls ~/.bun/bin/bun

文件存在时，把它写进当前 shell 的启动文件：

echo 'export PATH="$HOME/.bun/bin:$PATH"' >> ~/.bashrc source ~/.bashrc

zsh 用户把~/.bashrc换成~/.zshrc。验证：bun --version能打印版本号就说明 PATH 生效了，再执行bun install拉取前端依赖。

cc 链接器缺失

error: linker `cc` not found

cc 是 Rust 调用系统 C 工具链的入口，系统上没有任何 C 编译器时就会出现这条报错，与代码无关。按平台装工具链：

# Ubuntu / Debian sudo apt install build-essential # Fedora / RHEL sudo dnf groupinstall "Development Tools"

macOS 执行xcode-select --install，装完后cc --version能输出 clang 版本即修复。

Linux 系统依赖缺失

error[E0463]: can't find crate for `alsa_sys` error: could not find webkit2gtk-4.1 via pkg-config

Handy 的后端依赖一批系统库（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 cmake

Fedora 用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 Runtime

ld: library not found for -lonnxruntime

预编译的 ONNX Runtime 只覆盖 Apple Silicon，Intel Mac 需要自己装并显式告诉构建器去哪找动态库：

brew install onnxruntime ORT_LIB_LOCATION=$(brew --prefix onnxruntime)/lib ORT_PREFER_DYNAMIC_LINK=1 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/models
• macOS：~/Library/Application Support/handy/models
• Windows：%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 前请附上这些信息

确认过以上场景仍未解决时，把下面这份清单一次备齐，避免来回补材料：

1. 操作系统与版本（发行版、macOS 版本号、Windows 构建号）
2. Handy 版本号，或源码构建对应的 commit
3. 构建方式：bun run tauri dev还是bun run tauri build，是否带额外参数
4. 完整终端日志（从命令开始到最后一条错误）
5. 应用日志目录里的文件（位置见上节日志路径）
6. 最小复现步骤：干净环境里按哪几步能稳定复现

🔧 各阶段的关系可以对照这张图定位：

按图从上游到下游排查：卡在采集层看麦克风权限，卡在识别层看模型文件，卡在输出层看粘贴与快捷键配置。

【免费下载链接】HandyA free, open source, and extensible speech-to-text application that works completely offline.项目地址: https://gitcode.com/GitHub_Trending/handy11/Handy