WordPecker App 零基础上手与避坑指南：从安装到精通的实用教程

一、核心功能模块解析：如何利用AI提升语言学习效率？

语言学习工具层出不穷，但如何找到真正个性化的解决方案？WordPecker App通过三大核心功能模块，将词汇管理、沉浸式阅读和语音交互融为一体，让学习过程更高效、更贴近真实场景。

1.1 智能词汇学习系统

准备工作：确保已完成基础安装并启动应用 执行步骤：

1. 访问"Get New Words"页面创建自定义词汇列表
2. 添加单词时设置难度级别和记忆周期
3. 系统自动生成针对性练习（填空/选择/匹配题型） 验证方法：在"Learn"页面查看生成的练习，确认单词均来自自定义列表

核心功能模块：[backend/src/agents/vocabulary-agent/] [frontend/src/pages/WordLearningSession.tsx]

图1：智能词汇学习界面展示，包含进度跟踪和多样化题型

1.2 沉浸式阅读训练

准备工作：确保已添加至少10个目标词汇 执行步骤：

1. 进入"Light Reading"页面选择感兴趣的文章主题
2. 系统自动高亮已添加的词汇并提供即时解释
3. 完成阅读理解练习并查看词汇掌握情况分析 验证方法：检查高亮词汇是否与个人列表匹配，确认练习结果统计准确

核心功能模块：[backend/src/agents/reading-agent/] [frontend/src/pages/ReadingPage.tsx]

图2：沉浸式阅读界面，高亮显示用户添加的词汇并提供上下文学习

1.3 AI语音对话练习

准备工作：确保麦克风权限已开启，网络连接稳定 执行步骤：

1. 进入"Voice Chat"页面点击"Start Conversation"
2. 根据AI助手提示完成情景对话练习
3. 系统实时反馈发音准确度和语法修正建议 验证方法：检查语音识别是否准确，确认反馈建议与对话内容相关

核心功能模块：[frontend/src/agents/voice-agent/] [backend/src/api/voice/routes.ts]

图3：AI语音学习助手界面，支持实时对话练习和反馈

二、环境搭建与配置：如何避免常见的启动故障？

第一次部署开源项目时，环境配置往往是最容易出错的环节。本章节将通过清晰的步骤指引，帮助你顺利完成WordPecker的本地部署，避开那些让新手头疼的"坑"。

2.1 项目准备与依赖安装

准备工作：确保已安装Node.js(16+)和npm(7+) 执行步骤：

# 克隆项目仓库
git clone https://gitcode.com/gh_mirrors/wo/wordpecker-app
cd wordpecker-app

# 同时安装前后端依赖（使用并行命令提高效率）
cd backend && npm install && cd ../frontend && npm install

🔍 注意事项：如遇依赖安装失败，尝试使用npm cache clean --force清理缓存后重试

2.2 环境变量配置全流程

准备工作：创建前后端环境变量文件 执行步骤：

1. 后端配置：在backend目录创建.env文件

   PORT=3001
   OPENAI_BASE_URL=https://api.openai.com/v1
   OPENAI_API_KEY=your_api_key_here
   

2. 前端配置：在frontend目录创建.env文件

   VITE_API_URL=http://localhost:3001
   VITE_SUPABASE_URL=your_supabase_url
   VITE_SUPABASE_ANON_KEY=your_supabase_key
   

3. 核心配置项说明：

配置项	默认值	推荐值	说明
PORT	3000	3001	避免与前端开发服务器端口冲突
OPENAI_API_KEY	无	个人API密钥	需从OpenAI平台申请
VITE_API_URL	无	http://localhost:3001	必须与后端PORT保持一致

graph TD
    A[创建.env文件] --> B[填写基础配置]
    B --> C[验证API密钥有效性]
    C --> D[检查端口占用情况]
    D --> E[保存配置并启动服务]

2.3 前后端服务启动与验证

准备工作：确保环境变量配置正确 执行步骤：

1. 启动后端服务：

   cd backend
   npm run dev  # 使用nodemon实现热重载
   

2. 启动前端服务：

   cd frontend
   npm run dev  # Vite开发服务器，默认端口5173
   

3. 验证服务状态：

   • 后端：访问http://localhost:3001/api/health，应返回{"status":"ok"}
   • 前端：访问http://localhost:5173，应显示应用首页
   • 前后端联调：在前端创建词汇列表，检查是否能正常保存

🔍 注意事项：如遇跨域错误，检查后端CORS配置是否包含前端地址

三、高级功能配置：如何定制个性化学习体验？

掌握基础使用后，通过高级配置可以进一步提升学习效率。本节将介绍如何根据个人学习习惯调整系统设置，以及如何利用模板功能快速创建专业领域的词汇库。

3.1 学习偏好设置

准备工作：已完成基础注册并登录系统 执行步骤：

1. 进入"Settings"页面选择"Language Preferences"
2. 设置母语、目标语言和学习难度级别
3. 配置练习类型偏好（多选）：
   • 听力练习
   • 阅读理解
   • 口语对话
   • 词汇拼写
4. 保存设置并验证：新建学习任务时确认设置已生效

核心功能模块：[frontend/src/pages/Settings.tsx] [backend/src/api/preferences/routes.ts]

3.2 专业领域模板应用

准备工作：了解自己的学习需求（如学术、商务、日常等） 执行步骤：

1. 进入"Template Library"页面浏览可用模板
2. 选择适合的专业领域模板（如"学术研究"或"商务金融"）
3. 点击"Apply Template"导入相关词汇和练习
4. 根据个人需求调整模板内容

核心功能模块：[backend/data/templates/] [frontend/src/pages/TemplateLibrary.tsx]

3.3 学习数据同步与备份

准备工作：已创建Supabase账户并获取API凭证 执行步骤：

1. 在"Settings"页面找到"Data Management"选项
2. 输入Supabase配置信息并测试连接
3. 启用自动同步功能，设置同步频率
4. 手动触发一次完整备份，验证数据是否正确保存

🔍 注意事项：定期导出学习数据到本地，避免云端服务变更导致数据丢失

四、常见问题速查

Q1: 启动后端服务时提示"OPENAI_API_KEY未设置"，但我已经配置了.env文件，该如何解决？

A1: 可能原因及解决步骤：

1. 检查.env文件是否位于backend目录下
2. 确认变量名是否为"OPENAI_API_KEY"（区分大小写）
3. 重启终端或开发工具，确保环境变量已加载
4. 尝试直接在命令行临时设置：export OPENAI_API_KEY=your_key

Q2: 前端可以正常加载，但无法添加新词汇，网络请求返回404错误，如何处理？

A2: 这通常是前后端联调问题，解决方法：

1. 确认后端服务是否正常运行（访问/api/health）
2. 检查前端.env文件中的VITE_API_URL是否正确指向后端地址
3. 查看浏览器开发者工具的网络面板，确认请求URL是否正确
4. 检查后端路由定义是否包含词汇相关接口

Q3: 使用语音对话功能时没有声音反馈，如何排查问题？

A3: 按以下步骤排查：

1. 确认系统麦克风权限已授予浏览器
2. 检查网络连接是否稳定（语音功能需要持续网络连接）
3. 查看后端控制台是否有语音处理相关错误
4. 尝试更换浏览器或清除缓存后重试
5. 检查[frontend/src/agents/voice-agent/tools.ts]中的API配置是否正确