超详细！从零搭建Spring Boot+Vue3电商系统mall开发环境（附避坑指南）_源码搭建

一、项目概述

mall 项目是一套完整的电商系统，包含前台商城系统及后台管理系统，基于现阶段主流Java技术栈构建，并支持Docker容器化部署。该项目在GitHub上已获得超过84k Stars和29.7k Forks，是Java开发者学习和实战电商项目的优秀开源项目。
null

1.1 项目地址

后端项目：https://github.com/macrozheng/mall
后台管理前端：https://github.com/macrozheng/mall-admin-web
移动端商城前端：https://github.com/macrozheng/mall-app-web
官方文档：https://www.macrozheng.com

1.2 版本分支说明

项目提供了多个分支以适应不同的开发环境：

master 分支：基于 Spring Boot 3.5 + JDK 17，前端对应 Vue3 + Element Plus
dev-v2 分支：基于 Spring Boot 2.7 + JDK 8，前端对应 Vue2 + Element

在开始搭建环境之前，请根据自己的需求选择合适的分支。本文将以 master 分支为例进行说明。

二、后端开发环境搭建

后端环境是整套系统的基础，需要安装多个中间件和服务。如果只希望运行后台管理系统（mall-admin），则仅需安装 MySQL 和 Redis 即可。

2.1 开发工具准备

工具	说明	下载地址
IDEA	Java开发IDE	https://www.jetbrains.com/idea/download
Navicat	数据库连接工具	http://www.formysql.com/xiazai.html
RedisDesktop	Redis客户端	https://github.com/qishibo/AnotherRedisDesktopManager
Robomongo	MongoDB客户端	https://robomongo.org/download
Postman	API接口调试工具	https://www.postman.com/
Git	版本控制工具	https://git-scm.com/

2.2 基础环境配置

2.2.1 JDK安装

根据选择的分支，需要安装对应的JDK版本：

master 分支：JDK 17
dev-v2 分支：JDK 8

下载地址：https://www.oracle.com/java/technologies/javase/jdk17-archive-downloads.html

安装完成后，需要配置环境变量 JAVA_HOME 并将 bin 目录添加到 PATH 中。

2.2.2 IDEA导入项目

克隆项目源码：

git clone https://github.com/macrozheng/mall.git

打开IDEA，点击 File -> Open，选择项目根目录导入。
等待Maven依赖下载完成（首次导入可能需要较长时间）。
进入 File -> Project Structure，设置正确的JDK版本。

2.3 数据库与缓存服务

2.3.1 MySQL（必需）

版本要求：MySQL 5.7
下载地址：https://dev.mysql.com/downloads/installer/
安装配置：
1. 安装时设置root账号密码为 root（可根据需要修改，但需同步修改项目配置）。
2. 安装完成后，使用Navicat或其他客户端连接MySQL。
3. 创建数据库：
```
CREATE DATABASE mall CHARACTER SET utf8mb4;
```
4. 导入初始化数据：运行项目根目录下 document/sql/mall.sql 文件。

2.3.2 Redis（必需）

版本要求：Redis 7.0+
下载地址：
- Windows版本（第三方提供）：https://github.com/tporadowski/redis/releases
- Linux版本：https://redis.io/download
启动方式：
- Windows：解压后进入目录，执行 redis-server.exe redis.windows.conf
- 注册为服务：
```
redis-server --service-install redis.windows.conf
redis-server --service-start
```

2.4 高级服务（可选）

以下服务用于支持搜索、日志收集、消息队列等功能。如果仅进行基础功能测试，可以暂不安装。

2.4.1 Elasticsearch（搜索引擎）

版本要求：7.17.3
下载地址：https://www.elastic.co/cn/downloads/past-releases/elasticsearch-7-17-3
安装步骤：
1. 解压zip包到指定目录。
2. 安装中文分词器（注意版本对应）：https://github.com/medcl/elasticsearch-analysis-ik/releases
  将分词器解压到Elasticsearch的 plugins 目录下。
3. 运行 bin/elasticsearch.bat 启动服务。
4. 访问 http://localhost:9200 验证是否启动成功。

2.4.2 Kibana（可视化工具）

版本要求：7.17.3
下载地址：https://www.elastic.co/cn/downloads/past-releases/kibana-7-17-3
安装步骤：
1. 解压zip包。
2. 运行 bin/kibana.bat 启动服务。
3. 访问 http://localhost:5601 打开Kibana界面。

2.4.3 Logstash（日志收集）

