从零搭建一个现代化后台管理系统：基于 React 19 + Vite + Ant Design Pro 的最佳实践

从零搭建一个现代化后台管理系统：基于 React 19 + Vite + Ant Design Pro 的最佳实践

前言

最近在工作中需要搭建一个新的后台管理系统，考虑到项目规模和团队技术栈，我选择了 React + Ant Design 作为基础。但 Ant Design Pro 虽然功能强大，对于中小型项目来说显得有些"过重"，配置也比较复杂。

于是，我花了一些时间，基于最新的技术栈搭建了一个轻量级的后台管理系统模板------AntD Pro Lite。这个项目既保留了 Ant Design Pro 的核心优势，又去除了很多不必要的复杂度，更适合快速启动项目。

项目地址：github.com/secret821/r...

为什么需要这个项目？

在做技术选型的时候，我主要考虑了以下几点：

1. 开发效率：需要一个开箱即用的后台模板，而不是从零开始
2. 技术前瞻性：使用最新的 React 19、Vite 7 等现代工具
3. 灵活性强：不绑定太多预设配置，方便后续扩展
4. 代码质量：TypeScript、ESLint、Prettier 等工具链完整

基于这些考虑，我搭建了这个项目，它既保持了 Ant Design Pro 的优秀体验，又提供了更灵活的自定义空间。

技术栈选择

核心框架

• React 19：最新的 React 版本，带来了更好的性能和开发体验
• TypeScript：类型安全，提升代码质量和开发效率
• Vite 7：极速的开发服务器和构建工具，开发体验非常流畅

UI 组件库

• Ant Design 5：成熟的组件库，组件丰富且文档完善
• @ant-design/pro-components：Pro 系列组件，特别是 ProLayout 和 ProTable，大大提升了开发效率
• Tailwind CSS v4：原子化 CSS，与 Ant Design 配合使用，既能快速开发又能精细调整样式

状态管理与数据获取

• Zustand：轻量级状态管理库，用于全局状态（如用户认证信息）
• React Query (TanStack Query)：强大的数据获取和缓存库，处理服务端状态的最佳选择
• React Router v7：路由管理，配合路由守卫实现权限控制

其他工具

• i18next：国际化支持，内置中英文切换
• Axios：HTTP 客户端
• clsx + tailwind-merge：类名合并工具，优雅地处理条件样式

核心特性

1. 完整的认证体系

项目实现了基于 Cookie + Zustand 的认证方案：

// 路由守卫，自动判断登录状态
const ProtectedRoute = ({ children }) => {
  const { auth } = useAuthStore()
  if (!auth.accessToken) {
    return <Navigate to="/login" replace />
  }
  return children
}

未登录用户访问受保护页面时会自动跳转到登录页，已登录用户访问登录页会自动跳转到首页，体验非常流畅。

2. 优雅的布局系统

使用 ProLayout 构建的混合布局，支持侧边栏收起/展开：

• 顶部导航栏：显示系统标题和语言切换
• 侧边栏：菜单导航，支持图标和文字
• 底部用户信息：显示用户头像、邮箱和退出按钮
• 响应式设计：自适应不同屏幕尺寸

3. 强大的表格组件

基于 ProTable 实现的数据表格，内置了：

• 搜索功能
• 排序功能
• 分页功能
• 工具栏操作（新增、导出等）

只需要配置列定义，就能快速搭建一个功能完整的表格页面。

4. 国际化支持

内置 i18next，支持中英文切换。所有文本都通过翻译键管理，方便后续扩展更多语言。语言选择器位于顶部导航栏，切换即时生效。

5. 现代化的样式方案

采用 Tailwind CSS v4 + Ant Design 的组合：

• Tailwind 提供原子化工具类，快速开发
• Ant Design 提供完整的组件样式
• 两者结合，既能快速开发又能精细定制

项目还配置了 clsx 和 tailwind-merge，优雅地处理条件类名合并。

