Common Voice 项目本地开发环境搭建指南
前言
Common Voice 是一个开源的语音数据集项目，旨在为语音识别技术提供多样化的语音数据。本文将详细介绍如何搭建 Common Voice 项目的本地开发环境，帮助开发者快速上手项目开发。
目标读者
本指南适合以下两类开发者：
- 希望为 Common Voice 项目贡献代码、修复 bug 或添加新功能的开发者
- 计划在自己的基础设施上部署 Common Voice 或根据需求进行二次开发的开发者
环境准备
在开始之前，请确保您的开发环境中已安装以下工具：
- Git：版本控制系统
- Docker：容器化平台
- Docker Compose：多容器应用编排工具
建议对这些工具的基本使用有一定了解，特别是 Git 的常用命令（如 commit、push 等）和 Docker 的基本操作。
快速启动步骤
- 获取项目代码
- 配置环境变量文件
- 启动 Docker 容器
- 清除 Redis 缓存（如需要）
- 重启容器
- 访问本地开发环境（默认地址：http://localhost:9000）
详细开发环境搭建
1. 获取项目代码
首先需要将 Common Voice 项目代码克隆到本地。虽然本文不提供具体克隆命令，但您可以使用标准的 Git 克隆操作获取代码。
2. 项目结构解析
Common Voice 项目采用模块化设计，主要目录结构如下：
- common：前后端共享的通用功能模块
- locales：站点支持的语言信息
- maintenance：维护模式相关静态文件
- scripts：数据管理脚本
- server：基于 TypeScript 的服务端应用逻辑
- web：基于 React 和 TypeScript 的网站前端
- bundler：数据集发布包生成服务
3. Docker 环境配置
Common Voice 使用 Docker Compose 管理开发环境，这是官方推荐的方式。
环境变量配置
复制 .env-local-docker.example 文件为 .env-local-docker 并进行必要配置：
cp .env-local-docker.example .env-local-docker
关键环境变量说明：
- 数据库相关：
CV_DB_ROOT_PASS（数据库root密码）、CV_MYSQLHOST（数据库容器名） - 存储相关：
CV_STORAGE_LOCAL_DEVELOPMENT_ENDPOINT（本地存储端点） - 语言导入：
CV_IMPORT_SENTENCES（是否导入语句）、CV_IMPORT_LANGUAGES（指定导入的语言代码） - 邮件配置：
CV_EMAIL_USERNAME_FROM和CV_EMAIL_USERNAME_TO - 缓存配置：
CV_REDIS_URL（Redis容器地址） - 认证配置：
CV_JWT_KEY（JWT认证密钥）
特别注意 CV_IMPORT_LANGUAGES 变量，建议只指定您需要开发的语言代码，避免导入所有语言数据耗时过长。
4. 启动开发环境
执行以下命令启动开发环境：
docker-compose up
此命令将：
- 启动 MySQL 数据库服务
- 启动模拟的 GCP 云存储服务
- 挂载项目代码到容器中实现实时更新
- 根据配置导入指定语言的语句数据
- 启动 Common Voice 服务器
- 启动 bundler 服务
Redis 缓存处理
在导入新语言数据后，需要清除 Redis 缓存：
docker exec -it redis redis-cli FLUSHALL
然后重启容器使更改生效。
5. 最小化启动
如果只需要运行网站部分，可以使用最小化启动：
docker-compose up web
常见问题解决
Docker 连接问题
如果遇到 Docker 守护进程连接问题，可以尝试重新构建 Docker 镜像：
cd docker/
docker build .
cd ..
docker compose up
文件权限问题
在 Linux 系统上可能会遇到 /code/node_modules 目录权限问题。解决方法：
- 查看当前用户的 UID 和 GID：
id -u id -g - 修改
docker-compose.yaml文件中的user配置为实际值
开发辅助工具
代码规范检查
项目使用 ESLint 和 Prettier 进行代码规范检查，可以运行：
yarn lint
数据库迁移
使用 db-migrate 进行数据库迁移：
- 创建迁移：
yarn migrate:local create <迁移名称> - 执行迁移：
yarn migrate:local [up|down]
本地化支持
项目使用 Fluent 进行本地化，英文字符串定义在消息文件中，可通过 Pontoon 平台进行翻译。
单元测试
使用 Jest 编写单元测试，测试文件命名格式为 功能或服务名.test.ts。
运行测试：
docker exec -it common-voice bash
yarn test
结语
通过本文的指导，您应该已经成功搭建了 Common Voice 的本地开发环境。如果在开发过程中遇到问题，可以参考项目文档或社区讨论寻求帮助。Happy coding!
