Handy跨平台部署教程：Windows/macOS/Linux全平台适配指南

你是否正在寻找一款完全离线运行的语音转文字工具？Handy作为一款免费开源的语音转文本应用，支持全平台离线运行，本文将详细介绍如何在Windows、macOS和Linux系统上部署Handy，让你轻松实现本地语音识别。

准备工作：环境配置与依赖安装

全平台通用依赖

Handy基于Rust和Web技术栈构建，所有平台都需要安装以下基础依赖：

• Rust (最新稳定版)
• Bun 包管理器
• Tauri框架依赖：按照Tauri官方前置要求配置

项目构建配置文件：BUILD.md
项目依赖清单：package.json

平台专属依赖

Windows系统

• Microsoft C++ Build Tools
• Visual Studio 2019/2022（需安装C++开发组件）
• 或直接安装Visual Studio Build Tools 2019/2022

macOS系统

• Xcode命令行工具：

xcode-select --install

Linux系统

根据不同发行版安装相应依赖：

# Ubuntu/Debian
sudo apt update
sudo apt install build-essential libasound2-dev pkg-config libssl-dev libvulkan-dev vulkan-tools glslc libgtk-3-dev libwebkit2gtk-4.1-dev libayatana-appindicator3-dev librsvg2-dev patchelf

# Fedora/RHEL
sudo dnf groupinstall "Development Tools"
sudo dnf install alsa-lib-devel pkgconf openssl-devel vulkan-devel gtk3-devel webkit2gtk4.1-devel libappindicator-gtk3-devel librsvg2-devel

# Arch Linux
sudo pacman -S base-devel alsa-lib pkgconf openssl vulkan-devel gtk3 webkit2gtk-4.1 libappindicator-gtk3 librsvg

源代码获取与项目构建

1. 克隆代码仓库

git clone https://gitcode.com/GitHub_Trending/handy11/Handy.git
cd Handy

2. 安装项目依赖

使用Bun安装前端依赖：

bun install

项目依赖配置：package.json

3. 构建配置解析

Handy的构建过程由Tauri框架管理，主要配置文件为src-tauri/tauri.conf.json，关键配置项包括：

• 构建命令：beforeBuildCommand 执行前端资源构建
• 前端资源目录：frontendDist 指定为../dist
• 应用窗口设置：默认宽680px、高510px，不可最大化
• 打包配置：支持Windows、macOS和Linux全平台打包

平台专属构建步骤

Windows平台构建

1. 安装Visual Studio Build Tools 2019/2022（确保勾选"C++构建工具"）
2. 执行构建命令：

bun run tauri build

3. 构建产物位于src-tauri/target/release/bundle/msi/目录下，格式为.msi安装包

macOS平台构建

1. 安装Xcode命令行工具：

xcode-select --install

2. 执行构建命令：

bun run tauri build

3. 构建产物位于src-tauri/target/release/bundle/dmg/目录下，格式为.dmg镜像文件

macOS特定配置：在src-tauri/tauri.conf.json中设置了macOSPrivateApi: true以支持高级音频功能

Linux平台构建

1. 安装对应发行版的构建依赖（详见前文"平台专属依赖"部分）
2. 执行构建命令：

bun run tauri build

3. 构建产物位于src-tauri/target/release/bundle/目录下，包含AppImage、deb、rpm等多种格式

开发环境配置（可选）

如果你需要参与Handy的开发工作，可以使用开发模式运行应用：

bun run tauri dev

开发模式配置：在src-tauri/tauri.conf.json中设置了beforeDevCommand: "bun run dev"和开发服务器地址http://localhost:1420

常见问题解决

构建失败：缺少系统依赖

确保已安装所有平台特定依赖，特别是Linux系统需要的alsa、gtk和webkit2gtk库。参考BUILD.md中的"Platform-Specific Requirements"部分。

运行时错误：模型文件缺失

Handy需要VAD（语音活动检测）模型才能正常工作，构建过程中会自动下载必要的模型文件。如果遇到模型缺失错误，请检查网络连接或手动下载模型文件放置到指定目录。

权限问题：麦克风访问失败

• Windows：在应用设置中启用麦克风权限
• macOS：在系统偏好设置>安全性与隐私中授予麦克风访问权限
• Linux：确保用户属于audio组，或使用pactl命令检查音频设备权限

总结与后续步骤

通过本文指南，你已成功在Windows、macOS或Linux系统上部署了Handy应用。Handy的离线语音识别功能为你提供隐私安全的语音转文字体验。

接下来你可以：

• 探索Handy的设置界面，自定义快捷键和转录选项
• 尝试不同的语音模型以获得更好的识别效果
• 参与Handy的开源开发，提交Issue或Pull Request

项目贡献指南：参考README.md了解如何参与项目开发