JeecgBoot 前端如何用 Nginx 部署：最小可用配置到性能调优完整指南

JeecgBoot 前端如何用 Nginx 部署：最小可用配置到性能调优完整指南

【免费下载链接】jeecg-boot【低代码v2.0，一句话即可生成整个系统】企业级AI低代码平台，一键生成前后端代码甚至整个系统。 AI Skills 一句话画流程、设计表单、生成报表、大屏。内置 AI应用平台涵盖：AI聊天、知识库、流程编排、MCP插件等，兼容主流大模型。引领AI低代码「Skills 生成 → 在线配置 → 代码生成 → 手工合并->AI修改」开发模式，解决 Java 项目 90% 重复工作，提高效率又不失灵活。项目地址: https://gitcode.com/GitHub_Trending/je/jeecg-boot

跟着做完，你会得到一个可访问的 JeecgBoot 前端页面：浏览器打开就是登录页，API 请求统一走 Nginx 同源代理，刷新任意路由不再报 404。全程大约 30 分钟，不需要额外查 Nginx 配置文档。

JeecgBoot 是 Spring Boot 企业级低代码平台，前端 jeecgboot-vue3 采用 Vue3 + Vite 技术栈。本文基于 3.9.3 版本，讲清楚 JeecgBoot 前端部署中 Nginx 配置怎么配、为什么要这么配、遇到问题怎么查。

1. 部署架构速览

先建立一张心智地图，再动手：

三条链路记住就行：

• 页面和 js/css 等静态文件由 Nginx 直接从磁盘读，不碰后端；
• 所有 API 请求带/jeecgboot/前缀，由 Nginx 转发给后端容器；
• 前端走 history 路由，找不到静态文件的请求统一回落到index.html。

2. 环境与文件清单

动手前确认这些条件是否满足：

构建时注意两点：普通部署用npm run build；如果走 Docker 编排，仓库的.env.docker中VITE_PUBLIC_PATH = /，对应脚本是npm run build:docker，保证资源路径与 Nginx 的 root 目录对齐。

与部署直接相关的仓库文件：

• 前端 Nginx 配置模板（写在镜像构建里）：jeecgboot-vue3/Dockerfile
• 容器编排与端口映射：docker-compose.yml
• Vite 入口与 base 路径逻辑：jeecgboot-vue3/vite.config.ts

docker-compose.yml里jeecg-vue服务对外暴露 80 端口，依赖jeecg-boot-system，启动顺序不用你操心。

3. 最小可用的 Nginx 配置写法

最小目标只有一个：页面能打开，登录接口能调通。配置很短，核心就四段：

server { listen 80; # API 统一入口：前端请求 /jeecgboot/** 都在这里转发 location /jeecgboot/ { rewrite ^/jeecgboot/?(.*)$ /jeecg-boot/$1 break; # 对齐后端 context-path proxy_pass http://jeecg-boot-system:8080; proxy_set_header X-Real-IP $remote_addr; # 后端拿到真实来源 IP } # 前端静态资源 + history 路由回落 location / { root /var/www/html; index index.html; try_files $uri $uri/ /index.html; # 刷新路由不 404 的关键 } }

逐项说明为什么这样写：

官方 Docker 镜像里还多了一行resolver 127.0.0.11 valid=10s。原因是 Docker 内部 DNS：后端容器重启后 IP 会变，Nginx 若缓存了旧 IP 就会持续 502。裸机部署不需要，Docker 部署建议保留。

4. 分档性能优化：必做 / 推荐 / 进阶

优化点不多，但顺序有讲究。先做影响首屏的，再谈锦上添花。

必做：Gzip 压缩 + 静态资源缓存

首屏体积是 Vite 项目的大头，压缩能砍掉 60% 以上的传输量：

gzip on; gzip_min_length 1k; # 小于 1k 的响应不压缩，省 CPU gzip_comp_level 5; # 5 是压缩率与 CPU 的平衡点 gzip_types text/css application/javascript application/json text/xml;

缓存策略分两层：带 hash 的 js/css 内容即版本，可以长缓存；index.html必须禁缓存，否则发版后用户拿的还是旧入口文件，chunk 引用全部失效。

location ~* \.[a-f0-9]{8,}\.(js|css|png|svg|woff2)$ { expires 30d; add_header Cache-Control "public"; } location = /index.html { add_header Cache-Control "no-cache"; }

推荐：连接复用 + 后端转发头补全

keepalive_timeout 65; # 长连接复用，减少握手开销

同时确认 API 代理里带上了X-Forwarded-For，后端限流、日志审计都依赖它。这一档改动小、收益稳，生产环境建议直接带上。

进阶：防盗链与 HTTPS

有图片、文件下载场景且站点公开时，可加 referer 白名单拦截盗链：

valid_referers none blocked server_names; # server_names 匹配本域名 if ($invalid_referer) { return 403; }

上 HTTPS 时用证书替换 80 端口配置，并把前端构建的 base 保持为/，不要动。资源量大后可把带 hash 的静态文件推给 CDN，Nginx 只留 API 代理和路由回落，这是集群部署的常规做法。

5. 常见坑位与排查速查

要点回顾

• Nginx 在 JeecgBoot 前端部署里干两件事：发静态文件、代理/jeecgboot/前缀的 API，其余都是优化；
• try_files回落 + rewrite 前缀对齐，是页面能跑通的两条命根子；
• 缓存策略记住"hash 资源长缓存、index.html 禁缓存"，发版事故能少一大半。

更多部署细节（微服务、Nacos 编排、数据库初始化脚本）可参考仓库根目录的 docker-compose.yml 与 README.md，按章节对照你的实际环境调整即可。

【免费下载链接】jeecg-boot【低代码v2.0，一句话即可生成整个系统】企业级AI低代码平台，一键生成前后端代码甚至整个系统。 AI Skills 一句话画流程、设计表单、生成报表、大屏。内置 AI应用平台涵盖：AI聊天、知识库、流程编排、MCP插件等，兼容主流大模型。引领AI低代码「Skills 生成 → 在线配置 → 代码生成 → 手工合并->AI修改」开发模式，解决 Java 项目 90% 重复工作，提高效率又不失灵活。项目地址: https://gitcode.com/GitHub_Trending/je/jeecg-boot