boot-react 生产部署完全指南：如何把 React 资源打包进 Spring Boot Fat JAR

boot-react 生产部署完全指南：如何把 React 资源打包进 Spring Boot Fat JAR

【免费下载链接】boot-react A starter application with spring boot and react 项目地址: https://gitcode.com/gh_mirrors/bo/boot-react

🚀 boot-react 是一个经典的 Spring Boot + React 全栈脚手架。它最大的亮点是：通过一条 Gradle 命令，就能把 React 前端构建产物直接打包进 Spring Boot Fat JAR，让你只部署一个 JAR 文件就跑起整个前后端应用。本文带你完整拆解「React 资源打包进 Spring Boot JAR」的全流程。

一、项目结构速览：前后端双模块协作

boot-react 采用 Gradle 多项目结构，前后端各占一个子模块，由 settings.gradle 统一注册：

模块	目录	职责
后端	backend/	Spring Boot 应用、Spring Security、Spring Session
前端	frontend/	React + Redux + webpack 构建

理解这个结构是关键：后端的 jar 任务会依赖前端的 assemble 任务，这就是「一条命令打包两个世界」的底层原理。

二、一条命令：把 React 构建产物装进 JAR

2.1 打包命令（最快方式）

在项目根目录执行：

./gradlew clean assemble

构建完成后，产物位于 backend/build/libs/boot-react-0.0.1-SNAPSHOT.jar。

2.2 打包机制全解析

整个过程由两个 Gradle 文件协作完成：

① 前端构建（frontend/build.gradle）

• 通过 Node 插件自动下载 Node 6.10.3，无需本机安装 Node 环境
• bundle 任务执行 yarn run bundle，调用 webpack 生产配置
• assemble 任务依赖 bundle，输出到 frontend/dist 目录

② 前端生产配置（frontend/webpack.config.js）

• NODE_ENV=production 开启 React 生产模式
• UglifyJsPlugin 压缩混淆 JS
• ExtractTextPlugin 把 Stylus 样式抽取为独立的 styles.css
• CommonsChunkPlugin 将 node_modules 依赖分离为 vendors.js，利于浏览器缓存

③ JAR 装配（backend/build.gradle 第 56-62 行，核心代码仅 6 行）

jar {
  from('../frontend/dist') {
    into 'static'
  }
}

jar.dependsOn(':frontend:assemble')

它把 frontend/dist 里的全部产物（index.html、main.js、vendors.js、styles.css）以 static 目录的形式塞进 Fat JAR。Spring Boot 启动后自动从 classpath:/static/ 提供静态资源，前端即刻可用。

三、生产环境启动 Fat JAR 的完整步骤

3.1 带 Profile 启动

java -jar -Dspring.profiles.active=production \
  backend/build/libs/boot-react-0.0.1-SNAPSHOT.jar

3.2 关于 Redis 会话（生产必读）⚠️

应用使用 Spring Session 持久化会话：

Profile	会话存储方式	建议场景
默认	内存 Map	仅开发环境
redis	真实 Redis 实例	生产环境（可水平扩展）

生产配置在 backend/src/main/resources/application.yml 中，官方建议通过环境变量注入 Redis 地址和密码，避免明文写在配置里。

四、SPA 路由不 404 的秘密：PushState 资源解析器

React Router 默认使用浏览器 history 模式（URL 形如 /login、/private）。开发环境由 dev server 兜底（见 frontend/server.js），而生产环境交给 SinglePageAppConfig 这个专门的资源处理器：

📄 源码：backend/src/main/java/react/config/SinglePageAppConfig.java

它的策略非常巧妙：

1. 请求路径带已知扩展名（js、css、png、json 等）→ 正常返回静态资源
2. 请求 /api 开头 → 交给 REST 接口处理
3. 其余一切路径 → 回退返回 index.html，交给前端路由接管

这样用户直接刷新 /private 这类页面也不会 404。如果你改用 hash 路由（/#/login），这个配置可以移除。

五、Docker 镜像部署（可选进阶）

不想裸跑 JAR？项目内置了 Docker 插件：

# 构建镜像
./gradlew backend:buildDocker

# 运行容器
docker run -p 8080:8080 boot-react/boot-react

根目录的 docker-compose.yml 则把应用和 Redis 一起编排，一条 docker-compose up -d 即可拉起完整生产栈。

六、常见问题排查清单 📋

现象	原因	解决
JAR 里没有前端资源	只跑了 backend:assemble，未触发前端构建	使用根目录 ./gradlew clean assemble
页面能打开但样式丢失	styles.css 未被抽取或路径错误	检查 webpack.config.js 的 ExtractTextPlugin 配置
刷新子路由 404	缺少 SPA 资源回退	确认 SinglePageAppConfig 未被移除
多实例部署会话丢失	会话存内存	启用 redis Profile 并配置真实 Redis

总结

boot-react 用极简的 Gradle 依赖链（jar → frontend:assemble → yarn bundle）实现了 React 资源一键打包进 Spring Boot Fat JAR 的完整生产链路，配合 SPA 资源回退和 Redis 会话，是一个非常适合学习和二开的全栈部署范本。克隆仓库（git clone https://gitcode.com/gh_mirrors/bo/boot-react）后，花 5 分钟通读 backend/build.gradle，你就能完全掌握这套打包机制。

【免费下载链接】boot-react A starter application with spring boot and react 项目地址: https://gitcode.com/gh_mirrors/bo/boot-react