乐笙-Luxsin 产品官网 技术栈文档
项目概述
乐笙（Luxsin）产品官网，采用前后端分离架构。前端官网页面内容大部分由后台管理平台灵活配置，实现 CMS 级别的内容管理能力。
官网 CMS 管理功能并入现有的 dashboard 项目（耳机品牌与型号管理平台），共享同一套后端 API 和数据库，不再单独维护 admin 和 server。
架构总览
- Web 前端（www）：面向用户的产品展示官网（SPA）
- 管理后台（dashboard/frontend）：soybean-admin，新增「官网管理」菜单模块
- API 服务（dashboard/backend）：Express + TypeScript + Drizzle ORM，统一提供数据接口
- 数据库：MySQL（复用现有
audio 数据库）
目录结构
Web 前端 (www/)
| 技术 |
版本 |
说明 |
| Nuxt 4 |
4.5+ |
应用框架，SPA 模式，文件路由、自动导入、app/ 源码目录规范 |
| Vue 3 |
3.5+ |
UI 框架，Composition API + <script setup> |
| TypeScript |
5.x |
全量类型安全 |
| UnoCSS |
66+ |
原子化 CSS 引擎（presetWind3），与 Admin 统一 |
| Pinia |
4.x |
状态管理 |
| @nuxtjs/i18n |
10.x |
国际化（中英双语，自动检测 i18n/locales/） |
| ofetch |
内置 |
HTTP 请求（Nuxt 内置） |
| @vueuse/nuxt |
14.x |
常用组合式工具函数（自动导入） |
| vue-router |
5.x |
路由（Nuxt 内置，history 模式） |
| Vite |
8.x |
构建工具（Nuxt 内置） |
| pnpm |
11.x |
包管理器 |
目录规范（Nuxt 4）
Nuxt 4 引入 app/ 源码目录，将应用代码与项目根配置分离：
设计原则
- SPA 模式渲染，通过 API 获取后台配置的内容数据
- 组件化开发，页面由可配置的区块（Section）组合而成
- 中英双语支持，路由级别的语言切换（中文默认无前缀，英文
/en 前缀）
- 响应式设计，适配桌面端和移动端
- 预留 SSR/SSG 升级能力（Nuxt 可无缝切换渲染模式）
管理后台（dashboard/frontend）
复用现有 dashboard 项目的 soybean-admin 前端，新增「官网管理」菜单模块。
| 技术 |
版本 |
说明 |
| soybean-admin |
v2.2.0 |
管理后台 UI 框架 |
| Vue 3 |
3.5+ |
UI 框架 |
| Vite |
8.x |
构建工具 |
| Naive UI |
2.44+ |
UI 组件库 |
| UnoCSS |
66+ |
原子化 CSS |
| Pinia |
3.x |
状态管理 |
| vue-router |
5.x |
路由（history 模式） |
| vue-i18n |
11.x |
国际化 |
| TypeScript |
6.x |
类型安全 |
| pnpm |
10.5+ |
包管理器（workspace） |
新增功能模块（官网管理）
- 官网页面内容管理（Banner、产品、新闻、FAQ 等）
- 页面区块的增删改查与排序
- 媒体资源管理（图片、视频）
- 官网系统配置管理
后端 API 服务（dashboard/backend）
| 技术 |
说明 |
| Express 4 |
Web 框架（保留现有） |
| TypeScript |
全量类型安全（从 JS 迁移） |
| Drizzle ORM |
类型安全 ORM，替代原 Sequelize |
| MySQL (mysql2) |
数据库（复用现有 audio 库） |
| Zod |
请求参数校验与类型推导 |
| tsx |
TypeScript 运行/开发热重载 |
| pnpm |
包管理器 |
API 路由规划
| 前缀 |
用途 |
鉴权 |
/api/www/* |
官网前台接口（供 Nuxt 4 消费） |
公开访问 |
/api/admin/www/* |
官网 CMS 管理接口（供 dashboard 前端消费） |
JWT 鉴权 |
/api/*（其他） |
现有 dashboard 业务接口 |
JWT 鉴权 |
API 设计原则
- RESTful 风格
- 统一响应格式：
{ code, data, message }
- 与 soybean-admin 约定成功码
0000
- 前台接口公开，管理接口需 JWT 鉴权
数据库
| 项目 |
说明 |
| 数据库 |
MySQL（复用现有 audio 库） |
| ORM |
Drizzle ORM（mysql2 驱动） |
| 迁移 |
drizzle-kit（Schema 变更自动生成迁移文件） |
| 命名规范 |
表名 snake_case，字段名 snake_case |
| 字符集 |
utf8mb4 |
开发环境要求
| 工具 |
版本要求 |
| Node.js |
>= 20.19.0 |
| pnpm |
>= 10.5.0 |
| MySQL |
>= 8.0 |
| TypeScript |
>= 5.x |
项目管理
两个独立项目，各自管理：
| 项目 |
路径 |
说明 |
| www |
www/ |
官网前端（Nuxt 4），独立 pnpm 项目 |
| dashboard |
dashboard/ |
管理后台 + API 服务，pnpm workspace（frontend + backend） |
部署方案（待定）
| 模块 |
候选方案 |
| Web 前端（www） |
Vercel / Cloudflare Pages / Nginx 静态托管 |
| 管理后台（dashboard/frontend） |
Nginx 静态托管（现有方案） |
| API 服务（dashboard/backend） |
Docker 容器（现有方案，端口 8083） |
| 数据库 |
现有 MySQL 实例 |
技术选型理由
为什么选 Nuxt 4（SPA 模式）？
- 与 dashboard 管理后台统一 Vue 生态，降低团队学习和维护成本
app/ 目录规范让项目结构更清晰，配置与源码分离- 文件路由 + 自动导入提升开发效率
- 未来可无缝升级 SSR/SSG，无需重构
- @nuxtjs/i18n v10 提供更简洁的配置（自动检测 locale 文件）
为什么复用 dashboard 而非独立建 admin + server？
- dashboard 前端本身就是 soybean-admin，无需重复搭建
- 共享用户体系和权限管理，运营人员一个后台管理所有业务
- 减少项目数量，降低部署和维护成本
- 数据库统一为 MySQL，避免多数据源复杂度
为什么从 Sequelize 迁移到 Drizzle ORM？
- 类型安全，Schema 即类型定义，与 TypeScript 深度集成
- SQL-like API，学习成本低，性能透明
- 内置 drizzle-kit 迁移工具，版本化管理数据库变更（替代
sequelize.sync()）
- 轻量无依赖，不锁定数据库连接方案
为什么保留 Express 而非换 Hono？
- dashboard 后端已有大量 Express 路由和中间件，迁移 ORM 已足够
- Express 生态成熟，团队熟悉
- 避免同时迁移框架 + ORM + 语言，降低风险
eafonyang