开箱即用的 Vue 3 企业级中后台管理框架
简洁 · 现代 · 可扩展 · 纯前端可独立运行

在线演示 · Gitee 仓库 · GitHub 仓库

KOI-UI 是一款面向企业与个人开发者的 Vue 3 中后台管理模板。基于 Vite 8 + Vue 3.5 + TypeScript + Element Plus 构建，内置权限、路由、布局、主题、国际化等完整基建，代码结构清晰、注释完善，适合作为：

• 企业级管理后台脚手架
• 中小型项目快速启动模板
• 毕业设计 / 学习 Vue 3 生态的实战项目
• 前后端分离项目的标准前端层

相较于同类模板，KOI-UI 更强调 「少递归、少魔法、好对接」：后端菜单无需树形递归，前端扁平路由即可实现无限层级菜单与页面缓存；主题系统采用 CSS 变量 + html class 驱动，切换流畅、易于维护。

前后端版、博客版、大屏案例为付费授权版本，详情见文末「交流与授权」。

• Vite 8 极速构建：HMR、依赖预构建、Gzip 压缩、图片优化、SVG 雪碧图
• TypeScript 全链路：vue-tsc 类型检查，开发体验与可维护性兼顾
• 多环境配置：development / test / production 独立 .env 管理
• 规范化提交：集成 Commitizen + cz-git，统一 Git 提交信息

• 扁平化动态路由：后端返回平铺菜单 JSON，前端自动注册路由，三级及以上页面仍支持 KeepAlive
• 按钮级权限：v-auth 指令控制按钮显隐，对接后端权限码即可
• 路由守卫：登录校验、白名单、动态路由懒加载、版本更新检测

• 9 种布局模式：纵向、分栏、经典、混合、横向、渐变、毛玻璃等，移动端自适应
• CSS 优先主题引擎：布局色通过 theme-vars.scss + html class 切换，性能优于 JS 循环 setProperty
• 主题色阶自动生成：基于 Element Plus 混色算法，一键切换品牌色及 light/dark 色阶
• 暗色 / 灰度 / 色弱 / 头部反转 / 侧边栏反转：开箱即用，首屏无闪烁（localStorage 预恢复）

• 二次封装 Dialog / Drawer / Upload / Excel / Search 等高频组件
• SSE 实时通知：消息推送、未读角标、贴边收缩面板
• 锁屏、全屏、多 Tab、面包屑、菜单搜索 等管理端标配能力
• 集成 ECharts 6、MD Editor、Driver.js 引导、Sortable 拖拽

• UnoCSS 原子化样式：与 SCSS 变量体系互补，快速搭建页面
• Vue I18n 国际化：中英文切换，菜单标题动态翻译
• 自定义指令：防抖、节流、水印、复制、拖拽、表格高度自适应等
• Axios 统一封装：请求/响应拦截、加密解密可选、错误统一处理

系统管理    用户 / 角色 / 菜单 / 部门 / 岗位 / 字典 / 通知 / 文件 / 图片 / 日志
系统监控    在线用户 / 定时任务 / 服务监控 / 缓存 / Redis / 黑名单
博客管理    文章 / 分类 / 标签 / 评论 / 友链 / 说说 / 文库（博客版）
工具模块    代码生成
数据大屏    Dashboard / Console / Analysis 多套可视化布局
其他        首页工作台、个人中心、内链 iframe、多种登录页样式

传统方案中，后端需递归构造树形菜单，前端再二次递归生成路由，开发与联调成本较高。

KOI-UI 采用 扁平菜单 + 前端组装 方案：

1. 后端返回 平铺数组，每条记录含 menuId、parentId、path、component 等字段
2. 前端 generateFlattenRoutes 直接注册一级路由，菜单组件按 parentId 递归渲染
3. 三级及以上路由仍可通过 keep-alive 实现页面缓存

后端菜单示例（无需递归）：

{
  "status": 200,
  "msg": "SUCCESS",
  "data": [
    {
      "menuId": 1,
      "menuName": "系统管理",
      "parentId": 0,
      "menuType": "1",
      "path": "/system",
      "name": "systemPage",
      "component": "",
      "icon": "Tools",
      "isVisible": "1",
      "redirect": "/system/user",
      "isKeepAlive": "0",
      "isTag": "1",
      "isAffix": "1"
    },
    {
      "menuId": 11,
      "menuName": "用户管理",
      "parentId": 1,
      "menuType": "2",
      "path": "/system/user",
      "name": "userPage",
      "component": "system/user/index",
      "icon": "UserFilled",
      "isVisible": "1",
      "isKeepAlive": "0",
      "isTag": "1",
      "isAffix": "1"
    }
  ]
}

对接后端时，只需保证字段格式一致，即可快速完成权限菜单联调。

所有布局均支持 PC / Pad / 移动端 自适应，小屏自动切换 LayoutMobile。

• 亮色 / 暗色模式
• 12 种预设主题色 + 自定义取色
• 头部 / 侧边栏颜色反转
• 灰色模式、色弱模式
• 主题配置面板实时预览，持久化至 localStorage

主题架构遵循 「能 CSS 就不 JS」：布局变量由 theme-vars.scss 管理，仅主题色阶通过 themeColor.ts 写入 Element Plus 所需的 #RRGGBB 变量。

koi-ui/
├── build/                  # 构建插件（版本注入等）
├── public/                 # 静态资源
├── src/
│   ├── api/                # 接口定义
│   ├── assets/             # 图片、SVG 图标
│   ├── components/         # 全局业务组件（KoiDialog、KoiUpload…）
│   ├── config/             # 全局常量配置
│   ├── directives/         # 自定义指令（auth、debounce、waterMarker…）
│   ├── hooks/              # 组合式 Hooks（屏幕、SSE、字典）
│   ├── languages/          # 国际化语言包
│   ├── layouts/            # 布局组件与 ThemeConfig
│   ├── routers/            # 静态/动态路由
│   ├── stores/             # Pinia 状态（user、auth、global、tabs…）
│   ├── styles/             # 全局样式与 theme-vars
│   ├── utils/              # 工具函数（主题、路由、请求封装）
│   └── views/              # 页面视图
├── .env.development        # 开发环境变量
├── .env.test               # 测试环境变量
├── .env.production         # 生产环境变量
├── index.html              # 入口（含首屏主题预恢复脚本）
├── vite.config.ts
└── package.json

• Node.js >= 18
• 推荐使用 pnpm

# 全局安装 pnpm（可选）
npm install pnpm -g --registry=https://registry.npmmirror.com

# 克隆项目
git clone https://gitee.com/KoiKite/koi-ui.git
cd koi-ui

# 安装依赖
pnpm install

# 启动开发服务（默认 http://localhost:5730）
pnpm dev

以 .env.development 为例：

# 开发构建
pnpm build

# 测试环境
pnpm build:test

# 生产环境（移除 console、启用压缩与图片优化）
pnpm build:prod

构建产物输出至 dist/ 目录，可直接部署至 Nginx、OSS 或任意静态托管平台。

如果 KOI-UI 对你有帮助，欢迎在 Gitee 或 GitHub 点个 Star，这是对我最大的鼓励。

加微信时请备注：KOI-UI。

作者闲暇时间有限，如有需要，接收个人定制咨询。

Made with ❤️ by YuXin