版本要求：7.17.3
下载地址：https://www.elastic.co/cn/downloads/past-releases/logstash-7-17-3
注意事项：
- Logstash 7.17.3 需要 JDK 11 环境。
- 需要在环境变量中设置 LS_JAVA_HOME 指向JDK 11安装目录。
- 将项目中的 logstash.conf 配置文件拷贝到Logstash的 bin 目录下。
- 启动命令：logstash -f logstash.conf

2.4.4 MongoDB（NoSQL数据库）

版本要求：5.0
下载地址：https://www.mongodb.com/download-center/community
安装步骤：
1. 选择自定义安装，设置安装路径和数据目录。
2. 建议将MongoDB安装为Windows服务。
3. 如需移除服务：使用管理员权限运行 sc.exe delete MongoDB

2.4.5 RabbitMQ（消息队列）

版本要求：3.10.5
前置依赖：Erlang/OTP 25
下载地址：
- Erlang：https://erlang.org/download/otp_versions_tree.html
- RabbitMQ：https://github.com/rabbitmq/rabbitmq-server/releases
配置步骤：
1. 先安装Erlang，再安装RabbitMQ。
2. 进入RabbitMQ的 sbin 目录，启用管理功能：
```
rabbitmq-plugins enable rabbitmq_management
```
3. 访问管理页面 http://localhost:15672，默认账号密码 guest:guest。
4. 创建用户：账号 mall，密码 mall，设置为管理员角色。
5. 创建虚拟主机 /mall，并为 mall 用户分配权限。

2.4.6 MinIO（对象存储）

下载地址：https://dl.min.io/server/minio/release/windows-amd64/minio.exe

启动命令：

minio.exe server D:\minio\data --console-address ":9001"

访问地址：http://localhost:9001，默认账号密码 minioadmin:minioadmin

2.5 后端服务模块启动

项目包含多个子模块，可根据需要选择启动。

2.5.1 mall-admin（后台管理系统接口）

运行 com.macro.mall.MallAdminApplication 的 main 方法。
接口文档：http://localhost:8080/swagger-ui/
默认管理员账号：admin / 密码：macro123

2.5.2 mall-search（商品搜索系统）

运行 com.macro.mall.search.MallSearchApplication 的 main 方法。
重要：启动后需调用导入数据接口 /esProduct/importAll，将商品数据同步到Elasticsearch。
接口文档：http://localhost:8081/swagger-ui/

2.5.3 mall-portal（前台商城系统接口）

运行 com.macro.mall.portal.MallPortalApplication 的 main 方法。
接口文档：http://localhost:8085/swagger-ui/
默认测试账号：test / 密码：123456

三、前端开发环境搭建

前端项目共有两个：mall-admin-web（后台管理）和 mall-app-web（移动端商城），均已完成 Vue3 升级。

3.1 通用准备工作

Node.js：必须安装 v20 以上版本（建议使用 v20.x LTS版本）
- 下载地址：https://nodejs.org/zh-cn/download/archive/v20.20.0
包管理器：npm（随Node.js一起安装）
开发IDE：推荐 VSCode（https://code.visualstudio.com/）或IDEA

为提高依赖下载速度，可配置淘宝镜像源：

npm config set registry https://registry.npmmirror.com

3.2 后台管理系统：mall-admin-web

这是一个电商后台管理界面，基于 Vue3 + Element Plus 构建，包含商品管理、订单管理、会员管理、促销管理、运营管理、内容管理、统计报表、财务管理、权限管理、设置等功能。

3.2.1 获取代码与安装依赖

git clone https://github.com/macrozheng/mall-admin-web.git
cd mall-admin-web
npm install

3.2.2 配置后端接口地址

修改项目根目录下的 .env.development 文件中的 VITE_BASE_SERVER_URL：

# 连接本地后端（需启动 mall-admin）
VITE_BASE_SERVER_URL = http://localhost:8080

# 或使用在线演示API（仅有查看权限）
# VITE_BASE_SERVER_URL = https://admin-api.macrozheng.com

3.2.3 启动项目

npm run dev

访问地址：http://localhost:5173

3.2.4 项目结构说明

src/
├── apis/          # API请求定义
├── assets/        # 静态资源
├── components/    # 通用组件
├── router/        # 路由配置
├── store/         # Pinia状态管理
├── styles/        # 全局样式
├── types/         # TypeScript类型定义
├── utils/         # 工具函数
└── views/         # 页面视图
    ├── home/      # 首页
    ├── layout/    # 页面框架
    ├── oms/       # 订单管理
    ├── pms/       # 商品管理
    ├── sms/       # 促销管理
    └── ums/       # 用户管理

