Voicebox 安装全流程四步装完跑通首次语音生成10 个高频坑提前排掉【免费下载链接】voiceboxThe open-source AI voice studio. Clone, dictate, create.项目地址: https://gitcode.com/GitHub_Trending/voicebox1/voiceboxVoicebox 是一个本地优先的开源 AI 语音工作室用几秒音频克隆声音、生成多语言语音、全局快捷键听写到任意文本框。安装只是双击级别的简单操作真正的坑集中在首次启动——后端连不上、模型下载卡住、GPU 没生效。本文按装前体检 → 按平台安装 → 首次启动排雷 → 跑通验证四步带你走一遍一次装好、少走弯路。第 1 关 · 装前体检硬件门槛与安装渠道选型下载前先花 30 秒核对机器配置。Voicebox 内置 Python FastAPI 后端TTS 模型全部跑在本地资源要够。项目最低要求推荐配置系统macOS 11 / Windows 10 / Linux主流版本内存8 GB16 GB磁盘可用5 GB10 GB模型体积不小GPU无CPU 可跑NVIDIA CUDA 卡 / Apple Silicon / Intel Arc最低配置纯 CPU 也能跑但生成速度会慢 5-10 倍有独显就尽量用上。四种安装渠道按你的使用场景任选其一渠道适合谁一句话说明macOS DMGApple Silicon / Intel Mac双击装完即用但有一个命令级坑见第 2 关Windows MSIWindows 10按向导点完1 分钟Linux 源码构建Linux 用户暂无官方预编译包just两条命令搞定Docker 容器无头服务器 / 共享 GPUdocker compose up浏览器访问 Web UI✅过关判定你能明确说出自己要走哪条渠道。macOS / Windows 用户选前两个最省心。第 2 关 · 按平台安装macOS / Windows / Linux / DockermacOS 与 Windows 安装包已内置后端服务二进制应用启动时后端自动拉起不用手动配置。macOS双击 DMG 装上一条命令绕过已损坏警告装进应用程序后第一次双击大概率弹出应用已损坏无法打开。⚠️ 这不是真损坏——应用没有 Apple 开发者签名系统自动打了隔离属性。打开终端执行一行命令xattr -cr /Applications/Voicebox.app再双击就能打开无需重装。原理详见 troubleshooting 文档。Apple Silicon 用户首启后打开Settings → Server Status应显示Backend: MLX比 PyTorch 快 4-5 倍。若显示 PYTORCH说明 MLX 依赖没装好补装pip install -r backend/requirements-mlx.txtWindows过掉 SmartScreenNVIDIA 用户再装 CUDA 后端首次运行安装程序会弹蓝屏 SmartScreen 警告已保护你的电脑。这属于未签名应用的正常拦截点更多信息点仍要运行。全程 10 秒不用改任何系统设置。NVIDIA 显卡用户注意安装包不带 CUDA体积太大。首次需要 GPU 时打开Settings → GPU点Install CUDA backend应用会单独下载 CUDA 后端包约 4 GB并自动重启生效。完整流程见 GPU 加速文档。Linux没有官方预编译包源码构建两条命令官方暂无 Linux 预编译安装包如果你从别处拿到 AppImage先执行chmod x voicebox-*.AppImage赋予执行权限再运行。官方推荐路线是源码构建。先备好工具链Git、Rust、Bun、justcargo install just以及 Tauri 系统依赖。必须安装 Python 3.12——这是源码构建第一大坑系统默认 Python 是 3.13 的话just setup会装依赖失败。先装一个 3.12uv python install 3.12然后克隆仓库git clone https://gitcode.com/GitHub_Trending/voicebox1/voiceboxcd voiceboxjust setupjust setup会自动创建 Python venv 并装齐全部后端依赖不用手动 pip。接着构建just build构建产物在tauri/src-tauri/target/release/bundle/。所有命令定义在 justfile跑just --list查看全部后端依赖清单见 backend/requirements.txt。Docker一条命令起无头语音服务无桌面环境的服务器直接走 DockerWeb UI 由后端直接提供git clone https://gitcode.com/GitHub_Trending/voicebox1/voiceboxcd voiceboxdocker compose up首次构建要编译前端 安装 Python 依赖等几分钟之后启动秒开。⚠️最容易被忽略的坑默认 docker-compose.yml 把宿主机端口映射到了17600给桌面应用的 17493 让路所以打开http://localhost:17600而不是 17493。另外两个高频现象打开页面显示 JSON 而不是界面 → 前端构建阶段失败重新构建docker compose build --no-cache模型每次重启都重新下载 → 确认 compose 里挂载了huggingface-cache卷它保存模型缓存镜像是前端 / 后端 / 运行时三阶段构建见 Dockerfile卷与 NVIDIA / AMD GPU 配置细节见 docker 文档。✅过关判定应用或容器已启动、能看到主界面。此刻状态灯如果是红的也别慌正好交给第 3 关解决。第 3 关 · 首次启动排雷四道高频故障一次清掉以下故障跨平台通用统一按现象 → 原因 → 三步排查来照着做即可。红灯后端服务连不上现象左下角状态指示器红色提示 Failed to connect to server。原因后端监听17493端口。端口被占、服务二进制没有执行权限、或进程直接崩了都会表现为红灯。三步排查查端口占用。macOS / Linuxlsof -i :17493WindowsGet-NetTCPConnection -LocalPort 17493 -State Listen找到占用进程后结束它kill -9 PIDmacOS / Linux或taskkill /PID PID /FWindows。查二进制执行权限macOS / Linuxchmod x ~/Library/Application\ Support/sh.voicebox.app/backend/voicebox-server看日志定位真因。macOStail -f ~/Library/Application\ Support/sh.voicebox.app/logs/server.logWindows 看%APPDATA%\sh.voicebox.app\logs\server.log。 日志里出现flash-attn is not installed警告可以放心忽略——它是可选加速库缺省时 PyTorch 自动退回 SDPA 注意力速度几乎无损。模型下载卡住或首次生成要等 2-5 分钟现象点生成后进度条停在 Loading model... / Downloading...长时间无响应。原因首次生成会自动下载所选引擎的模型从 Kokoro 约 350 MB 到 TADA 3B 约 8 GB 不等。不是故障但网络不佳时体验很差。三步排查在Settings → Models查看下载进度带宽有限就先选Kokoro~350 MB或LuxTTS~300 MB起步下载失败多为 HuggingFace Hub 访问受限挂代理或手动下载模型进缓存目录pip install huggingface_hubhuggingface-cli download Qwen/Qwen3-TTS-12Hz-1.7B-Base模型缓存目录可用环境变量VOICEBOX_MODELS_DIR自定义Docker 用户发现模型每次重启都重新下载时检查huggingface-cache卷是否保留见第 2 关 Docker 节。CUDA out of memory显存不足现象生成报CUDA out of memory或进程直接被杀。原因生成需要6 GB 显存被游戏、视频剪辑等应用挤占了。三步排查关掉吃显存的应用重启 Voicebox显存确实不够就切 CPUSettings → Generation改用 CPU速度慢 5-10 倍但吃系统内存小模型依然可用长文本拆成短段落分段生成别一次丢全文。有 GPU 却跑在 CPU 速度现象有独显但生成很慢GPU 占用接近 0。原因后端没选对——Apple Silicon 的 MLX 没装好或 Windows 的 CUDA 后端没装。三步排查打开Settings → Server Status/GPU面板看识别到的后端Apple Silicon 应显示MLX显示 PYTORCH 就执行pip install -r backend/requirements-mlx.txt第 2 关已给命令Windows NVIDIA 确认已安装 CUDA 后端Settings → GPU多卡机器在Settings → Generation → GPU Device手动选对显卡NVIDIA 用户终端里跑nvidia-smi确认驱动正常GPU 面板出现[UNSUPPORTED - see logs]兼容警告时先升级 Voicebox 或重装 CUDA 后端。各平台后端对照表见 gpu-acceleration 文档。第 4 关 · 跑通验证30 秒自检确认安装完成状态灯变绿后按 安装文档 的验证流程做三步自检全部通过即算装完 第 1 步看状态灯。主界面左下角指示器应为绿色。第 2 步建一个测试语音档案。进入Voices页点 New Voice上传或录制10-30 秒清晰音频避开背景噪音点Create Profile保存第 3 步生成一次。切到Generate页选中刚建的档案输入一句话点Generate。首次可能要等一会儿原因见第 3 关听到声音即安装成功 语音数据、档案和生成音频默认保存在以下目录备份时认准它macOS~/Library/Application Support/sh.voicebox.app/Windows%APPDATA%\sh.voicebox.app\Linux~/.config/sh.voicebox.app/下一步能生成后可以试试多轨Stories编辑器——把不同声音的片段拖到时间线上做对话、播客和叙事内容细节见 stories 文档。附录 · 高频故障速查表卡在哪一步先查这张表问题关键动作预计耗时macOS App 已损坏xattr -cr /Applications/Voicebox.app10 秒Windows SmartScreen 警告更多信息 → 仍要运行10 秒Linux 没有官方预编译包just setup后just build5-10 分钟源码构建 Python 版本报错uv python install 3.12后重跑just setup1 分钟Docker 页面打不开确认默认宿主机端口为1760010 秒模型每次重启都重新下载确认挂载了huggingface-cache卷1 分钟后端红灯端口 17493 → 二进制权限 → server.log2 分钟模型下载卡住换小模型 / 挂代理 /huggingface-cli手动下载视网速CUDA out of memory关吃显存应用 / 切 CPU 模式2 分钟GPU 没生效对照 GPU 面板后端MLX / CUDA2 分钟更多症状数据库锁、损坏恢复、远程模式连接等完整收录在 troubleshooting 文档后端依赖清单见 backend/requirements.txt。【免费下载链接】voiceboxThe open-source AI voice studio. Clone, dictate, create.项目地址: https://gitcode.com/GitHub_Trending/voicebox1/voicebox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考