Admin端二次开发指南（小白版）

📖 本指南专门针对 Admin 端（管理后台）的二次开发，从零开始教你如何配置、开发和部署管理后台项目。

---

📋 目录

• 1. 技术栈介绍
• 2. 开始之前的准备
• 3. 首次安装配置
• 4. 环境文件配置详解
• 5. 开发模式（本地调试）
• 6. 生产环境打包
• 7. 开发技巧
• 8. 常见问题解决
• 9. 快速参考

---

1. 技术栈介绍

Admin 端（管理后台）使用的技术栈：

技术
版本
说明
| Vue.js | 3.2.37 | 渐进式 JavaScript 框架 |
| TypeScript | 4.7.4 | JavaScript 的超集，提供类型检查 |
| Vite | 3.0+ | 下一代前端构建工具 |
| Element Plus | 2.2.9 | 饿了么推出的 Vue 3 UI 组件库 |
| Pinia | 2.0.14 | Vue 3 官方推荐的状态管理工具 |
| Vue Router | 4.0.16 | Vue 官方路由管理器 |
| Axios | 0.27.2 | HTTP 请求库 |
| Tailwind CSS | 3.0.24 | 原子化 CSS 框架 |

核心功能组件：

• ✅ 富文本编辑器：@wangeditor/editor
• ✅ 数据可视化：echarts、vue-echarts
• ✅ Markdown 支持：markdown-it
• ✅ Excel 处理：xlsx
• ✅ PDF 预览：pdfjs-dist
• ✅ 拖拽功能：vuedraggable

---

2. 开始之前的准备

2.1 检查 Node.js 版本

Admin 端推荐使用 Node 16 或更高版本。

检查当前版本：
node -v

如果版本低于 16，请先升级：

• 下载地址：https://nodejs.org/
• 选择 LTS 版本
  2.2 选择包管理器

Admin 端支持以下包管理器（任选其一）：

• npm（Node.js 自带）
• yarn（推荐）
• pnpm

安装 yarn（推荐）：
npm install -g yarn

验证安装：
yarn -v

💡 提示：本指南使用 npm 作为示例，如果你用 yarn，只需将 npm 替换为 yarn 即可。

---

3. 首次安装配置

步骤 1：进入 Admin 端目录

在项目根目录下

cd admin

步骤 2：安装依赖包

使用 npm 安装（首次会比较慢，请耐心等待）

npm install

或使用 yarn（更快）

yarn install

⚠️ 重要提示：

• 安装前务必确认 Node 版本是 16+
• 如果安装失败，请查看本文档「常见问题」部分
• 安装时间取决于网速，通常需要 3-10 分钟

安装成功的标志：

• 终端没有报错
• 生成了 node_modules 文件夹
• 生成了 package-lock.json 或 yarn.lock 文件
  步骤 3：复制环境配置文件

Admin 端需要配置 2 个环境文件：

在 admin 目录下执行以下命令（Windows 系统）

1. 复制开发环境配置

copy .env.development.example .env.development

2. 复制生产环境配置

copy .env.production.example .env.production

Mac/Linux 系统：
cp .env.development.example .env.development
cp .env.production.example .env.production

💡 文件说明：

• .env.development → 开发环境配置（本地开发用）
• .env.production → 生产环境配置（打包上线用）

---

4. 环境文件配置详解

4.1 配置文件 1：.env.development（开发环境）

打开 admin/.env.development，配置后端 API 地址：

NODE_ENV = 'development'

后端 API 地址

VITE_APP_BASE_URL = 'http://你的后端地址'

配置示例：

示例 1：本地开发（后端在本地运行）
NODE_ENV = 'development'

本地后端地址

VITE_APP_BASE_URL = 'http://127.0.0.1:8000'

示例 2：连接测试服务器
NODE_ENV = 'development'

测试服务器地址

VITE_APP_BASE_URL = 'http://test.yourdomain.com'

示例 3：连接线上服务器
NODE_ENV = 'development'

线上服务器地址

VITE_APP_BASE_URL = 'https://api.yourdomain.com'

🎯 重点：这个地址必须是你的后端服务器地址，开发时所有 API 请求都会发送到这里。

---

4.2 配置文件 2：.env.production（生产环境）

打开 admin/.env.production，配置生产环境的 API 地址：

NODE_ENV = 'production'

生产环境的后端 API 地址

VITE_APP_BASE_URL = ''

配置说明：

留空（推荐）：
VITE_APP_BASE_URL = ''

• 打包后会自动使用当前域名作为 API 地址
• 例如：管理后台访问地址是 https://admin.yourdomain.com
• 则 API 请求地址也是 https://admin.yourdomain.com/api
  指定地址：
  VITE_APP_BASE_URL = 'https://api.yourdomain.com'
