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. 环境与文件清单动手前确认这些条件是否满足项目要求说明Node.js建议 18前端构建需要构建脚本预留了 8GB 堆内存Nginx1.20Docker 方式用官方 nginx 镜像即可后端服务jeecg-boot-system 已启动Nginx 会把 API 转发给它前端构建产物dist/目录执行npm run build生成构建时注意两点普通部署用npm run build如果走 Docker 编排仓库的.env.docker中VITE_PUBLIC_PATH /对应脚本是npm run build:docker保证资源路径与 Nginx 的 root 目录对齐。与部署直接相关的仓库文件前端 Nginx 配置模板写在镜像构建里jeecgboot-vue3/Dockerfile容器编排与端口映射docker-compose.ymlVite 入口与 base 路径逻辑jeecgboot-vue3/vite.config.tsdocker-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 的关键 } }逐项说明为什么这样写配置项作用location /jeecgboot/proxy_passAPI 走同源代理浏览器端没有跨域也避免了前端硬编码后端地址rewrite成/jeecg-boot/$1后端 context-path 是/jeecg-boot前缀必须对齐否则接口 404root /var/www/htmldist 产物目录Docker 构建时就是拷到这里try_files ... /index.htmlVue Router history 模式的兜底找不到静态文件就交给前端路由官方 Docker 镜像里还多了一行resolver 127.0.0.11 valid10s。原因是 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 的静态文件推给 CDNNginx 只留 API 代理和路由回落这是集群部署的常规做法。5. 常见坑位与排查速查现象可能原因处理方式刷新/system/user等路由报 404缺 history 模式回落规则补try_files $uri $uri/ /index.htmlAPI 一律 404后端 context-path 与 rewrite 不一致检查 rewrite 目标是否为/jeecg-boot/Docker 下突然 502重启 Nginx 又好了后端容器 IP 变化Nginx 缓存旧 IP加resolver 127.0.0.11 valid10s页面白屏控制台报 chunk 加载失败发版后旧 index.html 被缓存引用了不存在的 hash 文件index.html加no-cache头接口跨域报错前端直连了后端地址没走代理统一请求/jeecgboot/前缀靠 Nginx 转发首屏明显偏慢未开 gzip 或产物未分包按第 4 章必做项落地必要时npm run build:report看体积要点回顾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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考