一、速览：先搞清楚 Mall4j 是什么、能干什么

入门

Mall4j 是一套 Java 技术栈的电商商城系统，仓库里的开源版聚焦 B2C 单商户场景。后端基于 Spring Boot 4 + Sa-Token + MyBatis-Plus + Redis，前端管理后台是 Vue3，同时提供小程序/H5/APP 的商城端。

对开发者来说，它的价值在于：完整跑通「商品 → SKU → 购物车 → 下单 → 支付」这条电商主链路，而且前后端分离、代码结构清晰，适合拿来当企业商城原型或学习电商业务逻辑的参考实现。

注意开源版是 AGPLv3 协议，学习评估没问题，闭源商用需要走官网商业授权。多商户、SaaS、跨境这些能力在开源版里没有，属于企业版范围。

二、安装：本地开发环境三步跑起来

入门

Mall4j 依赖 JDK 17+、Maven 3.6+、Node.js 16+、MySQL 8.0+、Redis 6+。建议先装好这些基础环境，再按下面顺序操作。

第一步：拉取代码

git clone https://github.com/gz-yami/mall4j.git
cd mall4j

仓库结构分两块：mall4j-backend（Spring Boot 后端）和 mall4j-admin（Vue3 管理后台）。商城端（小程序/H5/APP）在独立子仓库，先不用管。

第二步：初始化数据库

# 创建数据库 mall4j，字符集 utf8mb4
mysql -uroot -p -e "CREATE DATABASE mall4j DEFAULT CHARACTER SET utf8mb4;"
# 导入项目自带的 SQL 脚本
mysql -uroot -p mall4j < mall4j-backend/sql/mall4j.sql

SQL 文件里已经包含表结构和基础数据（管理员账号、菜单权限、演示商品），不用手动建表。

第三步：启动后端和前端

# 后端：修改 application.yml 里的 MySQL/Redis 连接信息后启动
cd mall4j-backend
mvn spring-boot:run

# 前端管理后台：另开一个终端
cd mall4j-admin
npm install
npm run dev

后端默认跑在 8080 端口，前端管理后台跑在 5173。浏览器打开 http://localhost:5173，用 SQL 里预置的管理员账号登录即可看到后台界面。

三、核心用法：后台管理的主要模块

入门

登录后台后，左侧菜单就是完整的运营后台。几个核心模块值得先过一遍：

• 商品管理：创建商品、配置规格（SKU）、设置价格库存、上传图片。SKU 支持多规格组合，比如颜色×尺码
• 订单管理：订单列表、订单详情、发货/退款操作，订单状态流转是电商系统的核心逻辑
• 会员管理：用户列表、会员等级、余额/积分变动记录
• 运费模板：按地区配置运费规则，支持包邮、按件、按重量计费
• 系统设置：支付方式配置、小程序密钥、短信通道等

建议上手路径：先在商品管理里创建一个带多规格的商品 → 去商城端下单 → 回后台看订单状态变化 → 走一遍发货流程。这条链路跑通，你对整个系统的数据流转就有概念了。

四、配置：理解后端几个关键配置项

入门

后端配置集中在 mall4j-backend/src/main/resources/application.yml，几个关键项：

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/mall4j?useUnicode=true&characterEncoding=utf8mb4
    username: root
    password: your_password
  redis:
    host: localhost
    port: 6379
    password:          # 如果 Redis 设置了密码，填在这里

mall4j:
  # 上传文件的本地存储路径
  upload-path: /data/upload
  # 商城端的访问域名，用于生成支付回调等 URL
  domain: http://localhost:8080

mall4j.domain 这个配置容易忽略——小程序支付回调、H5 跳转都会用它拼 URL，本地调试改成 http://localhost:8080 即可。上传路径建议改成绝对路径，避免相对路径在不同启动目录下产生文件找不到的问题。

前端管理后台的接口地址配置在 mall4j-admin/.env.development 里，默认指向 http://localhost:8080，如果后端换了端口要同步改这里。

五、运维场景：部署到服务器和容器化

进阶 · 推荐细读

本地跑通后，部署到测试服务器是常见需求。建议直接用 Docker Compose 编排整套环境，比手动装 MySQL/Redis/Java 省事得多。

# docker-compose.yml
version: '3'
services:
  mysql:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: root123
      MYSQL_DATABASE: mall4j
    volumes:
      - ./sql:/docker-entrypoint-initdb.d   # 首次启动自动导入 SQL
    ports:
      - "3306:3306"

  redis:
    image: redis:7
    ports:
      - "6379:6379"

  backend:
    build: ./mall4j-backend
    depends_on:
      - mysql
      - redis
    environment:
      SPRING_DATASOURCE_URL: jdbc:mysql://mysql:3306/mall4j
      SPRING_REDIS_HOST: redis
    ports:
      - "8080:8080"

  admin:
    build: ./mall4j-admin
    depends_on:
      - backend
    ports:
      - "80:80"

两个注意点：

• SQL 挂载到 docker-entrypoint-initdb.d 目录后，MySQL 容器首次启动会自动执行初始化脚本，不用手动导入
• 前端容器要配 Nginx 反向代理，把 /api 路径转发到后端容器的 8080 端口，否则浏览器会跨域

后端服务层面，Mall4j 依赖 Redis 做缓存和分布式锁，生产环境建议 Redis 开启持久化（AOF），避免重启丢缓存导致缓存雪崩。MySQL 侧建议开启 binlog，方便后续做数据同步或回溯。

六、踩坑：本地搭建常见问题

进阶 · 推荐细读

1. 数据库字符集必须是 utf8mb4

Mall4j 的商品数据含 emoji 和生僻字，如果用默认的 utf8 字符集，插入数据会报 Incorrect string value 错误。建库时显式指定：

CREATE DATABASE mall4j DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

2. 前端 npm install 卡住或报错

项目依赖较多，建议用淘宝镜像源：

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

如果安装过程中报 node-sass 相关的错，通常是 Node 版本和依赖不兼容，建议用 nvm 切到 Node 16 LTS 版本再试。

3. 支付功能本地没法完整测试

微信支付/支付宝需要商户号和回调域名，本地环境没有外网回调地址，支付流程会在发起支付后卡住。建议先用「模拟支付」或「货到付款」的方式走通订单流程，等部署到有公网 IP 的服务器再配真实支付。

4. 上传图片后页面不显示

检查 mall4j.upload-path 配置的目录是否存在且有写权限，以及 mall4j.domain 是否配置正确。图片访问路径是 domain + 相对路径 拼接的，域名配错会导致图片 404。

七、评估：这个项目适不适合你

深入 · 老手可选

从技术选型的角度给个判断参考：

• 想学电商业务逻辑：商品-SKU-订单-支付这条链路在开源版里是完整的，代码组织清晰，适合精读
• 想快速搭商城原型：后台管理功能够用，配合演示数据，一天内能跑起来给业务方看效果
• 想直接商用：注意 AGPLv3 的传染性——如果你把代码集成进自己的闭源系统并对外提供服务，需要开源整个衍生作品。闭源商用必须走商业授权

另外提醒一点：Mall4j 开源版只有 B2C 单商户能力，如果你需要多商户入驻、分销、跨境这类功能，开源版里没有，需要评估企业版或者考虑其他方案，避免开发到一半发现能力边界不够。

项目信息

参考链接

• GitHub 仓库
• 项目主页