3.3 移动端商城：mall-app-web

这是一个基于 uni-app + Vue3 的移动端项目，可发布为H5或微信小程序，包含首页门户、商品搜索、商品展示、品牌专区、购物车、订单流程、支付、会员中心等功能。

3.3.1 获取代码与安装依赖

git clone https://github.com/macrozheng/mall-app-web.git
cd mall-app-web
npm install

3.3.2 配置后端接口地址

修改 .env.development 文件中的 VITE_API_BASE_URL：

# 连接本地后端（需启动 mall-portal）
VITE_API_BASE_URL=http://localhost:8085

# 或使用在线API
# VITE_API_BASE_URL=https://portal-api.macrozheng.com

3.3.3 运行项目

H5版本（浏览器预览）：

npm run dev:h5

访问地址：http://localhost:5173（建议切换至手机模式）

微信小程序版本：

npm run dev:mp-weixin

运行成功后，在项目根目录生成 dist/dev/mp-weixin 文件夹，使用微信开发者工具导入该目录即可预览。

3.3.4 项目结构说明

src/
├── apis/           # API请求（按业务模块划分）
├── components/     # 通用组件
├── composables/    # 组合式函数
├── pages/          # 页面
│   ├── address/    # 地址管理
│   ├── brand/      # 商品品牌
│   ├── cart/       # 购物车
│   ├── category/   # 商品分类
│   ├── index/      # 首页
│   ├── order/      # 订单
│   ├── product/    # 商品详情
│   ├── public/     # 登录页
│   └── user/       # 会员中心
├── static/         # 静态资源
├── stores/         # Pinia状态管理
├── styles/         # 全局样式
├── types/          # 类型定义
└── utils/          # 工具函数

3.4 快速部署方案

如果不想搭建前端开发环境，可直接使用发行包部署到Nginx：

下载发行包：
- 后台管理：https://github.com/macrozheng/mall-admin-web/releases
- 移动端商城：https://github.com/macrozheng/mall-app-web/releases
部署步骤：
- 解压 admin.zip 和 app.zip
- 将解压后的 admin 和 app 文件夹复制到Nginx的 html 目录下
- 启动Nginx后访问：
  - 后台：http://localhost/admin/
  - 前台：http://localhost/app/

四、常见问题与解决方案

4.1 后端常见问题

Q1：项目启动时报错 “Failed to configure a DataSource”

检查MySQL服务是否启动
检查 application.yml 中的数据库连接配置是否正确

Q2：Elasticsearch连接失败

确认Elasticsearch服务已启动（http://localhost:9200）
检查项目配置中的ES地址是否正确

Q3：Redis连接超时

确认Redis服务已启动
检查Redis配置的端口（默认6379）是否被占用

Q4：Maven依赖下载缓慢

配置阿里云Maven镜像：在 settings.xml 中添加镜像配置

4.2 前端常见问题

Q1：npm install 安装失败

检查Node.js版本是否满足要求（v20+）
清除npm缓存：npm cache clean --force
使用淘宝镜像源：npm config set registry https://registry.npmmirror.com

Q2：启动后页面无法访问接口

检查后端服务是否正常启动
检查 .env.development 中的API地址配置是否正确
注意跨域问题，开发环境下Vite已配置代理

Q3：微信小程序运行时白屏

检查是否已执行 npm run dev:mp-weixin 生成小程序文件
在微信开发者工具中执行 构建npm 操作

五、总结

通过以上步骤，你应该能够成功搭建 mall 项目的完整开发环境。整个环境涉及：

后端服务：JDK、MySQL、Redis为必需；Elasticsearch、Kibana、Logstash、MongoDB、RabbitMQ、MinIO为可选增强服务。
后端模块：mall-admin（后台管理接口）、mall-search（搜索服务）、mall-portal（前台接口）。
前端项目：mall-admin-web（Vue3后台管理界面）、mall-app-web（uni-app移动端商城）。
快速部署：可直接使用发行包部署到Nginx进行演示。

mall 项目不仅是一个功能完整的电商系统，更是一个学习现代Java开发和前端技术的优秀案例。通过实践搭建过程，你可以深入理解Spring Boot、Vue3、Elasticsearch、RabbitMQ等技术在实际项目中的应用。

超详细！从零搭建Spring Boot+Vue3电商系统mall开发环境（附避坑指南）