项目结构

src/
├── main.tsx              # 应用入口
├── router.tsx            # 路由配置（含路由守卫）
├── styles/               # 全局样式
│   ├── index.css
│   └── tailwind-theme.css  # Tailwind 主题配置
├── lib/                  # 工具库
│   └── cookies.ts        # Cookie 操作
├── stores/               # 状态管理
│   └── auth-store.ts     # 认证状态（Zustand）
├── context/              # React Context
│   └── AuthProvider.tsx  # 认证上下文
├── hooks/                # 自定义 Hooks
│   └── useLanguage.ts    # 语言切换 Hook
├── i18n/                 # 国际化配置
│   ├── config.ts
│   └── locales/          # 语言文件
├── utils/                # 工具函数
│   └── cn.ts             # 类名合并工具
├── layout/               # 布局组件
│   └── ProShell.tsx      # 主布局
├── pages/                # 页面组件
│   ├── LoginPage.tsx
│   ├── Dashboard.tsx
│   └── StockOrderList.tsx
└── services/             # API 服务
    └── stock.ts

结构清晰，职责分明，易于维护和扩展。

快速开始

安装依赖

pnpm install

启动开发服务器

pnpm dev

访问 http://localhost:5173 即可看到项目运行。

构建生产版本

pnpm build

预览构建结果

pnpm preview

开发体验优化

代码格式化

项目配置了 Prettier，支持自动格式化：

# 格式化所有代码
pnpm format

# 检查代码格式
pnpm format:check

Prettier 配置了 Tailwind CSS 类名排序、导入排序等功能，确保代码风格一致。

TypeScript 支持

完整的 TypeScript 配置，提供良好的类型提示和错误检查。

ESLint

配置了 ESLint，确保代码质量。在构建时会自动检查。

实际使用建议

这个模板适合以下场景：

1. 中小型后台管理系统：功能相对简单，不需要太复杂的权限系统
2. 快速原型开发：需要快速搭建一个可用的后台界面
3. 学习和参考：想了解现代 React 项目的搭建方式

如果是大型项目，建议根据实际需求进行扩展，比如：

• 添加更细粒度的权限控制
• 集成更多的业务组件
• 配置更复杂的路由结构
• 接入真实的认证服务

一些设计思考

为什么选择 Zustand 而不是 Redux？

对于后台管理系统来说，全局状态相对简单（主要是用户信息），Zustand 的 API 更简洁，学习成本更低，完全够用。

为什么使用 React Query？

服务端状态管理是后台系统的重要组成部分。React Query 提供了强大的缓存、重试、轮询等功能，使用它来处理 API 请求会让代码更简洁、性能更好。

Tailwind CSS 和 Ant Design 如何共存？

Ant Design 提供了完整的组件样式，Tailwind 主要用于：

• 布局相关的工具类（flex、grid、spacing 等）
• 自定义样式调整
• 快速原型开发

两者配合使用，既有组件库的便利，又有原子化 CSS 的灵活。

部署

项目配置了 GitHub Actions，可以自动部署到 GitHub Pages。部署配置已包含在 .github/workflows/deploy.yml 中，只需要：

1. 在 GitHub 仓库的 Settings → Pages 中，将 Source 设置为 "GitHub Actions"
2. 推送代码到 main 分支
3. Actions 会自动构建并部署

总结

这个项目是我在实际开发中总结出的一套最佳实践，它：

• ✅ 使用了最新的技术栈
• ✅ 代码结构清晰，易于维护
• ✅ 开箱即用，快速启动项目
• ✅ 保留了足够的灵活性，方便扩展
• ✅ 配置了完整的开发工具链

如果你也在寻找一个轻量级的后台管理系统模板，或者想学习现代 React 项目的搭建方式，不妨看看这个项目。欢迎 Star 和 Fork，也欢迎提出 Issue 和 PR。

项目地址：github.com/secret821/r...

License

MIT