Mall4j Nginx 配置实战：管理后台静态托管与后端接口反向代理完整指南

• 电商
• 后端
• 前端
• 移动开发

本文聚焦 Mall4j 电商系统部署中最容易踩坑的一环——Nginx 配置。文章将说明 Nginx 在 Mall4j 项目中的两个典型用途（托管管理后台静态文件、反向代理后端接口），并围绕"前端 API 地址 → 后端真实监听端口 → Nginx location 与 proxy_pass 三者必须对齐"这条主线，给出可直接复制使用的配置示例与生产环境调整要点。读完本文，你将能根据自己实际的启动方式（jar 或 Docker）和端口，正确搭建管理后台的 Nginx 站点，并为用户端接口配置稳妥的转发规则。

为什么 Mall4j 部署需要 Nginx

Mall4j 后端由两个 Java 服务构成（详见 部署总览）：

而前端管理后台mall4v构建后是纯静态资源，通常直接交给 Nginx 托管；后端接口是否通过 Nginx 反向代理，取决于前端配置里VITE_APP_BASE_API写的是完整后端地址还是相对路径。这就是文档开篇强调的"先对齐三件事，再抄配置"的原因：

1. front-end/mall4v/.env.production里的VITE_APP_BASE_API写成什么；
2. yami-shop-admin实际监听哪个端口；
3. Nginx 的location和proxy_pass必须和上面两项一致。

注意：本文给出的两套示例（完整地址方案与/apis相对路径方案）是互斥的，不要把它们拼在一起，否则会出现请求被 Nginx 重复改写或代理地址不匹配的问题。

第一步：构建并准备管理后台静态文件

管理后台使用 Vite 构建，进入front-end/mall4v目录执行：

cd front-end\mall4v pnpm run build

构建产物输出到front-end/mall4v/dist（Vite 的build配置见 vite.config.js，产物会被分类写入static/js/、static/[ext]/等目录）。随后把dist目录整体上传到服务器上的 Nginx 静态目录，例如：

/usr/share/nginx/admin

项目自带的 Docker 镜像构建方式与此一致：front-end/mall4v/Dockerfile执行COPY ./dist /usr/share/nginx/html/dist并把nginx.conf复制到/etc/nginx/conf.d，托管路径为/usr/share/nginx/html/dist。如果走 Docker 方式，静态托管 root 应相应写成该路径。

端口对照：先确认当前进程真实监听端口

Mall4j 不同启动方式对应不同端口，配置proxy_pass前必须先核对：

• 本地/开发环境端口来自dev与dockerprofile，Docker 方式下docker-compose.yml将容器8085/8086端口映射到宿主机同名端口；
• 生产环境以 jar 启动并启用prodprofile 时，管理端 application-prod.yml 中server.port: 8111，用户端 application-prod.yml 中server.port: 8112；
• 默认application.yml的spring.profiles.active是dev，因此"只改了端口没换 profile"是常见翻车点。

proxy_pass必须指向当前进程真实端口：不要看见文档里的8085就照抄到生产，反之亦然。如果改了application-prod.yml里的端口，Nginx 与前端配置必须同步修改。

方案 A（推荐，与仓库默认一致）：前端写完整后端地址，Nginx 只托管静态文件

当前仓库三个前端的生产配置默认都指向本机完整地址：

• 管理后台front-end/mall4v/.env.production：

VITE_APP_BASE_API = 'http://127.0.0.1:8085'

• uni-appfront-end/mall4uni/.env.production：

VITE_APP_BASE_API = 'http://127.0.0.1:8086'

• 原生小程序front-end/mall4m不走VITE_APP_BASE_API，接口地址在 utils/config.js 的domain字段，默认同样为http://127.0.0.1:8086。

这是本地开发口径。若后端以prodprofile 启动，前端需要改成服务器 IP 加对应 prod 端口：

• mall4v改成http://<服务器IP>:8111
• mall4uni/mall4m改成http://<服务器IP>:8112

两个前端不要写成同一个端口：管理后台只能连管理端接口，用户端只能连用户端接口，写反会导致登录或业务接口全部报错。

该方案下 Nginx只需托管管理后台静态文件，不必配置/api/代理。参考配置：

