Voicebox 安装避坑指南3 类常见报错5 分钟修好跑通【免费下载链接】voiceboxThe open-source AI voice studio. Clone, dictate, create.项目地址: https://gitcode.com/GitHub_Trending/voicebox1/voiceboxVoicebox 是一款本地优先的开源 AI 语音工作室支持声音克隆、语音生成和全局听写。安装 Voicebox 时最容易卡住的位置是首次启动和第一次生成macOS 提示应用已损坏无法打开Windows SmartScreen 弹已保护你的电脑或者左下角状态灯一直是红色。思路很简单把报错分成系统拦截、网络下载、运行加速三类先对号入座判断属于哪一类再执行该类的步骤。照做完状态灯会转绿你能听到第一段生成音频。下载之前先花 30 秒确认你的机器能跑系统macOS 11、Windows 10 或 Linux在关于本机或设置 → 系统里看版本号。内存8GB 起步推荐 16GB在任务管理器Windows或活动监视器macOS里看占用。磁盘至少 5GB 空闲推荐 10GB单个模型从约 350 MB 到约 8 GB 不等看系统盘剩余空间。GPU推荐 6GB 显存的 NVIDIA 卡终端执行nvidia-smi能看到显卡名即正常。网络需要访问 HuggingFace Hub 下载模型浏览器打开 huggingface.co 能正常加载即正常。3 分钟装好按系统选对安装渠道如果你是Apple Silicon Mac下载voicebox_aarch64.app.tar.gzIntel 选voicebox_x64.app.tar.gz解压并移入 /Applications。tar -xzf voicebox_aarch64.app.tar.gz mv Voicebox.app /Applications/如果你是Windows 10双击voicebox_x64_en-US.msi按向导完成或改用voicebox_x64-setup.exe独立安装器。如果你是Linux暂无官方预编译包需要源码构建。先装好 Bun、Rust、Python 3.12 和justcargo install just然后just setup # 创建 Python venv 并安装全部依赖 just build # 构建服务器二进制与桌面应用产物在tauri/src-tauri/target/release/bundle/里。如果你有无头服务器先git clone https://gitcode.com/GitHub_Trending/voicebox1/voicebox并cd voicebox然后docker compose up首次构建要几分钟编译前端 装 Python 依赖之后秒开浏览器打开127.0.0.1:17600docker-compose.yml 默认把宿主机 17600 映射到容器 17493。具体下载包名与数据目录位置见 installation。安装之后可能出现的报错下一节全部覆盖分成三类。报错排查先认类型再动手安装后的报错基本归为三类被系统拦下、网络与下载、运行与加速。先判断你遇到的是哪一类再按该类步骤执行。被系统拦下已损坏提示与 SmartScreen 弹窗双击时 macOS 提示应用已损坏无法打开您应将它移到废纸篓Windows 的 SmartScreen 蓝屏显示已保护你的电脑。 这是未签名应用被系统拦截文件本身没有问题。macOS打开终端执行xattr -cr /Applications/Voicebox.app再双击打开应用。Windows在蓝屏上点More info再点Run anyway。Linux 上如果从其他渠道拿到 AppImage 并提示Permission denied先执行chmod x voicebox-*.AppImage再运行。完成标志应用正常启动不再弹窗。网络与下载模型下载卡住生成时进度条停在 Loading model... 或 Downloading...或弹出 Failed to download model。 首次生成会自动下载所选引擎的模型体积从 Kokoro 约 350 MB 到 TADA 3B 约 8 GB 不等网络慢或 HuggingFace 访问受限就会卡住这不是故障。打开Settings → Models查看真实下载进度带宽有限就换小模型起步Kokoro约 350 MB或 LuxTTS约 300 MB。长时间不动就挂上代理或用官方 CLI 手动把模型下到缓存目录pip install huggingface_hub huggingface-cli download Qwen/Qwen3-TTS-12Hz-1.7B-Base缓存位置可用环境变量VOICEBOX_MODELS_DIR改Docker 用户确认huggingface-cache卷还在否则每次重启都会重新下载模型。完成标志进度条走动或Settings → Models里模型显示完成。运行与加速后端起不来、爆显存、GPU 没生效左下角状态灯一直红色提示 Failed to connect to server或生成报 CUDA out of memory、no kernel image is available或 Apple Silicon 上生成报 metallib 相关错误。 后端进程没正常起来端口 17493 被占、二进制缺权限或者显存不够生成需要 6GB又或者后端与硬件不匹配——程序本身没坏。查端口占用macOS/Linux 执行lsof -i :17493Windows 执行powershell -Command Get-NetTCPConnection -LocalPort 17493 -State Listen用kill -9 PID或taskkill /PID PID /F结束占用进程。macOS/Linux 给后端二进制补执行权限chmod x ~/Library/Application\ Support/sh.voicebox.app/backend/voicebox-server再看同目录logs/server.log找真因。出现flash-attn is not installed可以忽略它是可选加速库。CUDA out of memory关掉吃显存的应用后重启 Voicebox或Settings → Generation切到 CPU慢 5-10 倍但改用系统内存同时在Settings → Models卸载不用的引擎腾显存。GPU 没生效Windows 在Settings → GPU点Install CUDA backendApple Silicon 在Settings → Server Status看到 PYTORCH 而不是 MLX 时执行pip install -r backend/requirements-mlx.txtno kernel image is available 先确认版本 ≥ 0.4.0再到Settings → GPU重装 CUDA 后端多显卡机器在Settings → Generation → GPU Device选对显卡。完成标志左下角状态灯转绿Settings → Server Status显示预期后端Apple Silicon 为 MLXNVIDIA 为 CUDA。更多数据库锁、损坏恢复等症状见 troubleshooting。跑通一次完整流程验收安装启动 Voicebox确认左下角状态灯为绿色。点Voices标签点 New Voice新建测试档案上传或录制一段 10-30 秒的清晰人声。填好 Name 和 Language点Create Profile保存。切到Generate标签选中这个档案输入一句话。点Generate首次会下载模型可能等 2-5 分钟进度在Settings → Models看。点Play试听能听到声音安装成功 急救卡看到什么提示就先做什么你看到的提示先做这个预计耗时App 已损坏无法打开macOSxattr -cr /Applications/Voicebox.app10 秒SmartScreen 已保护你的电脑WindowsMore info→Run anyway10 秒Permission deniedLinux AppImagechmod x voicebox-*.AppImage10 秒Failed to connect to server、红灯依次查端口 17493 占用 → 二进制权限 → server.log2 分钟卡在 Loading model... / Downloading...换小模型 / 挂代理 / huggingface-cli 手动下载视网速CUDA out of memory关 GPU 应用 / CPU 模式 /Settings → Models卸载模型2 分钟no kernel image is available更新到 ≥ 0.4.0Settings → GPU重装 CUDA 后端5 分钟metallib 相关报错Apple Siliconpip install -r backend/requirements-mlx.txt1 分钟语音数据、档案和生成音频默认存在 macOS 的~/Library/Application Support/sh.voicebox.app/、Windows 的%APPDATA%/sh.voicebox.app/、Linux 的~/.config/sh.voicebox.app/备份时认准这个目录。首次生成的完整细节与 Stories 编辑器用法看 quick-start。【免费下载链接】voiceboxThe open-source AI voice studio. Clone, dictate, create.项目地址: https://gitcode.com/GitHub_Trending/voicebox1/voicebox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考