企业官网建设流程全解析

Voicebox 安装避坑指南：3 类常见报错，5 分钟修好跑通

【免费下载链接】voiceboxThe open-source AI voice studio. Clone, dictate, create.项目地址: https://gitcode.com/GitHub_Trending/voicebox1/voicebox

Voicebox 是一款本地优先的开源 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.gz（Intel 选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 和just（cargo 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:17600（docker-compose.yml 默认把宿主机 17600 映射到容器 17493）。

具体下载包名与数据目录位置见 installation。

安装之后可能出现的报错，下一节全部覆盖，分成三类。

报错排查：先认类型，再动手

安装后的报错基本归为三类：被系统拦下、网络与下载、运行与加速。先判断你遇到的是哪一类，再按该类步骤执行。

被系统拦下："已损坏"提示与 SmartScreen 弹窗

双击时 macOS 提示"应用已损坏，无法打开，您应将它移到废纸篓"；Windows 的 SmartScreen 蓝屏显示"已保护你的电脑"。 这是未签名应用被系统拦截，文件本身没有问题。

1. macOS：打开终端执行xattr -cr /Applications/Voicebox.app，再双击打开应用。
2. Windows：在蓝屏上点More info，再点Run anyway。
3. Linux 上如果从其他渠道拿到 AppImage 并提示"Permission denied"：先执行chmod +x voicebox-*.AppImage再运行。

完成标志：应用正常启动，不再弹窗。

网络与下载：模型下载卡住

生成时进度条停在 "Loading model..." 或 "Downloading..."，或弹出 "Failed to download model"。 首次生成会自动下载所选引擎的模型，体积从 Kokoro 约 350 MB 到 TADA 3B 约 8 GB 不等；网络慢或 HuggingFace 访问受限就会卡住，这不是故障。

1. 打开Settings → Models查看真实下载进度；带宽有限就换小模型起步：Kokoro（约 350 MB）或 LuxTTS（约 300 MB）。
2. 长时间不动就挂上代理，或用官方 CLI 手动把模型下到缓存目录：

pip install huggingface_hub huggingface-cli download Qwen/Qwen3-TTS-12Hz-1.7B-Base

3. 缓存位置可用环境变量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+），又或者后端与硬件不匹配——程序本身没坏。

1. 查端口占用：macOS/Linux 执行lsof -i :17493；Windows 执行powershell -Command "Get-NetTCPConnection -LocalPort 17493 -State Listen"；用kill -9 <PID>或taskkill /PID <PID> /F结束占用进程。
2. macOS/Linux 给后端二进制补执行权限chmod +x ~/Library/Application\ Support/sh.voicebox.app/backend/voicebox-server；再看同目录logs/server.log找真因。出现flash-attn is not installed可以忽略💡，它是可选加速库。
3. "CUDA out of memory"：关掉吃显存的应用后重启 Voicebox；或Settings → Generation切到 CPU（慢 5-10 倍但改用系统内存）；同时在Settings → Models卸载不用的引擎腾显存。
4. GPU 没生效：Windows 在Settings → GPU点Install CUDA backend；Apple Silicon 在Settings → Server Status看到 PYTORCH 而不是 MLX 时执行pip install -r backend/requirements-mlx.txt；"no kernel image is available" 先确认版本 ≥ 0.4.0，再到Settings → GPU重装 CUDA 后端；多显卡机器在Settings → Generation → GPU Device选对显卡。

完成标志：左下角状态灯转绿，Settings → Server Status显示预期后端（Apple Silicon 为 MLX，NVIDIA 为 CUDA）。

更多"数据库锁"、损坏恢复等症状见 troubleshooting。

跑通一次完整流程，验收安装

1. 启动 Voicebox，确认左下角状态灯为绿色。
2. 点Voices标签，点+ New Voice新建测试档案：上传或录制一段 10-30 秒的清晰人声。
3. 填好 Name 和 Language，点Create Profile保存。
4. 切到Generate标签，选中这个档案，输入一句话。
5. 点Generate；首次会下载模型，可能等 2-5 分钟，进度在Settings → Models看。
6. 点Play试听：能听到声音，安装成功 🎉

急救卡：看到什么提示，就先做什么

语音数据、档案和生成音频默认存在 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