166 lines
4.3 KiB
Markdown
166 lines
4.3 KiB
Markdown
# Admin Plus（Vue3 企业级开发模板）
|
||
|
||
面向公司项目的前端模板与基础库：内置 `Vue 3 + Vue CLI 5 + TypeScript + Pinia + Vue Router + Element Plus`，并集成 Mock、代码生成（Plop）、多套布局组件与常用工具链，支持在此基础上快速裁剪与复用。
|
||
|
||
> 本仓库同时提供面向 AI 的结构说明与模块索引：见 [AI-Coding/README.md](AI-Coding/README.md)。
|
||
|
||
---
|
||
|
||
## 亮点
|
||
|
||
- **开箱即用**：工程化配置齐全（TS/ESLint/Prettier/Stylelint/Unit Test）。
|
||
- **可扩展的 UI/布局体系**：`library/layouts/`、`library/components/` 内置多布局与业务型基础组件。
|
||
- **Mock 一体化**：开发环境通过 `devServer.setupMiddlewares` 自动挂载 `mock/` 路由。
|
||
- **现代依赖栈**：`Element Plus` + `@element-plus/icons-vue`，并内置图标组件 `vab-icons`。
|
||
- **可生成代码**：通过 `plop` 快速生成页面/CRUD/组件/mock&api。
|
||
|
||
---
|
||
|
||
## 环境要求
|
||
|
||
- Node.js：建议 **16/18/20 LTS**（与 Vue CLI 5 兼容）
|
||
- 包管理器：推荐 `pnpm`（项目脚本也提供 `npm` 用法）
|
||
|
||
---
|
||
|
||
## 快速开始
|
||
|
||
### 1）安装依赖
|
||
|
||
```powershell
|
||
cd d:\project\Web_Template_Vue3_Dev
|
||
pnpm i
|
||
```
|
||
|
||
如你使用 npm：
|
||
|
||
```powershell
|
||
cd d:\project\Web_Template_Vue3_Dev
|
||
npm i
|
||
```
|
||
|
||
### 2）启动开发环境
|
||
|
||
```powershell
|
||
pnpm run serve
|
||
```
|
||
|
||
### 3）构建
|
||
|
||
```powershell
|
||
pnpm run build
|
||
```
|
||
|
||
### 4）单元测试 / 代码质量
|
||
|
||
```powershell
|
||
pnpm run test:unit
|
||
pnpm run lint
|
||
pnpm run lint:eslint
|
||
pnpm run lint:prettier
|
||
pnpm run lint:stylelint
|
||
```
|
||
|
||
---
|
||
|
||
## 常用脚本（scripts）
|
||
|
||
来自 `package.json`：
|
||
|
||
- **`serve`**：启动开发服务器（本地 Mock 会自动挂载）。
|
||
- **`build`**：生产构建。
|
||
- **`build:compress` / `compress`**：构建后压缩产物（`scripts/compress.js`）。
|
||
- **`build:website`**：站点构建（使用 `VAB_VARIABLE=website` + 压缩）。
|
||
- **`test:unit`**：单元测试。
|
||
- **`lint`**：Vue CLI ESLint。
|
||
- **`lint:eslint` / `lint:prettier` / `lint:stylelint`**：更精细的格式化与风格修复。
|
||
- **`template`**：启动 `plop` 代码生成。
|
||
|
||
---
|
||
|
||
## 项目结构（速览）
|
||
|
||
> 更完整、可供 AI 检索复用的索引见 [AI-Coding/README.md](AI-Coding/README.md)。
|
||
|
||
```text
|
||
src/ 应用主代码（入口、路由、状态、国际化、业务页面）
|
||
library/ 模板基础库（全局样式、插件集合、构建扩展等）
|
||
library/components/ 可复用基础组件（Vab* 体系）
|
||
library/layouts/ 多套布局（含主 Layout 入口）
|
||
mock/ 本地 Mock 服务（devServer 中间件挂载）
|
||
types/ 全局类型声明与业务类型
|
||
tests/unit/ 单元测试
|
||
scripts/ 构建后处理脚本（如压缩）
|
||
public/ 静态资源与 HTML 模板
|
||
```
|
||
|
||
---
|
||
|
||
## 关键约定与入口
|
||
|
||
### 应用入口
|
||
|
||
- `src/main.ts`
|
||
- 创建应用并挂载：`createApp(App)`
|
||
- 初始化顺序：`setupVab` → `setupI18n` → `setupStore` → `setupRouter`
|
||
- 生产环境可自动启用 Mock：当 `baseURL` 不是外链地址时（见 `src/main.ts` 的判断）
|
||
|
||
### 路由
|
||
|
||
- `src/router/index.ts`
|
||
- `constantRoutes`：如登录/注册/404 等基础路由
|
||
- `asyncRoutes`：业务路由（包含 `Layout` 作为壳）
|
||
|
||
### 状态管理
|
||
|
||
- `src/store/index.ts`：Pinia 初始化与注入。
|
||
|
||
### 国际化
|
||
|
||
- `src/i18n/index.ts`
|
||
- `createI18n({ legacy:false })`
|
||
- 当前语言读取自 `useSettingsStore(pinia)`
|
||
|
||
### Mock
|
||
|
||
- `mock/index.js`
|
||
- 挂载到开发服务器中间件（在 `vue.config.js` 的 `devServer.setupMiddlewares`）
|
||
- 基于 `mockjs` 返回数据，并支持文件变更热更新
|
||
|
||
---
|
||
|
||
## 别名（Alias）
|
||
|
||
来自 `vue.config.js` / `tsconfig.json`：
|
||
|
||
- `@` → `src`
|
||
- `~` → 项目根目录
|
||
- `/#` → `types`
|
||
- `@vab` → `library`
|
||
- `@gp` → `library/plugins/vab`
|
||
|
||
---
|
||
|
||
## 代码生成（Plop）
|
||
|
||
项目提供 `plop` 生成器（见 `plopfile.js`）：
|
||
|
||
- `view`：页面
|
||
- `curd`：CRUD
|
||
- `component`：组件
|
||
- `mock&api`：Mock 与 API 片段
|
||
|
||
运行：
|
||
|
||
```powershell
|
||
pnpm run template
|
||
```
|
||
|
||
---
|
||
|
||
## 贡献与团队协作建议
|
||
|
||
- 建议以“业务模块”为单位在 `src/views/` 组织页面。
|
||
- API 按域拆分在 `src/api/`，与 `mock/controller/` 保持同名与路径一致，方便对照。
|
||
- 公共能力优先沉淀在 `library/`（全局插件/样式/构建扩展）与 `library/components/`（可视组件）。
|