基于 Yarn workspaces monorepo 的前后端一体 CMS：Nest.js API + React/Antd 管理后台

方案简介

Leaa 是一个 monorepo 结构的 CMS（内容管理系统）开源项目，后端使用 Nest.js（配合 @nestjsx/crud、MySQL、Docker Compose），管理后台（leaa-dashboard）使用 React.js + Ant Design + MobX 构建，官网端（leaa-www）使用 Next.js。整个项目通过 Yarn workspaces 组织成 monorepo，使 API、Dashboard、Website 多端可以共享 TypeScript 的 interface 和可复用配置。项目初衷是作者想用 React/JSX 语法做更多的事情，将以前写前后端的经验汇集起来，做一个 Blog -> CMS -> Shop 的开源项目。它适合希望学习全栈 TypeScript 开发、或需要一个最小可用管理后台骨架作为二次开发基础的开发者。作者认为一个最小可用的 Dashboard 应包括用户（登录/注册）、角色、权限、文件上传、广告、分类、文章、设置这些模块，写完基本上就可以拿来当 Blog 用，有业务需求时基于这样的最小化 Dashboard 开发也很简单。

亮点与能力

• monorepo 架构，多端共享 TS interface 与可复用配置
• 后端基于 Nest.js + @nestjsx/crud + MySQL，Docker Compose 部署
• Dashboard 基于 React + Antd + MobX，全面使用 hooks（含 Apollo hooks）
• GraphQL API，区别于传统 restful 的权限处理
• 最小可用 Dashboard 模块：用户（登录/注册）、角色、权限、文件上传、广告、分类、文章、设置
• 阿里云 OSS 整合：Local 上传、OSS 上传、@2x/@1x 图片生成与备份、删除联动、Local/OSS 可配置
• 权限模块（角色/权限管理）可支撑业务需求扩展

组成与分工

• Nest.js：后端框架，提供一整套范式与 Typescript 支持，用于构建 API
• @nestjsx/crud：Nest.js 的 CRUD 扩展，用于快速生成后端增删改查接口
• MySQL：后端数据库
• Docker Compose：后端容器化部署与编排
• React.js：Dashboard 前端基础框架，全面使用 hooks
• Ant Design (Antd)：Dashboard 的 UI 组件库
• MobX：Dashboard 的状态管理
• GraphQL：API 查询语言，dashboard 通过 Apollo hooks 访问
• Next.js：官网（leaa-www）的 SSR 框架
• Yarn workspaces：monorepo 包管理，使各 package 共享依赖与代码

前置要求

• 需要熟悉 Yarn workspaces，因为项目是 monorepo，安装依赖前可能需要先了解 workspaces 机制
• 后端依赖 MySQL 数据库
• 后端可通过 Docker Compose 运行
• 各子包的安装方式：查看 packages 目录下各子目录的 README.md

安装入口说明：

View the README.md of each sub-directory in packages. You may need to look at yarn workspaces first.

注意：monorepo 下 yarn install 较慢，CPU 占用高；项目曾因 mp/app 等独立仓库无法共享 node_modules 而体积大、安装非常慢。

实施步骤

1. 了解 monorepo 结构

项目是 monorepo，核心 package 包括 leaa-api（后端）与 leaa-dashboard（管理后台），可查看 demo：https://leaa-dashboard.now.sh。

2. 安装依赖

查看 packages 中各子目录的 README.md，并先了解 Yarn workspaces 机制，然后在仓库根目录通过 yarn 安装所有 workspace 的依赖。

3. 启动后端 leaa-api

后端为 Nest.js + @nestjsx/crud + MySQL，通过 Docker Compose 编排 MySQL 等依赖后启动 API 服务。

4. 启动 Dashboard

Dashboard 是 React + Antd + MobX 应用，启动后可通过在线 demo 对照验证功能：用户登录、角色、权限、文件上传、广告、分类、文章、设置等模块。

5. 验证

作者认为最小可用 Dashboard 包括以下模块，启动后逐一验证：

• 用户（登录 / 注册）
• 角色
• 权限
• 文件上传
• 广告
• 分类
• 文章
• 设置

使用与配置要点

• Dashboard 在线 demo：https://leaa-dashboard.now.sh，可用于预览功能效果
• 文件上传模块支持 Local 与 OSS 两种模式，且是否开启均可配置；如 OSS 开启，为保证用户上传速度，所有上传直接走 OSS
• OSS 模式下：上传后备份到 Local；上传 @2x 图片后生成 @1x 上传回 OSS；删除 OSS 文件会联动删除 @1x/@2x 及 Local 对应文件
• 代码规范：.prettierrc 的 printWidth 与 .eslintrc.js 的 max-len 都设置为 120，并在 git commit 时通过 lint 卡 code style

注意事项与常见问题

• monorepo 中有非常多「文件名相似」的文件，找文件时容易被干扰，作者将 Components/Filter/index.tsx 改为 Components/Filter/Filter.tsx 以便 cmd+p 快速定位文件，但仍难摆脱「文件地狱」感
• monorepo 安装慢：每次 yarn install 非常慢，CPU 狂飙；作者曾尝试上 lerna 但问题没好转，只好作罢
• 非标准 web 应用（mp/app）与 monorepo 完全隔离，node_modules 无法共享，若重构建议单独放一个 repo
• React 版本曾锁定在 16.8.6，等待 antd 发版消除 Warning: componentWillMount... 等 warning 后再升级
• 5 端难度排行（作者经验）：mp > app > www > api > dashboard
• Next.js v9 坑较多，大版本变动（如 8to9）有断崖式改动，官方缺乏复杂功能的最佳实践；集成 Antd 时官方 withLess 插件只能管 60%，需要自写 withPlugin
• 项目仍有许多 bug，作者写 leaa 的初衷是让有需要的人能检索到有用的代码

优缺点

• ✓ 一仓库共享 interface 与可复用
• ✓ 最小可用 Dashboard 模块齐全可
• ✕ monorepo 文件多易被干扰
• ✕ 安装慢 CPU 占用高

出处

本方案挖掘自开源项目 SolidZORO/leaa，方案内容与实施命令均来自其 README 原文。