第19章：开发环境搭建

配置你的本地 Voicebox 开发环境

快速开始（推荐）

通过两条命令快速上手：

# 克隆并进入仓库
git clone https://github.com/jamiepine/voicebox.git
cd voicebox

# 配置所有环境（Python venv、JS 依赖、开发 sidecar）
just setup

# 启动开发模式（后端 + 桌面应用）
just dev

just dev 命令会自动启动 Python 后端（如果尚未运行）并启动 Tauri 桌面应用。

前置依赖

请确保已安装以下工具：

• Bun
  下载 Bun
  curl -fsSL https://bun.sh/install | bash
• Python 3.12
  下载 Python
  python3.12 --version # macOS/Linux — 应为 3.12.x
py -3.12 --version # Windows
  Voicebox 将 venv 固定为 3.12 以匹配 CI 环境，因为部分依赖尚未发布 3.13 版本。在 Debian/Ubuntu 上还需安装 python3.12-venv。
• Rust
  安装 Rust
  rustc --version
• Just
  安装 Just
  brew install just # macOS
cargo install just # Linux/Windows
  Just 支持 macOS、Linux 和 Windows。

Just 命令

运行 just --list 查看所有可用命令。重点如下：

配置

开发

构建

质量检查

数据库

实用工具

项目结构

（此处原文未提供具体结构图，仅保留标题）

请求流程

HTTP 请求 → routes/（验证输入） → services/（业务逻辑） → backends/（TTS/STT 推理） → utils/（音频处理）

核心模块

• app.py — FastAPI 应用工厂、CORS、生命周期事件
• main.py — 入口点（导入 app，运行 uvicorn）
• server.py — Tauri sidecar 启动器、父进程 PID 监控
• services/generation.py — 处理所有生成模式的单一函数
• backends/ — TTS/STT 引擎实现（MLX、PyTorch 等）

模型下载

模型会在首次使用时自动从 HuggingFace Hub 下载，并向 UI 实时推送进度：

• Whisper（转录）— 首次转录时自动下载
• TTS 引擎 — 首次生成时自动下载。大小范围从 82 M（Kokoro，约 350 MB）到 3 B（TADA，约 8 GB）

完整列表请参阅“模型管理”。首次使用因模型下载速度较慢，但后续运行将使用缓存的模型。

生成 OpenAPI 客户端

启动后端服务器后，生成 TypeScript API 客户端：

just generate-api

这将下载 OpenAPI schema 并在 app/src/lib/api/ 中生成 TypeScript 客户端。

手动配置（高级）

如果不想使用 Just，请遵循以下手动步骤：

1. 安装 JavaScript 依赖

bun install

这将安装以下项目的依赖：

• app/ - 共享 React 前端
• tauri/ - Tauri 桌面包装器
• web/ - Web 部署包装器

2. 配置 Python 后端

cd backend

# 创建虚拟环境（使用 Python 3.12 — 参见前置依赖）
python3.12 -m venv venv   # macOS/Linux
# 或者
py -3.12 -m venv venv     # Windows

# 激活虚拟环境
source venv/bin/activate  # macOS/Linux
# 或者
venv\Scripts\activate  # Windows

# 安装 Python 依赖
pip install -r requirements.txt

# Apple Silicon：安装 MLX 依赖
pip install -r requirements-mlx.txt

# Chatterbox 固定了 numpy<1.26 / torch==2.6，在 Python 3.12+ 上会失效
pip install --no-deps chatterbox-tts

# HumeAI TADA 固定了 torch>=2.7,<2.8，与我们要求的 torch>=2.1 冲突
pip install --no-deps hume-tada

# 从源码安装 Qwen3-TTS
pip install git+https://github.com/QwenLM/Qwen3-TTS.git

# PyInstaller 和 Lint 工具
pip install pyinstaller ruff pytest pytest-asyncio

3. 启动开发

启动后端：

cd backend
source venv/bin/activate
uvicorn main:app --reload --port 17493

在新终端中启动桌面应用：

cd tauri
bun run tauri dev

后续步骤

• 架构 — 了解系统架构
• 贡献 — 阅读贡献指南
• 构建 — 学习如何构建生产发行版
• TTS 引擎 — 端到端添加新的 TTS 引擎

故障排查

▶ 后端无法启动

• 检查 Python 版本（必须是 3.12）
• 确保已激活虚拟环境：source backend/venv/bin/activate
• 验证所有依赖已安装：pip install -r requirements.txt
• 检查端口 17493 是否可用

▶ Tauri 构建失败

• 确保已安装 Rust：rustc --version
• 清理构建：cd tauri/src-tauri && cargo clean
• 尝试重新构建：just dev

▶ OpenAPI 客户端生成失败

• 确保后端正在运行：curl http://localhost:17493/openapi.json
• 检查网络连接
• 验证后端是否可通过 localhost:17493 访问

更多问题及解决方案请参阅完整的“故障排查指南”。

在 GitHub 上编辑 | 获取模型进度 | 通过 Server-Sent Events 获取模型下载进度 | 架构：理解 Voicebox 的技术架构