• 如果后端 API 和管理后台不在同一个域名下，需要指定完整地址

💡 新手建议：通常保持留空即可，系统会自动处理。

---

5. 开发模式（本地调试）

配置完成后，就可以启动开发服务器了。

5.1 启动开发服务器

在 admin 目录下执行

npm run dev

或使用 yarn

yarn dev

5.2 访问管理后台

启动成功后，终端会显示：

VITE v3.0.0 ready in 1234 ms

➜ Local: http://localhost:5173/admin/
➜ Network: http://192.168.1.100:5173/admin/

打开浏览器访问：http://localhost:5173/admin/

⚠️ 注意：访问路径后面有 /admin/，不要忘记。

5.3 登录管理后台

默认账号：

• 账号：admin

• 密码：123456（具体密码以安装时设置为准）
  5.4 开发模式特点

• ✅ 热重载：修改代码后自动刷新页面

• ✅ 实时预览：可以立即看到修改效果

• ✅ 错误提示：代码错误会在浏览器和终端中显示

• ✅ 调试友好：支持 Vue DevTools 等开发工具

• ✅ 快速编译：Vite 构建速度非常快

💡 提示：开发时不要关闭终端窗口，保持开发服务器运行。

---

6. 生产环境打包

开发完成后，需要打包成生产版本部署到服务器。

6.1 打包前准备

检查配置

打开 admin/.env.production，确认配置正确：
NODE_ENV = 'production'
VITE_APP_BASE_URL = ''

确认后端服务正常

• 确保后端服务可以正常访问
• 测试 API 接口是否正常
  6.2 执行打包命令

在 admin 目录下执行

npm run build

或使用 yarn

yarn build

6.3 等待打包完成

打包过程通常需要 1-3 分钟，终端会显示进度。

打包成功的标志：

• 终端显示 "Build complete"
• 生成了 dist 目录（临时目录）
• 文件自动复制到 server/public/admin/ 目录
  打包后的文件位置：
  server/public/admin/
  ├── assets/ # 静态资源（JS、CSS、图片等）
  ├── index.html # 入口 HTML 文件
  └── ...

6.4 部署到服务器

方式一：整体部署（推荐）

将整个 server 目录上传到服务器，管理后台的文件已经在 server/public/admin/ 下了。

方式二：单独部署

只上传 server/public/admin/ 目录到你的服务器。

访问地址：
https://yourdomain.com/admin/

---

7. 开发技巧

7.1 创建新页面

Admin 端使用手动配置路由的方式。

第 1 步：创建页面组件

在 admin/src/views/ 下创建页面文件：

第 2 步：创建 API 接口

在 admin/src/api/ 下创建 API 文件：

// admin/src/api/article.ts
import request from '@/utils/request'

// 文章列表
export function apiArticleList(params: any) {
return request.get('/article/lists', { params })
}

// 文章详情
export function apiArticleDetail(id: number) {
return request.get('/article/detail', { params: { id } })
}

// 添加文章
export function apiArticleAdd(data: any) {
return request.post('/article/add', data)
}

// 编辑文章
export function apiArticleEdit(data: any) {
return request.post('/article/edit', data)
}

// 删除文章
export function apiArticleDelete(id: number) {
return request.post('/article/delete', { id })
}

第 3 步：配置路由

在 admin/src/router/ 下配置路由（具体位置可能因项目而异）：

// 在路由配置文件中添加
{
path: '/article',
name: 'article',
meta: { title: '文章管理', icon: 'el-icon-document' },
children: [
{
path: 'list',
name: 'article-list',
component: () => import('@/views/article/list.vue'),
meta: { title: '文章列表' }
}
]
}

---

7.2 使用状态管理（Pinia）

创建 Store

在 admin/src/stores/ 下创建状态管理文件：

// admin/src/stores/article.ts
import { defineStore } from 'pinia'
import { apiArticleList } from '@/api/article'

export const useArticleStore = defineStore('article', {
state: () => ({
list: [],
total: 0,
loading: false
}),

getters: {
// 已发布的文章
publishedArticles: (state) => {
return state.list.filter((item: any) => item.status === 1)
}
},

actions: {
// 获取文章列表
async getList(params: any) {
this.loading = true
try {
const { data } = await apiArticleList(params)
this.list = data.lists
this.total = data.count
} finally {
this.loading = false
}
},

// 清空列表
clearList() {
this.list = []
this.total = 0
}
}
})

在组件中使用

---

7.3 使用 Element Plus 组件

Admin 端已经全局引入了 Element Plus，可以直接使用所有组件。

常用组件示例：

更多组件：

• 访问 Element Plus 官网：https://element-plus.org/

---

7.4 图片/文件上传

---

7.5 使用富文本编辑器

Admin 端已经集成了 wangEditor 富文本编辑器。

---

