在实际全栈开发中前端 Vue3 与后端 Node.js 的配合是构建现代化后台管理系统的常见选择。很多开发者虽然能分别使用 Vue3 或 Node.js但当需要将它们与 MySQL 数据库整合成一个完整可用的后台管理系统时往往会遇到环境配置混乱、前后端数据流不清晰、权限控制不完整、部署调试困难等问题。本文将以一个完整的后台管理系统为例从零开始搭建 Vue3 全家桶Vue Router、Pinia、Vite前端项目配合 Node.js Express 后端服务连接 MySQL 数据库实现增删改查业务逻辑最终形成一个可学习、可复现、可扩展的全栈项目实战。1. 环境准备与工具版本确认全栈项目对环境一致性要求较高版本不匹配会导致各种依赖冲突和运行错误。1.1 开发环境要求在开始编码前需要确认本地开发环境满足以下要求环境/工具版本要求检查命令备注Node.js18.x 或更高node --version长期支持版本避免使用奇数版本npm9.x 或更高npm --version通常随 Node.js 安装MySQL8.0 或更高mysql --version社区版即可注意身份验证方式浏览器Chrome 90-支持现代 JavaScript 特性1.2 解决 Node.js 安装和权限问题从热词中可以看到很多开发者遇到 npm 脚本执行权限问题。这是因为 Windows PowerShell 的执行策略限制。安装 Node.js 步骤访问 Node.js 官网下载 LTS 版本运行安装程序默认选项即可会自动添加环境变量安装完成后验证node --version # 应输出 v18.x.x 或更高 npm --version # 应输出 9.x.x 或更高解决 npm 脚本执行错误如果遇到无法加载文件 npm.ps1因为在此系统上禁止运行脚本错误需要修改 PowerShell 执行策略以管理员身份打开 PowerShell执行Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser然后重新打开终端验证 npm 命令是否可用。1.3 MySQL 安装与配置MySQL 安装过程中的常见问题是服务启动失败和身份验证插件冲突。安装步骤下载 MySQL Community Server 8.0选择适合操作系统的安装包安装过程中设置 root 密码记下该密码选择使用传统身份验证方法MySQL 5.x 兼容避免新的 caching_sha2_password 插件问题验证安装mysql -u root -p输入密码后应进入 MySQL 命令行界面。创建项目数据库CREATE DATABASE vue3_admin DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; USE vue3_admin;2. 前端 Vue3 项目搭建与配置Vue3 的 Composition API 和新的工具链为开发大型应用提供了更好的支持。2.1 使用 Vite 创建 Vue3 项目Vite 提供了更快的冷启动和热更新适合开发阶段使用。npm create vuelatest vue3-admin-frontend cd vue3-admin-frontend npm install项目创建过程中选择需要的特性TypeScript是JSX否除非热词中提到的 JSX 需求Vue Router是Pinia是状态管理ESLint是Prettier是2.2 项目结构调整默认的 Vue3 项目结构需要调整以适应后台管理系统需求src/ ├── api/ # API 接口封装 ├── components/ # 通用组件 ├── views/ # 页面组件 ├── router/ # 路由配置 ├── store/ # 状态管理 ├── utils/ # 工具函数 ├── types/ # TypeScript 类型定义 └── assets/ # 静态资源2.3 配置路由和基础布局在src/router/index.ts中配置基础路由import { createRouter, createWebHistory } from vue-router const routes [ { path: /, redirect: /dashboard }, { path: /login, name: Login, component: () import(/views/Login.vue) }, { path: /dashboard, name: Dashboard, component: () import(/views/Dashboard.vue), meta: { requiresAuth: true } }, { path: /user, name: User, component: () import(/views/user/UserList.vue), meta: { requiresAuth: true } } ] const router createRouter({ history: createWebHistory(), routes }) // 路由守卫检查登录状态 router.beforeEach((to, from, next) { const token localStorage.getItem(admin_token) if (to.meta.requiresAuth !token) { next(/login) } else { next() } }) export default router3. 后端 Node.js 服务搭建Express 框架简单易用适合快速构建 RESTful API。3.1 初始化 Node.js 项目mkdir vue3-admin-backend cd vue3-admin-backend npm init -y npm install express mysql2 cors dotenv bcryptjs jsonwebtoken npm install -D nodemon关键依赖说明mysql2MySQL 客户端支持 Promisecors处理跨域请求dotenv环境变量管理bcryptjs密码加密jsonwebtokenJWT 身份验证3.2 项目结构设计backend/ ├── config/ # 数据库配置 ├── controllers/ # 控制器 ├── models/ # 数据模型 ├── routes/ # 路由定义 ├── middleware/ # 中间件 ├── utils/ # 工具函数 └── app.js # 应用入口3.3 数据库连接配置在config/database.js中const mysql require(mysql2/promise) require(dotenv).config() const pool mysql.createPool({ host: process.env.DB_HOST || localhost, port: process.env.DB_PORT || 3306, user: process.env.DB_USER || root, password: process.env.DB_PASSWORD, database: process.env.DB_NAME || vue3_admin, waitForConnections: true, connectionLimit: 10, queueLimit: 0 }) module.exports pool在.env文件中配置数据库连接DB_HOSTlocalhost DB_PORT3306 DB_USERroot DB_PASSWORDyour_mysql_password DB_NAMEvue3_admin3.4 用户表结构和初始数据创建用户管理相关的数据表CREATE TABLE users ( id INT PRIMARY KEY AUTO_INCREMENT, username VARCHAR(50) UNIQUE NOT NULL, password VARCHAR(255) NOT NULL, email VARCHAR(100), role ENUM(admin, user) DEFAULT user, status TINYINT DEFAULT 1 COMMENT 1-正常, 0-禁用, created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP ); -- 插入管理员账户密码为加密后的 admin123 INSERT INTO users (username, password, email, role) VALUES (admin, $2a$10$N9qo8uLOickgx2ZMRZoMyeIjZAgcfl7p92ldGxad68LJZdL17lhWy, adminexample.com, admin);4. 前后端数据交互实现前后端分离架构中API 设计规范和错误处理机制至关重要。4.1 统一响应格式设计在后端utils/response.js中定义统一响应格式class ApiResponse { constructor(code, message, data null) { this.code code this.message message this.data data this.timestamp new Date().toISOString() } static success(data null, message 操作成功) { return new ApiResponse(200, message, data) } static error(message 操作失败, code 500) { return new ApiResponse(code, message) } } module.exports ApiResponse4.2 用户登录 API 实现在controllers/authController.js中const bcrypt require(bcryptjs) const jwt require(jsonwebtoken) const pool require(../config/database) const ApiResponse require(../utils/response) class AuthController { async login(req, res) { try { const { username, password } req.body if (!username || !password) { return res.status(400).json(ApiResponse.error(用户名和密码不能为空)) } // 查询用户 const [users] await pool.execute( SELECT * FROM users WHERE username ? AND status 1, [username] ) if (users.length 0) { return res.status(401).json(ApiResponse.error(用户名或密码错误)) } const user users[0] // 验证密码 const isValidPassword await bcrypt.compare(password, user.password) if (!isValidPassword) { return res.status(401).json(ApiResponse.error(用户名或密码错误)) } // 生成 JWT token const token jwt.sign( { userId: user.id, username: user.username, role: user.role }, process.env.JWT_SECRET || your-secret-key, { expiresIn: 24h } ) // 移除密码字段 const { password: _, ...userInfo } user res.json(ApiResponse.success({ token, user: userInfo }, 登录成功)) } catch (error) { console.error(登录错误:, error) res.status(500).json(ApiResponse.error(服务器内部错误)) } } } module.exports new AuthController()4.3 前端 API 封装在src/api/request.js中创建 axios 实例import axios from axios import { ElMessage } from element-plus import router from /router const request axios.create({ baseURL: http://localhost:3000/api, timeout: 10000 }) // 请求拦截器添加 token request.interceptors.request.use( (config) { const token localStorage.getItem(admin_token) if (token) { config.headers.Authorization Bearer ${token} } return config }, (error) { return Promise.reject(error) } ) // 响应拦截器统一错误处理 request.interceptors.response.use( (response) { const { code, message, data } response.data if (code 200) { return data } else { ElMessage.error(message || 请求失败) return Promise.reject(new Error(message)) } }, (error) { if (error.response?.status 401) { localStorage.removeItem(admin_token) router.push(/login) ElMessage.error(登录已过期请重新登录) } else { ElMessage.error(error.response?.data?.message || 网络错误) } return Promise.reject(error) } ) export default request4.4 前端登录页面实现在src/views/Login.vue中template div classlogin-container el-card classlogin-box h2后台管理系统/h2 el-form :modelform :rulesrules refloginForm el-form-item propusername el-input v-modelform.username placeholder用户名 prefix-iconUser / /el-form-item el-form-item proppassword el-input v-modelform.password typepassword placeholder密码 prefix-iconLock / /el-form-item el-form-item el-button typeprimary clickhandleLogin :loadingloading stylewidth: 100% 登录 /el-button /el-form-item /el-form /el-card /div /template script setup import { ref, reactive } from vue import { useRouter } from vue-router import { ElMessage } from element-plus import { userStore } from /store/user const router useRouter() const store userStore() const loginForm ref() const loading ref(false) const form reactive({ username: , password: }) const rules { username: [{ required: true, message: 请输入用户名, trigger: blur }], password: [{ required: true, message: 请输入密码, trigger: blur }] } const handleLogin async () { try { await loginForm.value.validate() loading.value true await store.login(form) ElMessage.success(登录成功) router.push(/dashboard) } catch (error) { console.error(登录失败:, error) } finally { loading.value false } } /script5. 后台管理系统核心功能实现用户管理和数据展示是后台管理系统的核心功能。5.1 用户列表页面与分页查询后端用户列表 API (controllers/userController.js)class UserController { async getUsers(req, res) { try { const { page 1, pageSize 10, username, role } req.query const offset (page - 1) * pageSize let whereClause WHERE status 1 const params [] if (username) { whereClause AND username LIKE ? params.push(%${username}%) } if (role) { whereClause AND role ? params.push(role) } // 查询总数 const [countResult] await pool.execute( SELECT COUNT(*) as total FROM users ${whereClause}, params ) // 查询数据 const [users] await pool.execute( SELECT id, username, email, role, created_at, updated_at FROM users ${whereClause} ORDER BY id DESC LIMIT ? OFFSET ?, [...params, parseInt(pageSize), offset] ) res.json(ApiResponse.success({ list: users, total: countResult[0].total, page: parseInt(page), pageSize: parseInt(pageSize) })) } catch (error) { console.error(获取用户列表错误:, error) res.status(500).json(ApiResponse.error(获取用户列表失败)) } } }前端用户列表页面 (src/views/user/UserList.vue)template div classuser-list el-card template #header div classcard-header span用户管理/span el-button typeprimary clickhandleAdd新增用户/el-button /div /template !-- 搜索条件 -- el-form :modelqueryParams inline el-form-item label用户名 el-input v-modelqueryParams.username placeholder请输入用户名 clearable / /el-form-item el-form-item label角色 el-select v-modelqueryParams.role placeholder请选择角色 clearable el-option label管理员 valueadmin / el-option label普通用户 valueuser / /el-select /el-form-item el-form-item el-button typeprimary clickloadData搜索/el-button el-button clickresetQuery重置/el-button /el-form-item /el-form !-- 用户表格 -- el-table :datauserList v-loadingloading el-table-column propid labelID width80 / el-table-column propusername label用户名 / el-table-column propemail label邮箱 / el-table-column proprole label角色 template #default{ row } el-tag :typerow.role admin ? danger : primary {{ row.role admin ? 管理员 : 普通用户 }} /el-tag /template /el-table-column el-table-column propcreated_at label创建时间 / el-table-column label操作 width200 template #default{ row } el-button sizesmall clickhandleEdit(row)编辑/el-button el-button sizesmall typedanger clickhandleDelete(row)删除/el-button /template /el-table-column /el-table !-- 分页 -- div classpagination el-pagination v-model:current-pagequeryParams.page v-model:page-sizequeryParams.pageSize :totaltotal :page-sizes[10, 20, 50, 100] layouttotal, sizes, prev, pager, next, jumper size-changeloadData current-changeloadData / /div /el-card /div /template script setup import { ref, reactive, onMounted } from vue import { ElMessage, ElMessageBox } from element-plus import { getUserList, deleteUser } from /api/user const loading ref(false) const userList ref([]) const total ref(0) const queryParams reactive({ page: 1, pageSize: 10, username: , role: }) const loadData async () { try { loading.value true const response await getUserList(queryParams) userList.value response.list total.value response.total } catch (error) { console.error(加载用户列表失败:, error) } finally { loading.value false } } const resetQuery () { Object.assign(queryParams, { page: 1, username: , role: }) loadData() } const handleDelete async (row) { try { await ElMessageBox.confirm(确定删除该用户吗, 提示, { type: warning }) await deleteUser(row.id) ElMessage.success(删除成功) loadData() } catch (error) { if (error ! cancel) { ElMessage.error(删除失败) } } } onMounted(() { loadData() }) /script5.2 状态管理使用 Pinia在src/store/user.js中管理用户状态import { defineStore } from pinia import { login, logout, getUserInfo } from /api/auth export const useUserStore defineStore(user, { state: () ({ token: localStorage.getItem(admin_token) || , userInfo: null }), getters: { isLoggedIn: (state) !!state.token, userRole: (state) state.userInfo?.role }, actions: { async login(loginForm) { const response await login(loginForm) this.token response.token this.userInfo response.user localStorage.setItem(admin_token, response.token) }, async logout() { await logout() this.token this.userInfo null localStorage.removeItem(admin_token) }, async getUserInfo() { if (this.token) { this.userInfo await getUserInfo() } } } })6. 常见问题排查与解决方案在实际开发过程中会遇到各种环境配置和代码逻辑问题。6.1 跨域问题处理开发环境下前端通常运行在 5173 端口访问后端3000 端口会出现跨域问题。后端 CORS 配置 (app.js)const express require(express) const cors require(cors) const app express() // CORS 配置 app.use(cors({ origin: [http://localhost:5173, http://127.0.0.1:5173], credentials: true })) app.use(express.json()) app.use(express.urlencoded({ extended: true })) // 路由引入 app.use(/api/auth, require(./routes/auth)) app.use(/api/users, require(./routes/users)) const PORT process.env.PORT || 3000 app.listen(PORT, () { console.log(服务器运行在端口 ${PORT}) })6.2 数据库连接失败排查MySQL 连接失败的常见原因和解决方案问题现象可能原因检查方式解决方案ECONNREFUSEDMySQL 服务未启动sudo systemctl status mysql启动服务sudo systemctl start mysqlAccess denied密码错误或权限不足使用命令行测试连接重置密码或授权用户访问权限Unknown database数据库不存在SHOW DATABASES;创建数据库CREATE DATABASE vue3_admin;Authentication plugin身份验证插件不兼容SELECT user,plugin FROM mysql.user;修改用户插件ALTER USER rootlocalhost IDENTIFIED WITH mysql_native_password BY password;6.3 JWT Token 验证问题Token 验证失败的可能原因Token 过期检查生成 token 时的 expiresIn 配置Secret 不匹配确保前后端使用相同的 JWT secretToken 格式错误确认 Authorization header 格式为Bearer {token}后端验证中间件 (middleware/auth.js)const jwt require(jsonwebtoken) const ApiResponse require(../utils/response) const authMiddleware (req, res, next) { const token req.header(Authorization)?.replace(Bearer , ) if (!token) { return res.status(401).json(ApiResponse.error(访问令牌缺失)) } try { const decoded jwt.verify(token, process.env.JWT_SECRET) req.user decoded next() } catch (error) { return res.status(401).json(ApiResponse.error(令牌无效或已过期)) } } module.exports authMiddleware6.4 前端路由守卫与权限控制基于用户角色进行页面访问控制// 在 router/index.ts 中增强路由守卫 router.beforeEach((to, from, next) { const store useUserStore() if (to.meta.requiresAuth) { if (!store.isLoggedIn) { next(/login) return } // 角色权限检查 if (to.meta.roles !to.meta.roles.includes(store.userRole)) { next(/403) // 无权限页面 return } } next() })7. 生产环境部署建议开发完成后的项目需要为生产环境做准备。7.1 环境变量配置分离创建不同的环境配置文件.env.development开发环境.env.production生产环境生产环境配置示例NODE_ENVproduction DB_HOSTlocalhost DB_PORT3306 DB_USERadmin_user DB_PASSWORDstrong_password DB_NAMEvue3_admin_prod JWT_SECRETyour-production-secret-key API_BASE_URLhttps://api.yourdomain.com7.2 前端项目构建优化Vite 生产环境构建配置// vite.config.js import { defineConfig } from vite import vue from vitejs/plugin-vue export default defineConfig(({ mode }) ({ plugins: [vue()], base: mode production ? /admin/ : /, build: { outDir: dist, assetsDir: assets, rollupOptions: { output: { chunkFileNames: assets/js/[name]-[hash].js, entryFileNames: assets/js/[name]-[hash].js, assetFileNames: assets/[ext]/[name]-[hash].[ext] } } }, server: { proxy: { /api: { target: http://localhost:3000, changeOrigin: true } } } }))7.3 后端服务进程管理使用 PM2 管理 Node.js 进程npm install -g pm2 # 创建 ecosystem.config.js module.exports { apps: [{ name: vue3-admin-api, script: ./app.js, instances: max, exec_mode: cluster, env: { NODE_ENV: production, PORT: 3000 } }] } # 启动服务 pm2 start ecosystem.config.js pm2 save pm2 startup7.4 数据库备份与监控设置定期数据库备份# 备份脚本 backup.sh #!/bin/bash DATE$(date %Y%m%d_%H%M%S) mysqldump -u root -p your_password vue3_admin_prod /backup/vue3_admin_${DATE}.sql find /backup -name vue3_admin_*.sql -mtime 7 -delete # 添加到 crontab 每天凌晨备份 0 2 * * * /path/to/backup.sh8. 项目扩展方向与最佳实践完成基础功能后可以考虑以下扩展方向提升项目完整性。8.1 功能扩展建议菜单权限管理根据用户角色动态生成侧边栏菜单操作日志记录记录用户关键操作便于审计文件上传功能集成云存储或本地文件管理数据可视化使用 ECharts 等库添加统计图表消息通知系统站内信或邮件通知功能API 文档生成使用 Swagger 自动生成接口文档8.2 代码质量提升TypeScript 强化为所有接口和组件添加完整类型定义单元测试覆盖使用 Vitest 进行前端测试Jest 进行后端测试代码规范检查配置 ESLint Prettier 确保代码一致性Git Hooks提交前自动运行代码检查和测试Docker 容器化使用 Docker 统一开发和生产环境8.3 性能优化措施前端懒加载路由组件和大型第三方库按需加载API 缓存策略合理使用 Redis 缓存频繁查询的数据数据库索引优化为常用查询字段添加合适索引静态资源 CDN将 CSS、JS、图片等资源部署到 CDN前端监控集成使用 Sentry 等工具监控前端错误这个全栈项目涵盖了从环境搭建到生产部署的完整流程重点解决了实际开发中常见的配置问题和业务逻辑实现。通过这个项目开发者可以掌握 Vue3 组合式 API 的实际应用、Node.js 后端服务开发、数据库设计优化以及前后端协同开发的完整工作流。每个技术选型都基于当前主流实践代码结构清晰易于扩展为构建更复杂的企业级应用打下了坚实基础。
Vue3+Node.js全栈后台管理系统实战：从环境配置到生产部署
在实际全栈开发中前端 Vue3 与后端 Node.js 的配合是构建现代化后台管理系统的常见选择。很多开发者虽然能分别使用 Vue3 或 Node.js但当需要将它们与 MySQL 数据库整合成一个完整可用的后台管理系统时往往会遇到环境配置混乱、前后端数据流不清晰、权限控制不完整、部署调试困难等问题。本文将以一个完整的后台管理系统为例从零开始搭建 Vue3 全家桶Vue Router、Pinia、Vite前端项目配合 Node.js Express 后端服务连接 MySQL 数据库实现增删改查业务逻辑最终形成一个可学习、可复现、可扩展的全栈项目实战。1. 环境准备与工具版本确认全栈项目对环境一致性要求较高版本不匹配会导致各种依赖冲突和运行错误。1.1 开发环境要求在开始编码前需要确认本地开发环境满足以下要求环境/工具版本要求检查命令备注Node.js18.x 或更高node --version长期支持版本避免使用奇数版本npm9.x 或更高npm --version通常随 Node.js 安装MySQL8.0 或更高mysql --version社区版即可注意身份验证方式浏览器Chrome 90-支持现代 JavaScript 特性1.2 解决 Node.js 安装和权限问题从热词中可以看到很多开发者遇到 npm 脚本执行权限问题。这是因为 Windows PowerShell 的执行策略限制。安装 Node.js 步骤访问 Node.js 官网下载 LTS 版本运行安装程序默认选项即可会自动添加环境变量安装完成后验证node --version # 应输出 v18.x.x 或更高 npm --version # 应输出 9.x.x 或更高解决 npm 脚本执行错误如果遇到无法加载文件 npm.ps1因为在此系统上禁止运行脚本错误需要修改 PowerShell 执行策略以管理员身份打开 PowerShell执行Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser然后重新打开终端验证 npm 命令是否可用。1.3 MySQL 安装与配置MySQL 安装过程中的常见问题是服务启动失败和身份验证插件冲突。安装步骤下载 MySQL Community Server 8.0选择适合操作系统的安装包安装过程中设置 root 密码记下该密码选择使用传统身份验证方法MySQL 5.x 兼容避免新的 caching_sha2_password 插件问题验证安装mysql -u root -p输入密码后应进入 MySQL 命令行界面。创建项目数据库CREATE DATABASE vue3_admin DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; USE vue3_admin;2. 前端 Vue3 项目搭建与配置Vue3 的 Composition API 和新的工具链为开发大型应用提供了更好的支持。2.1 使用 Vite 创建 Vue3 项目Vite 提供了更快的冷启动和热更新适合开发阶段使用。npm create vuelatest vue3-admin-frontend cd vue3-admin-frontend npm install项目创建过程中选择需要的特性TypeScript是JSX否除非热词中提到的 JSX 需求Vue Router是Pinia是状态管理ESLint是Prettier是2.2 项目结构调整默认的 Vue3 项目结构需要调整以适应后台管理系统需求src/ ├── api/ # API 接口封装 ├── components/ # 通用组件 ├── views/ # 页面组件 ├── router/ # 路由配置 ├── store/ # 状态管理 ├── utils/ # 工具函数 ├── types/ # TypeScript 类型定义 └── assets/ # 静态资源2.3 配置路由和基础布局在src/router/index.ts中配置基础路由import { createRouter, createWebHistory } from vue-router const routes [ { path: /, redirect: /dashboard }, { path: /login, name: Login, component: () import(/views/Login.vue) }, { path: /dashboard, name: Dashboard, component: () import(/views/Dashboard.vue), meta: { requiresAuth: true } }, { path: /user, name: User, component: () import(/views/user/UserList.vue), meta: { requiresAuth: true } } ] const router createRouter({ history: createWebHistory(), routes }) // 路由守卫检查登录状态 router.beforeEach((to, from, next) { const token localStorage.getItem(admin_token) if (to.meta.requiresAuth !token) { next(/login) } else { next() } }) export default router3. 后端 Node.js 服务搭建Express 框架简单易用适合快速构建 RESTful API。3.1 初始化 Node.js 项目mkdir vue3-admin-backend cd vue3-admin-backend npm init -y npm install express mysql2 cors dotenv bcryptjs jsonwebtoken npm install -D nodemon关键依赖说明mysql2MySQL 客户端支持 Promisecors处理跨域请求dotenv环境变量管理bcryptjs密码加密jsonwebtokenJWT 身份验证3.2 项目结构设计backend/ ├── config/ # 数据库配置 ├── controllers/ # 控制器 ├── models/ # 数据模型 ├── routes/ # 路由定义 ├── middleware/ # 中间件 ├── utils/ # 工具函数 └── app.js # 应用入口3.3 数据库连接配置在config/database.js中const mysql require(mysql2/promise) require(dotenv).config() const pool mysql.createPool({ host: process.env.DB_HOST || localhost, port: process.env.DB_PORT || 3306, user: process.env.DB_USER || root, password: process.env.DB_PASSWORD, database: process.env.DB_NAME || vue3_admin, waitForConnections: true, connectionLimit: 10, queueLimit: 0 }) module.exports pool在.env文件中配置数据库连接DB_HOSTlocalhost DB_PORT3306 DB_USERroot DB_PASSWORDyour_mysql_password DB_NAMEvue3_admin3.4 用户表结构和初始数据创建用户管理相关的数据表CREATE TABLE users ( id INT PRIMARY KEY AUTO_INCREMENT, username VARCHAR(50) UNIQUE NOT NULL, password VARCHAR(255) NOT NULL, email VARCHAR(100), role ENUM(admin, user) DEFAULT user, status TINYINT DEFAULT 1 COMMENT 1-正常, 0-禁用, created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP ); -- 插入管理员账户密码为加密后的 admin123 INSERT INTO users (username, password, email, role) VALUES (admin, $2a$10$N9qo8uLOickgx2ZMRZoMyeIjZAgcfl7p92ldGxad68LJZdL17lhWy, adminexample.com, admin);4. 前后端数据交互实现前后端分离架构中API 设计规范和错误处理机制至关重要。4.1 统一响应格式设计在后端utils/response.js中定义统一响应格式class ApiResponse { constructor(code, message, data null) { this.code code this.message message this.data data this.timestamp new Date().toISOString() } static success(data null, message 操作成功) { return new ApiResponse(200, message, data) } static error(message 操作失败, code 500) { return new ApiResponse(code, message) } } module.exports ApiResponse4.2 用户登录 API 实现在controllers/authController.js中const bcrypt require(bcryptjs) const jwt require(jsonwebtoken) const pool require(../config/database) const ApiResponse require(../utils/response) class AuthController { async login(req, res) { try { const { username, password } req.body if (!username || !password) { return res.status(400).json(ApiResponse.error(用户名和密码不能为空)) } // 查询用户 const [users] await pool.execute( SELECT * FROM users WHERE username ? AND status 1, [username] ) if (users.length 0) { return res.status(401).json(ApiResponse.error(用户名或密码错误)) } const user users[0] // 验证密码 const isValidPassword await bcrypt.compare(password, user.password) if (!isValidPassword) { return res.status(401).json(ApiResponse.error(用户名或密码错误)) } // 生成 JWT token const token jwt.sign( { userId: user.id, username: user.username, role: user.role }, process.env.JWT_SECRET || your-secret-key, { expiresIn: 24h } ) // 移除密码字段 const { password: _, ...userInfo } user res.json(ApiResponse.success({ token, user: userInfo }, 登录成功)) } catch (error) { console.error(登录错误:, error) res.status(500).json(ApiResponse.error(服务器内部错误)) } } } module.exports new AuthController()4.3 前端 API 封装在src/api/request.js中创建 axios 实例import axios from axios import { ElMessage } from element-plus import router from /router const request axios.create({ baseURL: http://localhost:3000/api, timeout: 10000 }) // 请求拦截器添加 token request.interceptors.request.use( (config) { const token localStorage.getItem(admin_token) if (token) { config.headers.Authorization Bearer ${token} } return config }, (error) { return Promise.reject(error) } ) // 响应拦截器统一错误处理 request.interceptors.response.use( (response) { const { code, message, data } response.data if (code 200) { return data } else { ElMessage.error(message || 请求失败) return Promise.reject(new Error(message)) } }, (error) { if (error.response?.status 401) { localStorage.removeItem(admin_token) router.push(/login) ElMessage.error(登录已过期请重新登录) } else { ElMessage.error(error.response?.data?.message || 网络错误) } return Promise.reject(error) } ) export default request4.4 前端登录页面实现在src/views/Login.vue中template div classlogin-container el-card classlogin-box h2后台管理系统/h2 el-form :modelform :rulesrules refloginForm el-form-item propusername el-input v-modelform.username placeholder用户名 prefix-iconUser / /el-form-item el-form-item proppassword el-input v-modelform.password typepassword placeholder密码 prefix-iconLock / /el-form-item el-form-item el-button typeprimary clickhandleLogin :loadingloading stylewidth: 100% 登录 /el-button /el-form-item /el-form /el-card /div /template script setup import { ref, reactive } from vue import { useRouter } from vue-router import { ElMessage } from element-plus import { userStore } from /store/user const router useRouter() const store userStore() const loginForm ref() const loading ref(false) const form reactive({ username: , password: }) const rules { username: [{ required: true, message: 请输入用户名, trigger: blur }], password: [{ required: true, message: 请输入密码, trigger: blur }] } const handleLogin async () { try { await loginForm.value.validate() loading.value true await store.login(form) ElMessage.success(登录成功) router.push(/dashboard) } catch (error) { console.error(登录失败:, error) } finally { loading.value false } } /script5. 后台管理系统核心功能实现用户管理和数据展示是后台管理系统的核心功能。5.1 用户列表页面与分页查询后端用户列表 API (controllers/userController.js)class UserController { async getUsers(req, res) { try { const { page 1, pageSize 10, username, role } req.query const offset (page - 1) * pageSize let whereClause WHERE status 1 const params [] if (username) { whereClause AND username LIKE ? params.push(%${username}%) } if (role) { whereClause AND role ? params.push(role) } // 查询总数 const [countResult] await pool.execute( SELECT COUNT(*) as total FROM users ${whereClause}, params ) // 查询数据 const [users] await pool.execute( SELECT id, username, email, role, created_at, updated_at FROM users ${whereClause} ORDER BY id DESC LIMIT ? OFFSET ?, [...params, parseInt(pageSize), offset] ) res.json(ApiResponse.success({ list: users, total: countResult[0].total, page: parseInt(page), pageSize: parseInt(pageSize) })) } catch (error) { console.error(获取用户列表错误:, error) res.status(500).json(ApiResponse.error(获取用户列表失败)) } } }前端用户列表页面 (src/views/user/UserList.vue)template div classuser-list el-card template #header div classcard-header span用户管理/span el-button typeprimary clickhandleAdd新增用户/el-button /div /template !-- 搜索条件 -- el-form :modelqueryParams inline el-form-item label用户名 el-input v-modelqueryParams.username placeholder请输入用户名 clearable / /el-form-item el-form-item label角色 el-select v-modelqueryParams.role placeholder请选择角色 clearable el-option label管理员 valueadmin / el-option label普通用户 valueuser / /el-select /el-form-item el-form-item el-button typeprimary clickloadData搜索/el-button el-button clickresetQuery重置/el-button /el-form-item /el-form !-- 用户表格 -- el-table :datauserList v-loadingloading el-table-column propid labelID width80 / el-table-column propusername label用户名 / el-table-column propemail label邮箱 / el-table-column proprole label角色 template #default{ row } el-tag :typerow.role admin ? danger : primary {{ row.role admin ? 管理员 : 普通用户 }} /el-tag /template /el-table-column el-table-column propcreated_at label创建时间 / el-table-column label操作 width200 template #default{ row } el-button sizesmall clickhandleEdit(row)编辑/el-button el-button sizesmall typedanger clickhandleDelete(row)删除/el-button /template /el-table-column /el-table !-- 分页 -- div classpagination el-pagination v-model:current-pagequeryParams.page v-model:page-sizequeryParams.pageSize :totaltotal :page-sizes[10, 20, 50, 100] layouttotal, sizes, prev, pager, next, jumper size-changeloadData current-changeloadData / /div /el-card /div /template script setup import { ref, reactive, onMounted } from vue import { ElMessage, ElMessageBox } from element-plus import { getUserList, deleteUser } from /api/user const loading ref(false) const userList ref([]) const total ref(0) const queryParams reactive({ page: 1, pageSize: 10, username: , role: }) const loadData async () { try { loading.value true const response await getUserList(queryParams) userList.value response.list total.value response.total } catch (error) { console.error(加载用户列表失败:, error) } finally { loading.value false } } const resetQuery () { Object.assign(queryParams, { page: 1, username: , role: }) loadData() } const handleDelete async (row) { try { await ElMessageBox.confirm(确定删除该用户吗, 提示, { type: warning }) await deleteUser(row.id) ElMessage.success(删除成功) loadData() } catch (error) { if (error ! cancel) { ElMessage.error(删除失败) } } } onMounted(() { loadData() }) /script5.2 状态管理使用 Pinia在src/store/user.js中管理用户状态import { defineStore } from pinia import { login, logout, getUserInfo } from /api/auth export const useUserStore defineStore(user, { state: () ({ token: localStorage.getItem(admin_token) || , userInfo: null }), getters: { isLoggedIn: (state) !!state.token, userRole: (state) state.userInfo?.role }, actions: { async login(loginForm) { const response await login(loginForm) this.token response.token this.userInfo response.user localStorage.setItem(admin_token, response.token) }, async logout() { await logout() this.token this.userInfo null localStorage.removeItem(admin_token) }, async getUserInfo() { if (this.token) { this.userInfo await getUserInfo() } } } })6. 常见问题排查与解决方案在实际开发过程中会遇到各种环境配置和代码逻辑问题。6.1 跨域问题处理开发环境下前端通常运行在 5173 端口访问后端3000 端口会出现跨域问题。后端 CORS 配置 (app.js)const express require(express) const cors require(cors) const app express() // CORS 配置 app.use(cors({ origin: [http://localhost:5173, http://127.0.0.1:5173], credentials: true })) app.use(express.json()) app.use(express.urlencoded({ extended: true })) // 路由引入 app.use(/api/auth, require(./routes/auth)) app.use(/api/users, require(./routes/users)) const PORT process.env.PORT || 3000 app.listen(PORT, () { console.log(服务器运行在端口 ${PORT}) })6.2 数据库连接失败排查MySQL 连接失败的常见原因和解决方案问题现象可能原因检查方式解决方案ECONNREFUSEDMySQL 服务未启动sudo systemctl status mysql启动服务sudo systemctl start mysqlAccess denied密码错误或权限不足使用命令行测试连接重置密码或授权用户访问权限Unknown database数据库不存在SHOW DATABASES;创建数据库CREATE DATABASE vue3_admin;Authentication plugin身份验证插件不兼容SELECT user,plugin FROM mysql.user;修改用户插件ALTER USER rootlocalhost IDENTIFIED WITH mysql_native_password BY password;6.3 JWT Token 验证问题Token 验证失败的可能原因Token 过期检查生成 token 时的 expiresIn 配置Secret 不匹配确保前后端使用相同的 JWT secretToken 格式错误确认 Authorization header 格式为Bearer {token}后端验证中间件 (middleware/auth.js)const jwt require(jsonwebtoken) const ApiResponse require(../utils/response) const authMiddleware (req, res, next) { const token req.header(Authorization)?.replace(Bearer , ) if (!token) { return res.status(401).json(ApiResponse.error(访问令牌缺失)) } try { const decoded jwt.verify(token, process.env.JWT_SECRET) req.user decoded next() } catch (error) { return res.status(401).json(ApiResponse.error(令牌无效或已过期)) } } module.exports authMiddleware6.4 前端路由守卫与权限控制基于用户角色进行页面访问控制// 在 router/index.ts 中增强路由守卫 router.beforeEach((to, from, next) { const store useUserStore() if (to.meta.requiresAuth) { if (!store.isLoggedIn) { next(/login) return } // 角色权限检查 if (to.meta.roles !to.meta.roles.includes(store.userRole)) { next(/403) // 无权限页面 return } } next() })7. 生产环境部署建议开发完成后的项目需要为生产环境做准备。7.1 环境变量配置分离创建不同的环境配置文件.env.development开发环境.env.production生产环境生产环境配置示例NODE_ENVproduction DB_HOSTlocalhost DB_PORT3306 DB_USERadmin_user DB_PASSWORDstrong_password DB_NAMEvue3_admin_prod JWT_SECRETyour-production-secret-key API_BASE_URLhttps://api.yourdomain.com7.2 前端项目构建优化Vite 生产环境构建配置// vite.config.js import { defineConfig } from vite import vue from vitejs/plugin-vue export default defineConfig(({ mode }) ({ plugins: [vue()], base: mode production ? /admin/ : /, build: { outDir: dist, assetsDir: assets, rollupOptions: { output: { chunkFileNames: assets/js/[name]-[hash].js, entryFileNames: assets/js/[name]-[hash].js, assetFileNames: assets/[ext]/[name]-[hash].[ext] } } }, server: { proxy: { /api: { target: http://localhost:3000, changeOrigin: true } } } }))7.3 后端服务进程管理使用 PM2 管理 Node.js 进程npm install -g pm2 # 创建 ecosystem.config.js module.exports { apps: [{ name: vue3-admin-api, script: ./app.js, instances: max, exec_mode: cluster, env: { NODE_ENV: production, PORT: 3000 } }] } # 启动服务 pm2 start ecosystem.config.js pm2 save pm2 startup7.4 数据库备份与监控设置定期数据库备份# 备份脚本 backup.sh #!/bin/bash DATE$(date %Y%m%d_%H%M%S) mysqldump -u root -p your_password vue3_admin_prod /backup/vue3_admin_${DATE}.sql find /backup -name vue3_admin_*.sql -mtime 7 -delete # 添加到 crontab 每天凌晨备份 0 2 * * * /path/to/backup.sh8. 项目扩展方向与最佳实践完成基础功能后可以考虑以下扩展方向提升项目完整性。8.1 功能扩展建议菜单权限管理根据用户角色动态生成侧边栏菜单操作日志记录记录用户关键操作便于审计文件上传功能集成云存储或本地文件管理数据可视化使用 ECharts 等库添加统计图表消息通知系统站内信或邮件通知功能API 文档生成使用 Swagger 自动生成接口文档8.2 代码质量提升TypeScript 强化为所有接口和组件添加完整类型定义单元测试覆盖使用 Vitest 进行前端测试Jest 进行后端测试代码规范检查配置 ESLint Prettier 确保代码一致性Git Hooks提交前自动运行代码检查和测试Docker 容器化使用 Docker 统一开发和生产环境8.3 性能优化措施前端懒加载路由组件和大型第三方库按需加载API 缓存策略合理使用 Redis 缓存频繁查询的数据数据库索引优化为常用查询字段添加合适索引静态资源 CDN将 CSS、JS、图片等资源部署到 CDN前端监控集成使用 Sentry 等工具监控前端错误这个全栈项目涵盖了从环境搭建到生产部署的完整流程重点解决了实际开发中常见的配置问题和业务逻辑实现。通过这个项目开发者可以掌握 Vue3 组合式 API 的实际应用、Node.js 后端服务开发、数据库设计优化以及前后端协同开发的完整工作流。每个技术选型都基于当前主流实践代码结构清晰易于扩展为构建更复杂的企业级应用打下了坚实基础。