server { listen 80; server_name admin.example.com; root /usr/share/nginx/admin; index index.html; location / { try_files $uri $uri/ /index.html; } location /api/ { proxy_pass http://127.0.0.1:8085/; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; } }

说明：

• location /配合try_files ... /index.html是 Vue/Vite 单页应用的标准写法，保证前端路由刷新（如/login、/prod/prodInfo）不产生 404；
• location /api/与proxy_pass http://127.0.0.1:8085/配合时，Nginx 会把/api/xxx中/api前缀剥掉，转发为/xxx。如果前端VITE_APP_BASE_API直接写完整后端地址，则不一定需要/api/代理；如果写相对路径（如/api），则需要 Nginx 配合。请根据实际配置取舍，避免既写完整地址又让 Nginx 剥前缀导致路径错乱。

源码视角：VITE_APP_BASE_API是如何生效的

VITE_APP_BASE_API并非魔法变量，它的作用链路在 front-end/mall4v/src/utils/http.js 中清晰可见：

• http.adornUrl = actionName => import.meta.env.VITE_APP_BASE_API + actionName（见 http.js），所有业务接口 URL 都由它拼接前缀；
• 滑块验证码组件在 components/verifition/utils/axios.js 中通过axios.defaults.baseURL = import.meta.env.VITE_APP_BASE_API全局设置 baseURL。

因此，无论前端把VITE_APP_BASE_API写成完整地址还是相对路径，最终发出的请求路径都以它为前缀，Nginx 的 location 与 proxy_pass 必须与之一一对应，这正是"三件事对齐"的源码依据。同时，http.js中http.adornUrl会对所有请求追加Authorizationtoken 与时间戳参数（见请求拦截器），反向代理时务必通过proxy_set_header透传 Host 与真实 IP，避免后端拿到的请求头不完整。

方案 B：/apis相对路径转发方式

旧部署文档中使用过/apis前缀来减少后台接口的域名/端口数量。虽然当前front-end/mall4v/.env.production默认仍是完整地址，但生产环境若希望收敛为相对路径，可把前端配置改为：

VITE_APP_BASE_API = '/apis'

此时管理后台发出的所有请求都形如/apis/xxx，需要在 Nginx 增加对应转发：

location /apis { rewrite ^/apis/(.*)$ /$1 break; proxy_pass http://127.0.0.1:8111; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; }

关键点：

• 上面的8111来自当前yami-shop-admin的 application-prod.yml。如果生产端口改了，Nginx 也要同步改；
• rewrite ^/apis/(.*)$ /$1 break的作用是把/apis/xxx还原为/xxx后再转发，确保后端收到的是无前缀路径；
• 若同一台服务器还要托管用户端 H5，请为yami-shop-api单独增加一个location（如/apis-h5）指向8112，不要与管理端共用/apis前缀，避免接口错连。

生产环境注意事项

• 管理后台只能连管理端接口8085（或 prod 的8111）；小程序、H5、uni-app 只能连用户端接口8086（或 prod 的8112）；
• 微信小程序正式环境通常要求 HTTPS 域名，Nginx 需额外配置 SSL 证书并监听 443，VITE_APP_BASE_API也要随之换成https://完整地址；
• 接入支付回调时，回调域名必须能被第三方支付平台访问，即该域名解析与端口（443/80）对外可达，且不能是127.0.0.1之类的内网地址；
• 静态资源（图片等）默认使用VITE_APP_RESOURCES_URL（仓库默认https://img.mall4j.com/），如自建对象存储或本地存储，需同步修改该变量并在 Nginx/存储侧配置可公网访问的域名；
• 修改.env.production后必须重新执行pnpm run build，Vite 会在构建期把import.meta.env.VITE_APP_*编译进产物，仅改文件不重新构建不会生效；
• 上线后可用curl验证链路：curl http://<域名>/api/xxx观察是否被正确转发到后端端口，再用curl http://127.0.0.1:8111/xxx直连后端对比响应，从而快速定位是 Nginx 配置还是后端端口的问题。

小结

Nginx 在 Mall4j 部署中的核心任务可以概括为一张对照表：

无论选择哪种方案，只要坚持"前端 API 地址、后端真实端口、Nginx location/proxy_pass"三者对齐，并依据当前启动方式（dev/docker用 8085/8086，prodjar 用 8111/8112）核对端口，管理后台与用户端的线上访问即可稳定运行。相关的部署顺序、后端打包等完整流程可继续阅读 部署总览 与 Docker 部署。

• 电商
• 后端
• 前端
• 移动开发