8. 常见问题解决

问题 1：npm install 失败

错误提示：
npm ERR! code ERESOLVE
npm ERR! ERESOLVE unable to resolve dependency tree

解决方法：

方法 1：清除缓存重新安装

npm cache clean --force
rmdir /s /q node_modules
del package-lock.json
npm install

方法 2：使用 --legacy-peer-deps

npm install --legacy-peer-deps

方法 3：使用 yarn 代替

npm install -g yarn
yarn install

---

问题 2：端口被占用

错误提示：
Port 5173 is already in use

解决方法：

方法 1：更换端口

修改 admin/vite.config.ts 文件：
export default defineConfig({
server: {
port: 5174 // 改成其他端口
}
})

方法 2：关闭占用进程（Windows）

查找占用端口的进程

netstat -ano | findstr :5173

结束进程（替换为实际的 PID）

taskkill /PID 12345 /F

---

问题 3：打包后访问白屏

可能原因：

• API 地址配置错误
• 后端服务未启动
• 路径配置问题
  排查步骤：

1. 检查 .env.production 中的 VITE_APP_BASE_URL 配置
2. 打开浏览器控制台（F12），查看具体错误
3. 检查网络请求是否成功（Network 标签）
4. 确认后端服务正常运行

---

问题 4：登录失败或无法访问

解决方法：

1. 检查后端服务是否正常启动
2. 检查 .env.development 中的 API 地址是否正确
3. 打开浏览器控制台，查看网络请求是否成功
4. 检查账号密码是否正确

---

问题 5：组件样式不生效

解决方法：

1. 检查是否正确导入了组件的样式文件
2. 如果使用了 scoped，尝试使用深度选择器：

/* 使用深度选择器 */ :deep(.el-button) { color: red; }

---

问题 6：跨域问题

错误提示：
Access to XMLHttpRequest has been blocked by CORS policy

解决方法：

开发环境：配置代理（修改 vite.config.ts）
export default defineConfig({
server: {
proxy: {
'/api': {
target: 'http://127.0.0.1:8000',
changeOrigin: true
}
}
}
})

生产环境：后端需要配置 CORS 跨域支持。

---

9. 快速参考

9.1 常用命令

安装依赖

npm install

或

yarn install

启动开发服务器

npm run dev

或

yarn dev

打包生产版本

npm run build

或

yarn build

预览打包结果

npm run preview

或

yarn preview

代码检查

npm run lint

或

yarn lint

---

9.2 配置文件位置

文件
路径
说明
开发环境配置
admin/.env.development
本地开发用
生产环境配置
admin/.env.production
打包上线用
Vite 配置
admin/vite.config.ts
构建工具配置
包管理配置
admin/package.json
依赖和脚本
TypeScript 配置
admin/tsconfig.json
TS 配置
路由配置
admin/src/router/
路由配置目录

---

9.3 重要目录结构

admin/
├── src/
│ ├── api/ # API 接口定义
│ ├── components/ # 公共组件
│ ├── config/ # 配置文件
│ ├── enums/ # 枚举定义
│ ├── hooks/ # 组合式函数
│ ├── layout/ # 布局组件
│ ├── router/ # 路由配置
│ ├── stores/ # 状态管理（Pinia）
│ ├── styles/ # 样式文件
│ ├── utils/ # 工具函数
│ ├── views/ # 页面组件
│ ├── App.vue # 根组件
│ └── main.ts # 入口文件
├── .env.development # 开发环境配置
├── .env.production # 生产环境配置
├── vite.config.ts # Vite 配置
└── package.json # 项目配置

---

9.4 开发流程速查

首次开发：

1. cd admin
2. npm install
3. copy .env.development.example .env.development
4. copy .env.production.example .env.production
5. 编辑 .env.development，填写 API 地址
6. npm run dev
7. 访问 http://localhost:5173/admin/

日常开发：

1. cd admin
2. npm run dev
3. 修改代码
4. 浏览器自动刷新

打包部署：

1. 编辑 .env.production
2. npm run build
3. 上传 server/public/admin/ 到服务器

---

🎯 总结

本指南涵盖了 Admin 端二次开发的所有关键步骤：

1. ✅ 环境准备（Node.js、npm/yarn）
2. ✅ 安装配置（依赖、环境文件）
3. ✅ 开发调试（启动服务、热重载）
4. ✅ 打包部署（生产打包）
5. ✅ 开发技巧（页面创建、组件使用）
6. ✅ 问题解决（常见错误处理）
   推荐学习资源：

• Vue 3 官方文档：https://cn.vuejs.org/
• Element Plus 组件库：https://element-plus.org/
• Vite 官方文档：https://cn.vitejs.dev/
• Pinia 状态管理：https://pinia.vuejs.org/
  祝你开发顺利！🚀