# vue3-admin-template

**Repository Path**: luo-binger/vue3-admin-template

## Basic Information

- **Project Name**: vue3-admin-template
- **Description**: vue3+vite+pinia+ts+element-plus+router+mock工程化模板
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-11-28
- **Last Updated**: 2025-11-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Vue3 + Vite + Element Plus 企业级中后台开发模板

<p align="left">
  <img src="https://img.shields.io/badge/Vue-3.4+-42b883?style=flat-square&logo=vue.js" />
  <img src="https://img.shields.io/badge/Vite-5.0+-646CFF?style=flat-square&logo=vite" />
  <img src="https://img.shields.io/badge/TypeScript-5.0+-3178C6?style=flat-square&logo=typescript" />
  <img src="https://img.shields.io/badge/ElementPlus-Global-409EFF?style=flat-square&logo=element-plus" />
  <img src="https://img.shields.io/badge/Pinia-2.1+-FFE46B?style=flat-square&logo=pinia" />
</p>

## 📖 项目简介

这是一个开箱即用的 Vue3 企业级开发脚手架。
为了提供最稳定的开发体验，本项目采用 **Element Plus 全局全量导入** 策略，避免了按需引入可能导致的样式丢失或 TypeScript 类型报错问题。同时保留了 Vue 核心 API 的自动导入，兼顾了开发效率与稳定性。

### ✨ 核心特性

- **稳定技术栈**：Vue3 Setup + Vite5 + TypeScript + Pinia。
- **UI 框架 (全局导入)**：Element Plus 完整引入，无需手动注册组件，样式完全兼容。
- **开发体验**：
  - **AutoImport**：自动导入 Vue/Router/Pinia 核心 API (如 `ref`, `computed`)。
  - **Path Alias**：已配置 `@` 指向 `src` 目录。
  - **Sass**：开箱即用的 CSS 预处理器支持。
- **数据模拟**：集成 `vite-plugin-mock`，本地开发无需等待后端接口。

---

## 🚀 快速上手 (使用 Git Clone)

### 1. 拉取项目并初始化

请将 `[MyProjectName]` 替换为你实际的项目名称：

```bash
# 1. 克隆模板仓库
git clone https://gitee.com/luo-binger/vue3-admin-template.git [MyProjectName]

# 2. 进入项目目录
cd [MyProjectName]

# 3. [关键] 切断与模板仓库的关联，重新初始化 Git
rm -rf .git  # Windows CMD 用户请使用: rmdir /s /q .git
git init
git add .
git commit -m "feat: init project"
```

### 2. 安装依赖

推荐使用 npm 安装。
*(注：添加 `--legacy-peer-deps` 是为了防止部分 Mac 环境下的版本冲突警告)*

```bash
npm install --legacy-peer-deps
```

### 3. 启动项目

```bash
npm run dev
```
启动成功后访问：`http://localhost:5173`

---

## 📂 目录结构

```text
├── mock/                  # Mock 数据配置
├── public/                # 静态资源
├── src/
│   ├── assets/            # 项目资源 (图片/全局样式)
│   ├── components/        # 公共组件 (src/components 下的组件会自动注册)
│   ├── router/            # 路由配置
│   ├── store/             # Pinia 状态管理
│   ├── views/             # 页面文件
│   ├── App.vue            # 根组件
│   ├── main.ts            # 入口文件 (Element Plus 在此全局注册)
│   └── vite-env.d.ts      # Vite 类型声明
├── index.html             # HTML 模板
├── package.json           # 依赖配置
├── tsconfig.json          # TypeScript 配置
└── vite.config.ts         # Vite 配置 (Vue自动导入/Mock配置)
```

---

## 🧩 开发规范与指南

### 1. Element Plus 使用说明 (全局导入) ✅
本项目已在 `main.ts` 中引入了完整的 Element Plus。

*   **组件 (Component)**: **无需 Import**，直接在 template 中使用。
    ```html
    <!-- 任何页面直接写，不用引 -->
    <el-button type="primary">按钮</el-button>
    <el-input v-model="val" />
    ```

*   **反馈 API (Message/Notification)**: **必须手动 Import**。
    ```typescript
    import { ElMessage, ElMessageBox } from 'element-plus'

    const showMsg = () => {
      ElMessage.success('操作成功')
    }
    ```

### 2. Vue 核心 API 自动导入
无需在每个 `.vue` 文件中引入 Vue 的核心 API。
*   **支持列表**: `ref`, `reactive`, `computed`, `watch`, `onMounted`, `useRouter`, `useRoute` 等。
*   **使用方式**: 直接用即可。

### 3. Pinia Store 开发规范 ⚠️
在 `src/store` 下编写 `.ts` 文件时，为了避免 TypeScript 环境下自动导入偶发失效导致**响应式丢失**，**请务必手动引入 `ref`**。

```typescript
// src/store/user.ts
import { defineStore } from 'pinia'
import { ref } from 'vue' // 👈 强烈建议：在 .ts 文件中手动引入 ref

export const useUserStore = defineStore('user', () => {
  const token = ref('')
  return { token }
})
```

### 4. Mock 数据
在 `mock/` 目录下创建 `.ts` 文件即可自动拦截请求。
```typescript
export default [
  {
    url: '/api/test',
    method: 'get',
    response: () => ({ code: 200, data: 'Mock Data' })
  }
]
```

---

## ❓ 常见问题排查 (Troubleshooting)

**Q1: `npm install` 报错 `EACCES: permission denied`**
> **原因**: npm 缓存文件夹权限被 root 用户占用。
> **解决**: 运行 `sudo chown -R 501:20 "$HOME/.npm"` 修复权限。

**Q2: 为什么 `ElMessage` 报错 `is not defined`?**
> **原因**: 全局导入模式下，组件是自动注册的，但 API 方法不是。
> **解决**: 请在文件头部添加 `import { ElMessage } from 'element-plus'`。

**Q3: 修改了 Store 里的数据，但页面没更新？**
> **原因**: `ref` 在 `.ts` 文件中未被正确识别。
> **解决**: 检查 store 文件是否手动引入了 `import { ref } from 'vue'`。

---

## 📄 License

MIT