Voicebox本地声音克隆：4步跑通安装与首次运行
【免费下载链接】voiceboxThe open-source AI voice studio. Clone, dictate, create.项目地址: https://gitcode.com/GitHub_Trending/voicebox1/voicebox
Voicebox 是一款本地优先的开源免费 AI 语音工作室，能把几秒音频克隆成可用声音，再离线生成语音。本文覆盖 macOS、Windows、Linux/Docker 三条安装路线，以及首次运行最常见的报错，按顺序走完，你能在 10 分钟内拿到第一段自己生成的语音。
第一步：装之前先确认三件事
- 系统版本：macOS 11+ / Windows 10+ / 较新的 Linux 发行版；源码构建另需 Python 3.12（
just setup会固定这个版本）。 - 硬件：最低 8GB 内存、5GB 可用磁盘；推荐 16GB+ 内存和 NVIDIA GPU，生成需要 6GB+ 显存。
- 网络：首次生成会自动从 HuggingFace 下载模型，约 350MB 到 8GB，网络受限会卡住（见第三步处理）。
| 平台 | 推荐方式 | 耗时估算 | 备注 |
|---|---|---|---|
| macOS | DMG 安装 | 2 分钟 | 注意芯片架构，选 aarch64 或 x64 |
| Windows | MSI 安装 | 2 分钟 | 可能触发 SmartScreen |
| Linux | Docker 容器 | 5-10 分钟 | 首次构建需编译前端 |
| 开发者 | 源码构建 | 15-30 分钟 | 需 Rust、just、Bun |
安装文档
第二步：按你的平台走对应路线
macOS 路线（官方安装包，含 GPU 加速后端）
- 从 Releases 下载对应芯片的 DMG，拖入 Applications。
- 首次双击若提示"App 已损坏"，属正常隔离，在终端执行一行命令解除：
xattr -cr /Applications/Voicebox.app- 再打开即可。Apple Silicon 上后端会自动使用 MLX（比 PyTorch 快 4-5 倍），无需手动配置。
Windows 路线（官方安装包）
- 下载
voicebox_x64_en-US.msi，双击按向导安装。 - SmartScreen 蓝屏提示"未知应用"是未签名应用的正常拦截：点"更多信息"，再点"仍要运行"，10 秒过。
- 有 NVIDIA 显卡的用户，在 Settings → GPU 里确认安装了 CUDA 后端，否则生成会退回 CPU，速度差 5-10 倍。
Linux / Docker 路线（容器化部署）
Linux 暂无官方桌面安装包，容器是最省事的走法，浏览器直接访问完整界面。在仓库目录执行：
git clone https://gitcode.com/GitHub_Trending/voicebox1/voicebox cd voicebox docker compose up首次构建要几分钟（编译前端 + 装 Python 依赖），之后秒开；浏览器打开http://localhost:17493即可。想走源码构建就装好just和 Bun 后依次跑just setup、just build，产物在tauri/src-tauri/target/release/bundle/。
第三步：首次启动，看到红灯别慌
左下角状态灯变绿才算后端就绪。红灯或卡住时，先对照下表处理：
| 你看到的现象 | 一步到位的处理动作 |
|---|---|
| "App is damaged, can't be opened" | 终端执行xattr -cr /Applications/Voicebox.app |
| SmartScreen"已保护你的电脑" | 点"更多信息"→"仍要运行" |
| "Failed to connect to server" | 查 17493 端口占用 → 补执行权限 → 看日志 |
| 进度停在 "Downloading..." | 换小模型（Kokoro ~350MB）或挂代理 |
| "CUDA out of memory" | 关占显存应用，或 Settings → Generation 切 CPU |
| "Database is locked" | 退出所有实例，删除 data 目录的-wal/-shm文件 |
端口冲突是最常见的红灯根因。后端固定在 17493 端口，被别的实例占住就起不来：
lsof -i :17493 # macOS / Linux taskkill /PID <PID> /F # 确认 PID 后在 Windows 结束进程权限与日志：macOS/Linux 上服务二进制可能缺执行权限，chmod +x ~/Library/Application\ Support/sh.voicebox.app/backend/voicebox-server即可；日志在~/Library/Application\ Support/sh.voicebox.app/logs/server.log，tail -f跟进才能看到真正的崩溃原因。Windows 对应%APPDATA%\sh.voicebox.app\logs\server.log。
模型缓存：首次生成慢不是故障，是引擎在自动下载模型。进度在 Settings → Models 查看；Docker 用户若每次重启都重新下载，检查huggingface-cache卷是否保留。
日志里出现
Warning: flash-attn is not installed可以安全忽略——它是可选加速库，缺省时 PyTorch 自动改用 SDPA 注意力，速度几乎无损。
完整排障文档
第四步：验证你真的装好了
- 启动应用：左下角状态灯为绿色，说明内置后端已连上。
- 创建测试语音档案：进 Voices 页点+ New Voice，上传或录制 10-30 秒清晰音频（背景噪声越少克隆越准）。
- 生成一段语音：切到 Generate 页，选刚建的档案，输入一句话点 Generate。能听到声音即安装成功，音频会同步进 History 列表。
附录：常用路径与快捷命令
- 服务日志：macOS
~/Library/Application Support/sh.voicebox.app/logs/server.log，Windows%APPDATA%\sh.voicebox.app\logs\server.log - 数据目录（档案 + 生成音频，备份认准它）：macOS
~/Library/Application Support/sh.voicebox.app/、Windows%APPDATA%\sh.voicebox.app\、Linux~/.config/sh.voicebox.app/ - 模型缓存：
~/.cache/huggingface/，可用环境变量VOICEBOX_MODELS_DIR自定义 - 查端口占用：
lsof -i :17493（macOS/Linux） - 健康检查：
curl http://127.0.0.1:17493/health - API 文档：浏览器访问
http://127.0.0.1:17493/docs - 手动下载模型：
pip install huggingface_hub后huggingface-cli download Qwen/Qwen3-TTS-12Hz-1.7B-Base
【免费下载链接】voiceboxThe open-source AI voice studio. Clone, dictate, create.项目地址: https://gitcode.com/GitHub_Trending/voicebox1/voicebox
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
