当前位置：首页 > news >正文

基于Next.js与FSD架构的现代健身教练平台开发全解析

news 2026/5/3 2:36:00

1. 项目概述：一个现代健身教练平台的诞生

如果你和我一样，既是一个健身爱好者，又对技术充满热情，那么你肯定也经历过这样的困境：市面上那些健身App要么功能臃肿、广告满天飞，要么就是闭源、收费昂贵，数据还锁死在他们的服务器里。几年前，一个名为 workout.lol 的开源项目曾让我眼前一亮，它简洁、现代，完全符合我对一个私人健身工具的所有想象。然而，这个项目最终因为商业合作和视频版权成本等问题被出售，随后便陷入了停滞，社区的热情也随之冷却。作为一个深度参与过原项目的贡献者，我亲眼目睹了这一切，也感受到了社区成员的失落。正是这份不甘心，驱使我决定从头开始，打造一个全新的、更强大的、真正属于社区的现代健身教练平台——这就是workout.cool。

workout.cool 不仅仅是一个健身计划生成器或记录工具，它是一个综合性的健身教练平台。它的核心是围绕一个全面的动作数据库构建的，这个数据库包含了详尽的动作说明、执行要点，甚至视频演示。基于这个数据库，平台可以为你智能生成个性化的训练计划，让你能够系统地追踪每一次训练的组数、次数、重量和身体感受，从而清晰地看到自己的进步轨迹。无论你是刚刚踏入健身房的新手，还是寻求突破瓶颈的资深训练者，这个工具都能为你提供结构化的指导，让你的训练不再盲目。

2. 项目架构与核心技术选型解析

2.1 为什么选择 Next.js 与 App Router？

在技术栈的选型上，我毫不犹豫地选择了Next.js，并且采用了其最新的App Router架构。这背后有几个核心考量。首先，Next.js 提供了开箱即用的服务端渲染（SSR）和静态生成（SSG）能力，这对于一个内容驱动型应用至关重要。动作库的页面、训练计划详情页，这些内容非常适合预渲染，能极大提升首次加载速度和搜索引擎优化效果。其次，App Router 基于 React Server Components，允许我们更自然地在服务器端处理数据获取和业务逻辑。例如，获取用户训练记录、查询动作详情这些操作，可以直接在服务器组件中完成，无需先加载一个空壳页面再通过客户端useEffect去获取数据，这带来了更快的初始渲染和更精简的客户端代码。

注意：从 Pages Router 迁移到 App Router 需要思维上的转变。最大的挑战在于理解 Server Components 和 Client Components 的边界。我的经验是，默认将所有组件视为 Server Component，只有在明确需要交互性（如useState,useEffect,onClick）或浏览器 API（如localStorage）时，才在文件顶部添加“use client”指令。这能最大化利用服务端渲染的优势。

2.2 采用 Feature-Sliced Design (FSD) 进行代码组织

随着功能增多，代码库很容易变得混乱不堪。为了避免重蹈许多项目“面条式代码”的覆辙，我决定采用Feature-Sliced Design架构模式。FSD 的核心思想是按业务功能（Feature）来切片和组织代码，而不是按技术角色（如 components, hooks, utils）。在 workout.cool 的src/目录下，你可以看到清晰的分层：

shared/: 存放真正跨领域共享的代码，如 UI 组件库（基于 shadcn/ui）、工具函数、配置文件。这里的代码应该对业务一无所知。
entities/: 定义核心业务实体，如User（用户）、Exercise（动作）、WorkoutPlan（训练计划）。这里主要是 TypeScript 类型定义、Prisma 模型以及一些与实体相关的纯函数。
features/: 这是 FSD 的核心。每个独立的业务功能都是一个文件夹，例如auth（认证）、exercise-management（动作管理）、workout-planning（计划制定）。每个 feature 内部是自包含的，拥有自己的ui/（组件）、model/（状态、hooks）、lib/（业务逻辑）、api/（服务端动作）。
widgets/: 组合多个 features 形成的复杂 UI 模块，例如侧边栏导航、页面头部，它们本身不直接对应某个业务实体。
processes/: 描述跨越多个 features 的复杂用户流程，例如“用户从注册到完成第一个训练计划”这个流程。
app/: Next.js 的页面路由层，负责将上述所有模块组合成具体的页面。

这种架构的优势在于极强的可维护性和可预测性。当需要修改“动作管理”功能时，你几乎只需要在features/exercise-management目录下工作，不会意外影响到用户认证模块。新成员加入项目，也能通过目录结构快速理解业务边界。

