一款帮你通过句子构建轻松掌握英语的开源学习工具

1.项目背景

在英语学习过程中，很多人都会遇到这样的困境：背了很多单词，却无法组织成完整的句子；学了多年语法，开口时还是支离破碎。传统的英语学习工具往往侧重于单词记忆或语法规则，忽略了语言学习的本质——在实际语境中构建和使用句子。

Earthworm 正是为解决这一问题而生。它通过连词构建句子的方式，帮助学习者在实践中掌握英语句子的结构和用法，让英语学习变得更加自然、高效。

这是项目传送地址Earthworm链接

2. 核心功能亮点

1.🎯 句子构建学习法 不再是孤立的单词记忆，而是通过连词成句的方式，理解句子结构，掌握语法规则。

2.📊 渐进式课程体系 从简单句到复杂句，从基础语法到高级表达，55个精心设计的课程层层递进。

3.🔄 实时反馈机制 每完成一个句子构建，系统立即给出反馈，帮助学习者及时纠正错误。

3. 技术架构

Earthworm 采用现代化的前后端分离架构：

前端技术栈

• 框架：Nuxt 3 + Vue 3
• 样式：TailwindCSS + daisyUI
• 状态管理：Pinia
• 构建工具：Vite

后端技术栈

• 运行环境：Node.js
• 框架：NestJS
• 数据库：PostgreSQL
• 缓存：Redis

4. 📖 Earthworm 完整安装与使用教程（重点来喽）

环境准备

• Node.js >= v20 node --version`
• pnpm >= 8 pnpm -v
• Docker 任意现代版本 docker --version
• Postgres >= 14.0.0 由 Docker 提供，无需本地安装
• Redis >= 5.0.0 由 Docker 提供，无需本地安装

检查环境

打开终端（Windows 使用 PowerShell）

# 检查 Node.js 版本
node --version  # 应显示 v20+
# 检查 pnpm 版本
pnpm --version  # 应显示 8+
# 检查 Docker 版本
docker --version
docker ps  # 确保 Docker 正在运行

快速安装

步骤1：克隆项目

  git clone https://github.com/cuixueshe/earthworm.git
  cd earthworm

步骤2：安装依赖

  pnpm install

步骤3：配置环境变量

# 后端配置
cp apps/api/.env.example apps/api/.env

# 前端配置
cp apps/client/.env.example apps/client/.env

步骤4：解压 Logto 认证数据

# Windows PowerShell
Expand-Archive -Path "logto_db_init_data.zip" -DestinationPath ".volumes\" -Force

# Linux/macOS
unzip logto_db_init_data.zip -d .volumes/

步骤5：启动数据库服务

pnpm docker:start

步骤6：初始化数据库

pnpm db:init
pnpm db:upload

步骤7：启动应用

  #终端1 - 后端服务
  pnpm dev:serve

终端2 - 前端服务(再开一个终端)
# 为避免端口冲突，设置前端端口为 5173
$env:PORT = "5173"  # Windows PowerShell
# export PORT=5173  # Linux/macOS
pnpm dev:client

步骤8：访问应用

• 前端应用：http://localhost:5173
• Logto 管理后台：http://localhost:3011

📌重要

用户信息自己注册

5. 常见问题

Q1: pnpm install 时报 argon2 错误

• 解决方案：

# 确保 Docker 正在运行
docker ps

# 安装 Windows 构建工具
npm install --global windows-build-tools

# 重新安装依赖
pnpm install

Q2: 数据库连接失败

# 1. 确认 Docker 容器运行
docker ps
# 2. 检查数据库端口
netstat -ano | findstr :5433
# 3. 查看容器日志
docker logs earthworm-db-1

Q3: Logto 登录报错 "session mismatch"

# 1. 重新解压 Logto 数据
Remove-Item -Recurse -Force .volumes -ErrorAction SilentlyContinue
Expand-Archive -Path "logto_db_init_data.zip" -DestinationPath ".volumes\" -Force
# 2. 重启容器
pnpm docker:stop
pnpm docker:start
# 3. 清除浏览器缓存后重试

Q4: 前端无法连接后端

# 1. 确认后端运行在 3000 端口
curl http://localhost:3000/health

# 2. 检查前端 .env 配置
cat apps/client/.env
# 确保 VITE_API_URL=http://localhost:3000

Q5: 上传课程时外键约束错误

# 清空数据库表
docker exec -it earthworm-db-1 psql -U postgres -d earthworm

# 在 PostgreSQL 中执行
TRUNCATE TABLE courses CASCADE;
TRUNCATE TABLE course_packs CASCADE;
\q

# 重新上传
pnpm db:upload

安装 Windows 构建工具

npm install --global windows-build-tools

重新安装依赖

pnpm install

代码块

// JavaScript 示例
function hello() {
  console.log('Hello, WeMD!');
  const a = 1;
  const b = 2;
  return a + b;
}

6. 自定义课程(小例子)

添加新课程

1.进入课程目录：

cd packages/xingrong-courses/courses

2.复制现有课程作为模板：

# Windows
copy 55.json 56.json

# Linux/macOS
cp 55.json 56.json

3.编辑 56.json，修改为您的课程内容：

{
  "order": 56,
  "title": "四级翻译训练",
  "courses": [
    {
      "title": "中国文化",
      "sentences": [
        {
          "english": "The Spring Festival is the most important traditional festival in China.",
          "chinese": "春节是中国最重要的传统节日。"
        }
      ]
    }
  ]
}

4.重新上传数据：

cd ../../..
pnpm db:upload

创建独立的课程包（另一种办法）

1.复制现有包：

cd packages
cp -r xingrong-courses cet4-translation

2.修改 cet4-translation/package.json 中的包名 3.清空 courses 目录，添加自己的课程文件 4.在项目根目录的 package.json 中添加新的上传命令

7. 最后的最后

Earthworm 不仅是一个实用的英语学习工具，更是一个展示现代 Web 开发最佳实践的开源项目。通过本文档，您应该能够：

• ✅ 成功在本地部署 Earthworm
• ✅ 理解项目的核心功能和使用方法
• ✅ 解决常见的安装和运行问题
• ✅ 根据需求自定义和扩展课程内容 如果您在安装使用过程中遇到任何问题，欢迎查阅项目的 GitHub Issues 或参与社区讨论，一起让 Earthworm 变得更好！ 项目地址：https://github.com/cuixueshe/earthworm 作者：cuixueshe