# vue-admin-side

**Repository Path**: GyYuMine/vue-admin-side

## Basic Information

- **Project Name**: vue-admin-side
- **Description**: vite7_vue3_elementuiplus_ts 多模块架构
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-24
- **Last Updated**: 2026-05-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Vue Admin Side - 企业级后台管理系统

基于 Vue 3 + Vite 7 + Element Plus + TypeScript 构建的现代化后台管理系统，采用模块化架构设计，支持多模块独立打包和联合打包。

## 📋 目录

- [技术栈](#技术栈)
- [项目结构](#项目结构)
- [快速开始](#快速开始)
- [模块化架构](#模块化架构)
- [构建命令](#构建命令)
- [分模块打包能力](#分模块打包能力)
- [环境变量](#环境变量)
- [代码规范](#代码规范)
- [组件多声明方式支持](#组件多声明方式支持-new)
- [部署](#部署)

---

## 🛠️ 技术栈

### 核心框架

- **Vue 3.5.24** - 渐进式 JavaScript 框架
- **Vite 7.2.2** - 下一代前端构建工具
- **TypeScript 5.9.3** - 类型安全的 JavaScript 超集
- **Element Plus 2.10.4** - Vue 3 组件库

### 状态管理

- **Pinia 3.0.3** - Vue 官方状态管理库
- **Pinia Plugin Persistedstate** - Pinia 持久化插件

### 路由管理

- **Vue Router 4.6.3** - Vue 官方路由

### 构建工具

- **@vitejs/plugin-vue** - Vue 单文件组件支持
- **vue-tsc** - TypeScript 类型检查
- **unplugin-auto-import** - 自动导入 API
- **unplugin-vue-components** - 组件自动注册
- **vite-plugin-svg-icons** - SVG 图标管理
- **code-inspector-plugin** - 代码定位调试工具

### UI/样式

- **Sass 1.89.2** - CSS 预处理器
- **全局 SCSS 变量系统** - 统一的设计令牌管理

### 地图可视化

- **Leaflet 1.9.4** - 开源地图库
- **Leaflet Canvas Map 1.0.3** - Canvas 地图渲染

### HTTP 请求

- **Axios 1.10.0** - HTTP 客户端

---

## 📁 项目结构

```
vue-admin-side/
├── public/                     # 公共静态资源（直接复制）
│   └── vite.svg
├── config/                     # 配置文件
│   └── readdir.ts             # 获取模块名称的工具函数
├── src/                        # 主源码目录
│   ├── assets/                # 全局静态资源
│   │   ├── api/               # 全局 API 接口定义
│   │   ├── dictionary/        # 全局数据字典
│   │   ├── font/              # 字体文件
│   │   ├── icons/             # 全局 SVG 图标
│   │   ├── images/            # 图片资源
│   │   ├── mapData/           # 地图数据
│   │   └── styles/            # 全局样式
│   │       ├── variables.scss # 全局 SCSS 变量（设计令牌）
│   │       ├── globalStyle.scss # 全局基础样式
│   │       └── reset.scss     # 样式重置
│   ├── components/            # 全局公共组件
│   │   ├── sidebar/           # 侧边栏组件
│   │   ├── SvgIcon.vue        # SVG 图标组件
│   │   └── HelloWorld.vue
│   ├── engineeringModule/     # 工程模块目录（核心业务模块）
│   │   ├── example/           # 示例模块（可删除）
│   │   ├── test/              # 测试模块（可删除）
│   │   └── readMe.md          # 工程模块说明文档
│   ├── router/                # 全局路由配置
│   │   ├── index.ts           # 路由实例
│   │   └── routes.ts          # 路由表
│   ├── store/                 # 全局状态管理
│   │   ├── index.ts           # Store 入口
│   │   └── default.ts         # 默认状态
│   ├── types/                 # TypeScript 类型定义
│   │   └── ResponseData.ts    # 响应数据类型
│   ├── utils/                 # 工具函数
│   │   ├── http.ts            # HTTP 请求封装
│   │   ├── mainImport.ts      # 主导入工具
│   │   ├── regex.ts           # 正则表达式
│   │   ├── registerComponen.ts # 组件注册
│   │   ├── registerdirective.ts # 指令注册
│   │   └── tools.ts           # 通用工具
│   ├── views/                 # 全局页面视图
│   │   ├── layout/            # 布局组件
│   │   │   ├── components/    # 布局子组件
│   │   │   │   └── HomeTabs.vue # Tab 标签页
│   │   │   └── index.vue      # 主布局
│   │   └── RouterView.vue     # 路由视图
│   ├── App.vue                # 根组件
│   ├── main.ts                # 主入口文件
│   └── vite-env.d.ts          # Vite 类型声明
├── dist/                       # 构建输出目录
│   ├── all/                   # 全部模块打包结果
│   ├── example/               # example 模块打包结果
│   └── test/                  # test 模块打包结果
├── .vscode/                    # VSCode 配置
├── .qoder/                     # Qoder AI 配置
├── .history/                   # 历史版本备份（可忽略）
├── index.html                  # HTML 模板
├── package.json                # 项目依赖配置
├── pnpm-lock.yaml              # 依赖锁定文件
├── tsconfig.json               # TypeScript 配置
└── vite.config.ts              # Vite 构建配置
```

---

## 🚀 快速开始

### 环境要求

- Node.js >= 18.x
- pnpm >= 8.x（推荐使用 pnpm）

### 安装依赖

```bash
pnpm install
```

### 启动开发服务器

```bash
# 启动主模块（默认）
pnpm dev

# 启动指定工程模块
pnpm dev:example  # 启动 example 模块
pnpm dev:test     # 启动 test 模块
```

### 访问地址

开发服务器启动后自动打开浏览器，访问：`http://localhost:8080`

---

## 🏗️ 模块化架构

### 什么是工程模块？

工程模块是本项目核心的架构设计理念，每个模块都是一个**独立完整的功能单元**，包含：

- 独立的页面视图（views）
- 独立的路由配置（router）
- 独立的状态管理（store）
- 独立的组件库（components）
- 独立的静态资源（assets）
- 独立的样式系统（styles）

### 模块目录结构

每个工程模块都遵循标准化的目录结构：

```
moduleName/
├── assets/                 # 模块静态资源
│   ├── api/                # API 接口定义
│   ├── dictionary/         # 数据字典
│   ├── font/               # 字体文件
│   ├── icons/              # SVG 图标
│   ├── images/             # 图片资源
│   └── styles/             # 样式文件（index.scss）
├── components/             # 模块组件
├── router/                 # 路由配置
│   ├── index.ts            # 路由实例
│   └── routes.ts           # 路由表
├── store/                  # 状态管理
│   └── index.ts            # Store 定义
├── utils/                  # 工具函数
├── views/                  # 页面视图
│   └── layout/             # 布局组件
│       ├── components/     # 布局子组件
│       └── index.vue       # 布局主页面
├── main.ts                 # 模块入口
├── auto-imports.d.ts       # 自动导入类型
└── components.d.ts         # 组件类型
```

### 当前模块

| 模块名            | 说明                         | 状态   |
| ----------------- | ---------------------------- | ------ |
| **example** | 示例模块，展示完整的模块结构 | 可删除 |
| **test**    | 测试模块，用于新功能开发     | 可删除 |

### 创建新模块

```bash
# 方式 1：复制示例模块
cp -r src/engineeringModule/example src/engineeringModule/new-module

# 方式 2：复制测试模块
cp -r src/engineeringModule/test src/engineeringModule/new-module
```

**命名规范：**

- 使用小写字母
- 多个单词用短横线 `-` 分隔
- 例如：`user-management`、`order-system`、`data-analysis`

**重要提示：**

- 模块名称会作为路由前缀和资源路径的一部分
- `store` 的 ID 必须与模块名称一致
- 在正式项目中，`example` 和 `test` 模块应删除

---

## 📦 构建命令

### 开发环境

```bash
# 启动主模块开发服务器
pnpm dev

# 启动指定工程模块开发服务器
pnpm dev:example
pnpm dev:test
```

### 生产环境

```bash
# 构建主模块（全部模块）
pnpm build
# 输出目录：dist/all/

# 构建指定工程模块
pnpm build:example  # 输出目录：dist/example/
pnpm build:test     # 输出目录：dist/test/
```

### 预览构建结果

```bash
pnpm preview
```

---

## 🔧 分模块打包能力

### 打包机制

项目支持**灵活的模块化打包策略**，可以根据不同需求选择打包范围：

#### 1. **全部模块打包**（默认）

```bash
pnpm build
```

- 打包所有工程模块和主应用
- 输出到 `dist/all/` 目录
- 适用于完整部署或单体应用

#### 2. **单个模块独立打包**

```bash
pnpm build:example
pnpm build:test
```

- 只打包指定的单个工程模块
- 输出到 `dist/{module-name}/` 目录
- 适用于微前端架构或模块独立部署

#### 3. **自定义模块打包**

通过修改 `package.json` 添加新的构建命令：

```json
{
  "scripts": {
    "build:custom": "vue-tsc --noEmit && cross-env VITE_MODE=your-module vite build"
  }
}
```

### 打包配置详解

#### 环境变量控制

```typescript
// vite.config.ts
process.env.VITE_MODE // 控制打包目标模块
```

- **未设置 VITE_MODE**：打包主应用（全部模块）
- **设置 VITE_MODE=example**：只打包 example 模块

#### 入口文件切换

```typescript
// 根据 VITE_MODE 动态切换入口
entryFileNames: process.env.VITE_MODE
  ? `./src/engineeringModule/${process.env.VITE_MODE}/main.ts`
  : './src/main.ts'
```

#### 资源路径管理

```typescript
// SVG 图标目录动态配置
iconDirs: (() => {
  let dirs = [resolve(root, 'src/assets/icons')];
  if (process.env.VITE_MODE) {
    // 只添加指定模块的图标
    dirs.push(resolve(root, 'src/engineeringModule/' + process.env.VITE_MODE + '/assets/icons'));
  } else {
    // 添加所有模块的图标
    engineeringModules.forEach(moduleName => {
      dirs.push(resolve(root, 'src/engineeringModule/'+ moduleName + '/assets/icons'));
    });
  }
  return dirs;
})()
```

#### 样式注入

```typescript
// SCSS 全局变量动态注入
additionalData: (() => {
  let style = `@import "@/assets/styles/globalStyle.scss";`;
  if (process.env.VITE_MODE) {
    style += `@import "@/engineeringModule/${process.env.VITE_MODE}/assets/styles/index.scss";`;
  }
  return style;
})()
```

### 打包优化策略

#### 1. **代码分割**

```typescript
manualChunks: {
  // 第三方库单独打包
  'vue-vendor': ['vue', 'vue-router', 'pinia'],
  'element-plus-vendor': ['element-plus'],
}
```

#### 2. **资源分类**

- JS 文件：`js/[name]-[hash].js`
- 图片资源：`images/[name]-[hash].[ext]`
- 其他资源：`[ext]/[name]-[hash].[ext]`

#### 3. **性能优化**

- 使用 esbuild 压缩（比 terser 快 20-40 倍）
- 生产环境移除 console 和 debugger
- 不生成 source map（提高构建速度）
- 启用依赖预构建和构建缓存

### 打包输出示例

```
dist/
├── all/                    # 全部模块打包
│   ├── assets/
│   │   ├── js/
│   │   │   ├── index-[hash].js
│   │   │   ├── vue-vendor-[hash].js
│   │   │   └── element-plus-vendor-[hash].js
│   │   ├── images/
│   │   └── svg/
│   └── index.html
├── example/                # example 模块打包
│   └── ...
└── test/                   # test 模块打包
    └── ...
```

---

## 🌍 环境变量

### 环境变量配置

项目使用 `.env` 文件管理环境变量（需要自行创建）：

```bash
# .env.development
NODE_ENV=development
VITE_API_BASE_URL=/api

# .env.production
NODE_ENV=production
VITE_API_BASE_URL=https://api.your-domain.com
```

### 自定义环境变量

在 `package.json` 的 `paramDescription` 中定义了关键参数：

```json
{
  "paramDescription": {
    "VITE_MODE": "启动模块的文件夹名称",
    "VITE_API_BASE_URL": "请求的接口转发"
  }
}
```

### API 代理配置

开发环境下的 API 代理配置（`vite.config.ts`）：

```typescript
proxy: {
  ['/api']: {
    target: 'http://xxx.xxx.xxx.xxx:8000',
    changeOrigin: true,
    rewrite: path => path.replace(new RegExp('^api'), ''),
  },
}
```

---

## 📝 代码规范

### TypeScript 规范

- 所有 `.vue` 和 `.ts` 文件必须使用 TypeScript
- 禁止使用 `any` 类型，使用 `unknown` 或具体类型
- 接口定义放在 `types/` 目录

### SCSS 规范

项目建立了完整的全局 SCSS 变量系统：

```scss
// 颜色变量
$primaryColor: #1e3a5f;      // 主题色
$sidebar-bg-color: #1e3a5f;  // 侧边栏背景
$whiteColor: #ffffff;         // 白色

// 字号变量（四个值原则）
$fontSize-xs: 12px;          // 超小字号
$fontSize-sm: 14px;          // 小字号
$fontSize-md: 16px;          // 中标号
$fontSize-lg: 18px;          // 大字号

// 间距变量（四个值原则）
$padding-xs: 4px;            // 超小内边距
$padding-sm: 8px;            // 小内边距
$padding-md: 12px;           // 中内边距
$padding-lg: 16px;           // 大内边距

$margin-xs: 4px;             // 超小外边距
$margin-sm: 8px;             // 小外边距
$margin-md: 12px;            // 中外边距
$margin-lg: 16px;            // 大外边距
```

### 命名规范

#### 文件命名

- 组件文件：PascalCase（如 `SidebarItem.vue`）
- 工具文件：camelCase（如 `http.ts`）
- 模块目录：kebab-case（如 `user-management`）

#### 组件命名

- 使用多单词名称（避免与 HTML 元素冲突）
- 文件名与组件名保持一致

#### Store 命名

```typescript
// 模块名称为 user-management
const useUserManagementStore = defineStore('user-management', {
  // store 定义
});
```

### 自动导入

项目配置了自动导入，无需手动导入以下内容：

- Vue API（ref, reactive, computed 等）
- Vue Router API（useRouter, useRoute 等）
- Pinia API（defineStore 等）
- Element Plus 组件

---

## 🎭 组件多声明方式支持 ✨ NEW

本项目**完美支持三种 Vue 3 组件声明方式混用**，你可以根据团队习惯和项目需求灵活选择。

### 三种声明方式对比

| 特性                 | Options API | Composition API | Setup 语法糖 |
| -------------------- | ----------- | --------------- | ------------ |
| **代码简洁度** | ⭐⭐⭐      | ⭐⭐            | ⭐⭐⭐⭐⭐   |
| **类型推导**   | ⭐⭐⭐      | ⭐⭐⭐⭐        | ⭐⭐⭐⭐⭐   |
| **逻辑复用**   | ⭐⭐        | ⭐⭐⭐⭐⭐      | ⭐⭐⭐⭐⭐   |
| **学习曲线**   | 低          | 中              | 中           |
| **Vue 2 兼容** | ✅          | ❌              | ❌           |
| **自动暴露**   | ✅          | ❌              | ✅           |
| **推荐场景**   | Vue 2 迁移  | 复杂逻辑封装    | 新项目首选   |

### 1️⃣ Options API（选项式 API）

**特点：**

- Vue 2 经典写法，使用 `data`、`methods`、`computed` 等选项
- 结构清晰，易于理解
- 适合从 Vue 2 迁移的项目

**示例代码：**

```vue
<script lang="ts">
import { defineComponent } from 'vue';

export default defineComponent({
  name: 'MyComponent',

  data() {
    return {
      count: 0
    };
  },

  methods: {
    increment() {
      this.count++;
    }
  }
});
</script>
```

### 2️⃣ Composition API（普通函数声明）

**特点：**

- 使用 `setup()` 函数
- 需要显式 `return` 模板中使用的内容
- 更好的类型推导，逻辑复用更方便

**示例代码：**

```vue
<script lang="ts">
import { defineComponent, ref } from 'vue';

export default defineComponent({
  setup() {
    const count = ref(0);

    const increment = () => {
      count.value++;
    };

    // ⚠️ 必须显式返回
    return {
      count,
      increment
    };
  }
});
</script>
```

### 3️⃣ Setup 语法糖（Vue 3 推荐）

**特点：**

- Vue 3 推荐的写法
- 代码最简洁，自动暴露顶层内容
- 无需手动 `return`

**示例代码：**

```vue
<script setup lang="ts">
import { ref } from 'vue';

const count = ref(0);

const increment = () => {
  count.value++;
};

// ✅ 自动暴露，无需 return
</script>
```

### 🎯 混合使用示例

父组件使用 Setup 语法糖，子组件可以使用任意一种方式：

```vue
<!-- 父组件：Setup 语法糖 -->
<template>
  <div>
    <!-- Options API 子组件 -->
    <options-api-component
      :initial-count="10"
      @count-change="handleCountChange"
    />

    <!-- Composition API 子组件 -->
    <composition-api-component
      :initial-data="userData"
      @submit="handleSubmit"
    />

    <!-- Setup 语法糖子组件 -->
    <child-component @event="handler" />
  </div>
</template>

<script setup lang="ts">
import { ref } from 'vue';
import OptionsApiComponent from './components/OptionsApiComponent.vue';
import CompositionApiComponent from './components/CompositionApiComponent.vue';
import ChildComponent from './components/ChildComponent.vue';

const userData = ref({ username: '张三' });

const handleCountChange = (newCount: number) => {
  console.log('计数变化:', newCount);
};

const handleSubmit = (data: any) => {
  console.log('收到数据:', data);
};
</script>
```

### 📁 完整示例位置

项目中已包含完整的三种声明方式示例：

```
src/engineeringModule/test/views/layout/
├── components/
│   ├── child.vue                        # Setup 语法糖示例
│   ├── OptionsApiComponent.vue          # Options API 完整示例
│   └── CompositionApiComponent.vue      # Composition API 完整示例
├── DemoIndex.vue                        # 三种方式混合演示页面
└── components/README.md                 # 详细使用文档
```

### 🚀 运行示例

启动 test 模块查看演示：

```bash
pnpm dev:test
```

然后在左侧导航点击 **"组件声明演示"** 菜单。

### ⚙️ 核心配置

项目已配置好支持多种声明方式，关键配置如下：

**vite.config.ts**

```typescript
AutoImport({
    imports: ['vue', 'vue-router', 'pinia'],
    resolvers: [ElementPlusResolver()],
    dts: './auto-imports.d.ts',
    include: [/\.[tj]sx?$/, /\.vue$/, /\.vue\?vue/, /\.md$/], // ✅ 支持所有文件
}),

Components({
    resolvers: [ElementPlusResolver()],
    dts: './components.d.ts',
    types: [], // ✅ 支持非 setup 语法
}),
```

**tsconfig.json**

```json
{
  "compilerOptions": {
    "allowSyntheticDefaultImports": true, // ✅ 允许默认导入
    "strict": true
  }
}
```

---

## 🚀 部署

### 构建产物

```bash
# 构建全部模块
pnpm build
# 输出：dist/all/

# 构建单个模块
pnpm build:example
# 输出：dist/example/
```

### 部署步骤

1. **构建生产版本**

   ```bash
   pnpm build
   ```
2. **上传构建产物**

   - 将 `dist/` 目录上传到服务器
   - 或使用 CI/CD 自动化部署
3. **配置 Web 服务器**

   **Nginx 配置示例：**

   ```nginx
   server {
     listen 80;
     server_name your-domain.com;
     root /path/to/dist/all;
     index index.html;

     location / {
       try_files $uri $uri/ /index.html;
     }

     location /api {
       proxy_pass http://backend-server:8000;
       proxy_set_header Host $host;
       proxy_set_header X-Real-IP $remote_addr;
     }
   }
   ```

### Docker 部署

```dockerfile
FROM nginx:alpine

COPY dist/all /usr/share/nginx/html
COPY nginx.conf /etc/nginx/conf.d/default.conf

EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]
```

### 多模块部署策略

#### 方案一：单体部署

- 构建全部模块（`dist/all/`）
- 统一部署到一个服务器
- 适用于小型项目

#### 方案二：微前端部署

- 每个模块独立构建（`dist/example/`, `dist/test/`）
- 部署到不同的子域名或路径
- 使用 qiankun、single-spa 等微前端框架集成

#### 方案三：按需部署

- 根据业务需求构建特定模块
- 动态加载远程模块
- 适用于大型分布式系统

---

## 🎨 UI 设计规范

### 主题色

```scss
$primaryColor: #1e3a5f;      // 导航栏深蓝主题色
$primaryLight: #409eff;      // Element Plus 主色
$sidebar-active-color: #00b2ff; // 侧边栏激活色
```

### 圆角规范

```scss
$border-radius-sm: 4px;      // 小圆角
$border-radius-md: 6px;      // 中圆角（Tab、按钮）
$border-radius-lg: 8px;      // 大圆角（卡片）
$border-radius-xl: 12px;     // 超大圆角
```

### 阴影规范

```scss
$button-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);           // 按钮阴影
$collapse-hover-shadow: 0 4px 12px rgba(0, 0, 0, 0.15); // 悬停阴影
```

---

## 🔍 开发工具

### Code Inspector

项目集成了 `code-inspector-plugin`，支持点击页面元素直接跳转到 VSCode 对应代码位置。

**使用说明：**

- 开发模式下自动启用
- 生产构建时自动禁用
- 点击页面任意元素即可定位到源码

### 自动导入

使用 `unplugin-auto-import` 和 `unplugin-vue-components` 实现：

- API 自动导入（ref, reactive 等）
- 组件自动注册（ElButton, ElTable 等）
- 类型提示自动生成

### SVG 图标

使用 `vite-plugin-svg-icons` 管理 SVG 图标：

```vue
<template>
  <svg-icon name="expand" />
</template>
```

---

## 📚 常见问题

### Q: 如何添加新的工程模块？

A:

1. 复制 `example` 或 `test` 目录
2. 重命名为新模块名称（使用 kebab-case）
3. 修改模块内的 `main.ts`、`router`、`store` 等文件
4. 在 `package.json` 中添加对应的启动命令

### Q: 如何实现模块间通信？

A:

- 使用 Pinia 全局状态管理
- 使用事件总线（mitt）
- 使用 localStorage/sessionStorage

### Q: 如何优化打包速度？

A:

- 使用 `pnpm` 替代 `npm`
- 启用 Vite 依赖预构建
- 合理配置 `manualChunks` 进行代码分割
- 生产环境不生成 source map

### Q: 如何处理跨域问题？

A:

- 开发环境：使用 Vite 的 `proxy` 配置
- 生产环境：使用 Nginx 反向代理

---

## 📄 许可证

MIT License

---

## 👥 贡献指南

欢迎提交 Issue 和 Pull Request！

---

## 📞 联系方式

如有问题，请通过以下方式联系：

- Email: tj_ygy@163.com
- GitHub Issues: [提交 Issue](https://github.com/your-repo/issues)

---

**最后更新：** 2026 年 3 月 24 日