2.3 后端与数据层：Prisma + PostgreSQL 的组合拳

对于数据层，我选择了Prisma作为 ORM，搭配PostgreSQL数据库。Prisma 以其类型安全的数据库查询和直观的数据模型定义而著称。在prisma/schema.prisma文件中，你可以像这样定义一个Exercise（动作）模型：

model Exercise { id Int @id @default(autoincrement()) name String // 动作名称（如“杠铃深蹲”） nameEn String? @map(“name_en”) // 英文名称 slug String @unique // URL 友好标识 description String? // 详细描述（HTML格式） primaryMuscle MuscleGroup? @relation(fields: [primaryMuscleId], references: [id]) primaryMuscleId Int? equipment Equipment[] @relation(“ExerciseEquipment”) // 所需器械 videos Video[] // 关联的视频 createdAt DateTime @default(now()) updatedAt DateTime @updatedAt @@map(“exercises”) }

这种定义方式不仅生成了数据库表，还自动为 TypeScript 生成了完全类型化的PrismaClient。这意味着你在编写查询时，如prisma.exercise.findMany({ where: { primaryMuscle: { name: “Chest” } } })，能获得完美的代码自动补全和类型检查，几乎杜绝了因字段名拼写错误导致的运行时bug。

PostgreSQL 作为关系型数据库，其稳定性和丰富的功能（如 JSONB 类型存储训练记录中的灵活数据、全文搜索用于动作库检索）是项目的坚实后盾。通过 Docker 进行容器化部署，也保证了开发、测试、生产环境的高度一致性。

2.4 前端 UI 与样式：Radix UI 与 shadcn/ui 的化学反应

为了构建一个既美观又具备高可访问性的用户界面，我选择了Radix UI作为底层原始组件库，并在此基础上采用了shadcn/ui的方案。Radix UI 提供了完全无样式、功能完备的 UI 原语（如 Dialog, Dropdown Menu, Tabs），它们解决了复杂的交互逻辑和可访问性问题。而 shadcn/ui 本质上是一套基于 Tailwind CSS 的、可自由定制的组件样式模板。

这样做的好处是极致的控制权。不同于直接引入一个完整的组件库（如 MUI），shadcn/ui 允许你将组件代码直接复制到你的项目中，成为你代码库的一部分。你可以随意修改这些组件的任何样式或行为，而无需担心版本升级带来的破坏性变更，也无需处理繁琐的theme provider覆盖。结合Tailwind CSS的原子化工具类，UI 的开发变得快速且一致。例如，一个训练计划卡片组件可以快速搭建，并确保与整个应用的设计系统保持一致。

3. 核心功能实现与实操要点

3.1 构建可扩展的动作数据库

动作数据库是 workout.cool 的基石。设计时，我重点考虑了可扩展性和多语言支持。一个动作（Exercise）不仅仅有名称和描述，它关联着目标肌群（MuscleGroup）、所需器械（Equipment）、动作类型（如力量、有氧）、难度级别，以及最重要的——教学视频（Video）。

数据库关系设计如下：

Exercise 与 MuscleGroup: 多对多关系。一个深蹲主要刺激股四头肌，但也涉及臀大肌和核心肌群。
Exercise 与 Equipment: 多对多关系。一个动作可能需要杠铃、哑铃或徒手完成。
Exercise 与 Video: 一对多关系。一个动作可以有多个角度的演示视频。

为了实现多语言，我为name、description等字段设计了对应的nameEn、descriptionEn字段。在前端，可以根据用户的语言偏好动态切换。视频资源则通过full_video_url链接到外部平台（如 YouTube），并缓存其缩略图full_video_image_url，这样既避免了天价的视频存储与流量成本，又保证了内容的丰富性。

实操心得：CSV 数据导入策略项目提供了pnpm run import:exercises-full脚本来从 CSV 文件批量导入动作数据。这里有个关键细节：CSV 文件需要处理“一对多”关系。如上文示例，同一条动作（相同id）在 CSV 中会以多行存在，通过attribute_name和attribute_value来标记不同的属性（如TYPE: STRENGTH,PRIMARY_MUSCLE: QUADRICEPS）。在导入脚本中，需要先解析 CSV，将同一id的数据行聚合，再创建包含所有关联数据的完整 Exercise 记录。这比维护多个关联 CSV 文件要方便得多。

3.2 智能化训练计划生成引擎

生成训练计划是平台的核心智能所在。我的设计思路是基于规则与偏好结合，而非复杂的黑盒AI模型，以保证计划的透明度和可解释性。

用户画像收集：首先，系统会通过问卷收集用户信息：训练目标（增肌、减脂、提升力量）、训练经验（新手、中级、高级）、每周可用训练天数、偏好训练部位、可用器械等。
动作池筛选：根据用户画像，从动作数据库中筛选出符合条件的动作。例如，一个目标是“增肌”且只有哑铃的用户，系统会优先筛选出哑铃相关的复合动作（如哑铃卧推、哑铃划船）和孤立动作。
计划模板匹配：系统内置了几种经典的训练分割模板，如“全身训练”、“上下肢分化”、“推/拉/腿分化”。根据用户每周训练天数，自动匹配最合适的模板。
动作编排与容量设定：将筛选出的动作填充到模板的每一天中。遵循“先复合后孤立”、“上下肢/推拉平衡”的原则。并为每个动作设定初始的组数、次数建议。例如，新手增肌计划可能推荐每个复合动作做3-4组，每组8-12次。
渐进超负荷逻辑：计划不是静态的。系统会追踪用户每次训练的实际完成情况（如最后一组是否轻松完成）。基于此，在下一周或下一循环中，会自动建议微调重量或增加次数，实现渐进超负荷，这是持续进步的关键。

这个引擎的逻辑主要封装在features/workout-planning/lib/generator.ts中，它纯粹是服务端的业务逻辑，通过 API 路由或 Server Action 提供给前端调用。

3.3 训练记录与进度追踪

记录功能的设计追求快速与无感。在训练界面，用户面对的是一个针对当日计划的、极简的记录表。

// 一个简化版的训练记录数据结构 interface WorkoutSet { id: string; exerciseId: number; targetReps: number; // 计划目标次数 actualReps: number; // 实际完成次数 weight: number; // 使用的重量（kg/lb） rpe: number; // 主观用力程度，1-10分 notes?: string; // 备注，如“感觉不稳定” } interface WorkoutSession { id: string; planId: string; date: Date; sets: WorkoutSet[]; overallFeeling: ‘great’ | ‘good’ | ‘average’ | ‘poor’; }

用户只需点击“+”增加一组，输入重量和次数即可。系统会自动保存草稿，防止意外退出丢失数据。RPE（自感用力度）的录入是一个专业功能，帮助高级训练者更精细地调控强度。所有记录最终关联到用户和具体的训练计划，用于生成长期的力量曲线图、容量趋势图等可视化报告，让进步一目了然。

3.4 用户认证与数据安全

我选择了Better Auth作为认证解决方案。它是一个开源、可自托管的现代认证库，完美适配 Next.js App Router，支持多种登录方式（邮箱/密码、OAuth等）。相比于自己从头实现认证逻辑，使用 Better Auth 能避免很多安全陷阱（如密码哈希、会话管理、CSRF 防护）。

关键配置在于将会话管理、数据库适配与 Prisma 集成。所有用户相关的数据（训练计划、记录）都通过userId进行严格隔离，确保用户只能访问自己的数据。API 路由和 Server Actions 中都会验证会话，这是数据安全的第一道防线。

4. 本地开发与部署实操指南

4.1 两种本地开发环境搭建

项目支持 Docker 和非 Docker 两种开发方式，推荐使用Docker以获得一致的环境。

🐳 Docker 开发流程（推荐）

确保本地已安装 Docker 和 Docker Compose。
克隆项目后，复制环境变量模板：cp .env.example .env。你只需要关注少数几个变量，如本地端口，数据库配置在 Docker Compose 文件中已预设好。
运行make dev命令。这个 Makefile 指令会依次执行：
- 启动 PostgreSQL 和 Redis（如果用到）容器。
- 运行数据库迁移（prisma migrate dev），在数据库中创建所有表。
- 可选地，运行种子脚本，导入示例动作数据。
- 启动 Next.js 开发服务器，并开启热重载。
打开浏览器访问http://localhost:3000，你将看到一个完整的、带示例数据的 workout.cool 应用。

避坑提示：如果遇到数据库连接错误，请检查.env文件中的DATABASE_URL。在 Docker 环境下，主机名应为postgres（服务名），而不是localhost。例如：DATABASE_URL=“postgresql://postgres:yourpassword@postgres:5432/workout_cool?schema=public”。

💻 非 Docker 手动安装如果你偏好原生环境，则需要：

安装 Node.js (v18+)、pnpm 和 PostgreSQL。
在 PostgreSQL 中手动创建数据库：createdb workout_cool。
同样复制.env文件，并将DATABASE_URL指向你的本地 PostgreSQL 实例。
运行pnpm install安装依赖，然后执行npx prisma migrate dev和pnpm dev。

两种方式都能顺利运行，但 Docker 方式免去了手动安装和配置数据库的麻烦，尤其适合团队协作，确保所有人的环境完全一致。

4.2 生产环境部署详解

对于生产部署，安全性和性能是首要考虑因素。

使用 Docker Compose 部署（最简单）这是自托管最推荐的方式。项目根目录下的docker-compose.prod.yml文件定义了生产服务栈：

version: ‘3.8’ services: postgres: image: postgres:16-alpine environment: POSTGRES_DB: workout_cool POSTGRES_USER: ${DB_USER} POSTGRES_PASSWORD: ${DB_PASSWORD} volumes: - postgres_data:/var/lib/postgresql/data healthcheck: { ... } app: build: . ports: - “${APP_PORT}:3000” environment: DATABASE_URL: postgresql://${DB_USER}:${DB_PASSWORD}@postgres:5432/workout_cool NODE_ENV: production depends_on: postgres: condition: service_healthy

部署步骤：

在服务器上安装 Docker 和 Docker Compose。
将项目代码克隆至服务器。
创建.env.production文件，填写强密码的数据库凭证、密钥等。
运行docker-compose -f docker-compose.prod.yml up -d，所有服务将后台运行。
使用 Nginx 或 Caddy 作为反向代理，配置域名、SSL 证书，并将流量转发到容器的 3000 端口。

手动部署到 VPS如果你熟悉 Node.js 生产环境，也可以手动部署：

在服务器上安装 Node.js, pnpm, PostgreSQL。
构建应用：pnpm run build，这会生成一个优化的.next输出目录。
运行数据库迁移：NODE_ENV=production npx prisma migrate deploy。
使用 PM2 等进程管理器启动应用：pm2 start pnpm –name “workout-cool” – start。
同样配置反向代理和 SSL。

部署到 Vercel（针对前端，需分离后端）workout.cool 是全栈应用，直接部署到 Vercel 需要处理数据库连接（可能被墙或延迟高）。一个更优的架构是：将前端（Next.js）部署在 Vercel，将 PostgreSQL 数据库部署在可公开访问的云服务（如 AWS RDS、Supabase 或 Neon），并确保 Vercel 的环境变量正确配置了远程数据库连接字符串。这种模式利用了 Vercel 的全球 CDN 和自动 HTTPS，同时保证了数据库的稳定可控。

4.3 数据迁移与备份策略

对于用户来说，数据是无价的。在自托管时，必须建立定期备份机制。Docker Compose 配置中已经将 PostgreSQL 数据卷挂载到postgres_data。最简单的备份方式是定期执行pg_dump命令：

# 在宿主机上执行，将数据库备份到文件 docker exec workout-cool-postgres-1 pg_dump -U postgres workout_cool > backup_$(date +%Y%m%d).sql

可以将此命令加入服务器的 crontab，实现每日自动备份，并将备份文件同步到远程存储（如 AWS S3、Backblaze B2）。同时，务必在.env.production中使用强密码，并考虑将数据库服务置于内部网络，仅允许应用容器访问，以增强安全性。

5. 常见问题排查与社区贡献

5.1 开发与部署中的常见问题

在开发和部署 workout.cool 的过程中，我遇到并解决了不少典型问题，这里记录下排查思路：

1. 数据库连接失败（Docker 环境）

症状：应用启动时报错PrismaClientInitializationError，提示无法连接到数据库。
排查：
- 首先运行docker ps确认 PostgreSQL 容器正在运行。
- 检查应用容器的DATABASE_URL环境变量。在 Docker Compose 网络内，主机名应为服务名postgres，端口为内部端口5432。
- 进入 PostgreSQL 容器 (docker exec -it <container_id> psql -U postgres)，手动检查workout_cool数据库和表是否存在。
解决：确保docker-compose.yml中应用服务depends_on数据库服务，并配置了condition: service_healthy，等待数据库就绪后再启动应用。

2. Prisma 迁移冲突

症状：多人协作开发时，同时修改了schema.prisma并生成迁移，导致合并冲突。
排查：查看prisma/migrations目录下的迁移文件历史，找到冲突的迁移记录。
解决：
- 沟通协调，按顺序应用迁移。
- 如果是在开发分支，可以重置数据库 (npx prisma migrate reset) 并重新应用所有迁移。切勿在生产环境使用reset。
- 最佳实践是：每次修改 schema 前，先拉取最新代码；生成迁移后立即提交。

3. 导入 CSV 数据时外键约束错误

症状：运行pnpm run import:exercises-full时，报错提示Foreign key constraint failed。
排查：CSV 数据中引用了不存在的关联记录 ID。例如，一个动作的primaryMuscleId指向了一个数据库中不存在的肌群 ID。
解决：确保 CSV 导入遵循正确的顺序。通常需要先导入基础实体（如MuscleGroup,Equipment），再导入关联它们的Exercise。检查提供的 CSV 示例文件，理解其数据结构和依赖关系。

4. 生产环境静态资源加载 404

症状：部署后，Logo、用户上传的图片等静态资源无法加载。
排查：Next.js 在构建时，public目录下的文件会被复制到输出目录。如果使用 Docker 构建，需要确保COPY public ./public指令正确执行。如果使用对象存储，检查配置的存储桶策略和 CDN 域名。
解决：对于 Docker 部署，确保 Dockerfile 中包含了COPY public ./public。对于 Vercel 等平台，通常会自动处理。自定义服务器部署时，需要配置静态文件中间件。

5.2 如何为 workout.cool 贡献代码

workout.cool 是一个真正的社区项目，我非常欢迎并依赖社区的贡献。以下是清晰的贡献流程：

发现或提出议题：在 GitHub Issues 中查看是否有你想解决的问题。如果没有，可以新建一个 Issue，清晰描述问题或功能建议。
声明工作：在 Issue 下留言，说明你打算解决它，避免重复劳动。
Fork 与分支：Fork 主仓库到你的账户，并基于main分支创建一个描述性的分支，如feat/add-dark-mode或fix/typo-in-exercise-description。
开发与测试：在本地进行修改。遵循项目的代码风格（Prettier + ESLint 已配置）。为你的更改添加或更新测试。确保pnpm run build和pnpm run lint通过。
提交与推送：使用清晰的提交信息，例如feat: add support for RPE input in workout log。将分支推送到你的 Fork。
发起 Pull Request (PR)：在你的 Fork 页面发起 PR 到主仓库的main分支。在 PR 描述中，引用相关的 Issue（如Closes #123），并详细说明你的更改内容、测试方法以及任何需要审查者注意的事项。
代码审查与合并：我会尽快 Review 你的 PR。可能会提出一些修改建议。经过讨论和必要的修改后，PR 将被合并。

给贡献者的建议：

从小处着手。修复一个错别字、完善一个文档句子都是极好的贡献。
在修改功能前，尤其是涉及 FSD 架构的部分，先花点时间理解现有代码的组织方式。
如果你不确定如何实现某个功能，可以在 Issue 或 Discord 社区中先发起讨论。

5.3 项目未来可能的演进方向

作为一个开源项目，workout.cool 的未来由社区共同塑造。目前我脑海中已有一些演进思路，也期待大家的想法：

移动端 PWA：利用 Next.js 的响应式设计和 PWA 能力，让应用可以安装到手机主屏幕，提供接近原生 App 的离线训练记录体验。
高级分析功能：集成更复杂的图表库，提供肌肉疲劳度分析、训练量（Volume）随时间变化趋势、基于 RPE 的自适应计划微调建议。
社区分享与模板：允许用户将自己的训练计划发布为模板，供其他用户一键套用，形成高质量的 UGC 计划库。
API 开放：提供一套完整的 RESTful 或 GraphQL API，让开发者可以构建第三方客户端、集成智能手表数据，或者进行更深入的量化分析。
更多训练模式支持：目前以力量训练为主，未来可以扩展支持耐力训练（跑步、骑行）、HIIT 计时、瑜伽课程等模块。

重启 workout.lol 的精神并构建 workout.cool，对我来说是一次充满挑战但也极其充实的旅程。它验证了现代 Web 技术栈（Next.js 14, Prisma, Tailwind）在构建复杂全栈应用时的强大与高效，也让我深刻体会到清晰的架构（FSD）对于长期维护的重要性。最让我欣慰的是，通过开源，这个工具不再是一个人的项目，而是汇聚了许多同样热爱健身与技术的开发者智慧的作品。每一次 Issue 的提交、每一次 PR 的合并，都让这个平台变得更健壮、更实用。如果你也在寻找一个能完全掌控数据、高度可定制的健身管理工具，不妨尝试部署属于你自己的 workout.cool，或者加入我们，一起把它变得更好。毕竟，最好的健身伙伴，可能就是你自己亲手参与打造的那一个。

查看全文

http://www.jsqmd.com/news/741767/