vue-admin-essentials

KO | EN

gitlite — search

#javascript #hacktoberfest #ai #go #machine-learning #deep-learning #docker #nodejs #windows #awesome-list #security #pytorch #mcp #open-source

vue-admin-essentials

(★ 9)

精简优化的vue-naive-admin，专注快速启动，开箱即用。

vue-admin-essentials Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<h1 align="center">Vue Admin Essentials</h1>

<p align="center">一个开箱即用的 Vue 3 后台管理模板，5 分钟从克隆到登录页。</p>

## 特性

- **精简干净** — 移除了原版所有示例页面和冗余组件，只保留框架核心代码
- **接口加密** — 预置 AES 接口加密拦截器，随机密钥对通过 RSA 传递，开箱即用
- **CRUD 模板** — 内置列表 + 翻页 + 弹窗的页面模板，配合 `useCrud` 组合式函数，几行代码搞定增删改查
- **极速上手** — 从 `git clone` 到看到登录页面，不超过 5 分钟
- **后端配套** — 高度契合 [php-webman-essentials](https://github.com/zxc7563598/php-webman-essentials)，前后端同时安装即可开始写业务
- **灵活布局** — 支持通用、全面、简约、空白四种布局，可自由切换

## 技术栈

| 类别 | 技术 |
|------|------|
| 框架 | Vue 3 |
| 构建 | Vite 6 |
| UI 组件 | Naive UI |
| 状态管理 | Pinia |
| 路由 | Vue Router 4 |
| CSS 引擎 | UnoCSS |
| HTTP 请求 | Axios + hejunjie-encrypted-request |
| 图表 | ECharts + vue-echarts |
| 国际化 | Vue I18n |
| 代码规范 | ESLint + simple-git-hooks |

## 前置要求

- **Node.js** >= 18
- **pnpm**（推荐。项目已生成 pnpm-lock.yaml，也可使用 npm）

## 快速开始

### 1. 克隆项目

```bash
git clone https://github.com/zxc7563598/vue-admin-essentials.git
cd vue-admin-essentials
```

### 2. 配置环境变量

```bash
cp .env.example .env
cp .env.example .env.development
cp .env.example .env.production
```

按需修改 `.env.development` 中的 `VITE_AXIOS_BASE_URL`，指向你的后端接口地址：

```env
# Axios 基础路径（开发环境）
VITE_AXIOS_BASE_URL = 'http://127.0.0.1:8787/admin-api'
```

> [!IMPORTANT]
> 项目使用了接口加密机制：采用 AES 加密请求体 + RSA 加密 AES 密钥的方式。如果你对接的是 [php-webman-essentials](https://github.com/zxc7563598/php-webman-essentials) 后端，需要将后端的 RSA 公钥文件放到 `public/keys/public_key.pem`。如果对接自己的后端，建议从[原项目](https://github.com/zclzone/vue-naive-admin)开始，自行定制加密方案会更方便。

### 3. 安装依赖

```bash
pnpm install
```

### 4. 启动开发服务器

```bash
pnpm dev
```

浏览器访问 `http://localhost:3200`，默认账号 `admin` / `123456`。

> [!NOTE]
> 本地开发需要配合后端服务才能正常登录和请求数据。如果还没有后端，参考[快速搭建后端 →](https://github.com/zxc7563598/php-webman-essentials)。

## 使用

### 创建一个 CRUD 页面

以用户管理为例，只需要三步：

**1. 定义 API（`api.js`）**

```js
import { request } from '@/utils/http'

export default {
  read: params => request.get('/user', { params }),
  create: data => request.post('/user', data),
  update: data => request.put(`/user/${data.id}`, data),
  delete: ({ id }) => request.delete(`/user/${id}`),
}
```

**2. 写页面模板（`index.vue`）—— 使用 `<MeCrud>` 组件**

```vue
<template>
  <CommonPage>
    <MeCrud
      ref="$table"
      v-model:query-items="queryItems"
      :columns="columns"
      :get-data="api.read"
    >
      <MeQueryItem label="用户名">
        <n-input v-model:value="queryItems.username" clearable />
      </MeQueryItem>
    </MeCrud>
  </CommonPage>
</template>
```

**3. 组合 `useCrud` 管理增删改查状态**

```js
const { modalRef, modalForm, handleAdd, handleDelete } = useCrud({
  name: '用户',
  initForm: {},
  doCreate: api.create,
  doDelete: api.delete,
  doUpdate: api.update,
  refresh: () => $table.value?.handleSearch(),
})
```

`useCrud` 封装了新增、编辑、查看、删除、表单校验、弹窗开关等逻辑，你只需定义 API 方法和列配置即可。

> 完整示例参考 [src/views/pms/user/index.vue](src/views/pms/user/index.vue)。

### 打包部署

```bash
pnpm build
```

构建产物在 `dist/` 目录，部署到任意静态服务器即可。如果部署在子路径下，修改 `.env.production` 中的 `VITE_PUBLIC_PATH`。

## 目录结构

```
├── build/             # 构建脚本（自定义 Vite 插件）
├── public/            # 静态资源（RSA 公钥等）
│   └── keys/          # 加密密钥文件
├── src/
│   ├── api/           # 框架层 API（登录、用户信息等）
│   ├── assets/        # 图标、图片资源
│   ├── components/    # 全局组件
│   │   ├── common/    # 通用组件（布局、页脚、Logo 等）
│   │   └── me/        # 业务模板组件（crud、modal）
│   ├── composables/   # 组合式函数（useCrud、useForm、useModal）
│   ├── directives/    # 自定义指令（权限指令等）
│   ├── layouts/       # 布局模板（通用/全面/简约/空白）
│   ├── router/        # 路由配置和守卫
│   ├── store/         # Pinia 状态管理
│   ├── utils/         # 工具函数（HTTP 请求、存储、通用工具）
│   └── views/         # 页面
│       ├── login/     # 登录页
│       ├── home/      # 首页
│       ├── pms/       # 系统管理（用户/角色/菜单）
│       ├── profile/   # 个人中心
│       └── error-page/# 错误页面
├── .env.example       # 环境变量模板
├── vite.config.js     # Vite 配置
└── uno.config.js      # UnoCSS 配置
```

## 常见问题

<details>
<summary><b>登录报错 "Network Error"？</b></summary>

检查 `.env.development` 中的 `VITE_AXIOS_BASE_URL` 和后端地址是否一致，确认后端服务已启动。
</details>

<details>
<summary><b>接口请求被加密拦截，但我对接的是自己的后端？</b></summary>

加密逻辑在 `src/utils/http/interceptors.js` 中，如果你不需要加密，可以在这里移除加密拦截器。更推荐从[原项目](https://github.com/zclzone/vue-naive-admin)开始，自行按需添加加密方案。
</details>

<details>
<summary><b>如何修改主题色？</b></summary>

编辑 [src/settings.js](src/settings.js) 中的 `defaultPrimaryColor` 和 `naiveThemeOverrides`。
</details>

<details>
<summary><b>如何切换路由模式？</b></summary>

修改 `.env` 中的 `VITE_USE_HASH` —— `true` 为 Hash 模式，`false` 为 History 模式。
</details>

## 相关项目

- [vue-naive-admin](https://github.com/zclzone/vue-naive-admin) — 原项目，功能更全面，包含丰富的示例页面
- [php-webman-essentials](https://github.com/zxc7563598/php-webman-essentials) — 配套 PHP 后端，基于 Webman 框架

vue-admin-essentials

vue-admin-essentials Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

vue-admin-essentials

vue-admin-essentials Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README