JavaProjectRepo/framework/docs/前后端整合.md

前后端一体化构建与打包说明

本文档说明如何在 Maven 构建流程中，先编译前端（pnpm），再编译后端（Java），并在 package 阶段将两者一起打包，使生成的可运行 jar/war 直接可以访问前端首页 index.html。

前置要求

• 已安装 JDK（推荐 17+）和 Maven（3.6.3+）。
• 已安装 Node.js（推荐 18+）与 pnpm（全局）：npm i -g pnpm。
• 当前项目结构：
  • 后端（Spring Boot）：app/pom.xml，源码在 app/src/main/java 与资源在 app/src/main/resources。
  • 前端（Vite/Vue）：位于 app/frontend，构建输出目录默认是 app/frontend/dist。

构建流程概览

在 pom.xml 中集成了以下步骤：

1. generate-resources 阶段：进入 frontend 目录，执行 pnpm install --frozen-lockfile 与 pnpm run build。
2. process-resources 阶段：将前端构建产物从 frontend/dist 复制到后端资源目录 src/main/resources/static。
3. 随后执行后端 Java 编译与打包，最终产出可运行的 jar/war。

这样在运行后端时，Spring Boot 会从类路径的 static 目录自动提供 index.html 作为欢迎页入口（访问根路径 / 即可看到前端页面）。

关键 POM 配置（摘要）

已经在 app/pom.xml 的 <build><plugins> 中加入：

• exec-maven-plugin：在 Java 编译前执行 pnpm 安装与构建。
• maven-resources-plugin：复制前端构建产物到 src/main/resources/static。

无需手动改动目录，只需按下述命令执行即可。

常用命令

• 开发运行（跳过测试）：mvn -DskipTests spring-boot:run
  • 如需指定开发配置：mvn -DskipTests -Dspring-boot.run.profiles=dev spring-boot:run
• 构建打包（跳过测试）：mvn -DskipTests package
  • 构建过程中会自动执行前端构建并拷贝到后端资源。

运行与访问

• 运行可执行包（以 war 为例，artifactId=platform，version=1.0）：
  • 默认运行：java -jar target/platform-1.0.war
  • 指定 dev 配置：java -Dspring.profiles.active=dev -jar target/platform-1.0.war
• 访问：
  • 若启用 dev 配置并端口为 8093：http://localhost:8093/
  • 若使用默认端口（例如 18080）：http://localhost:18080/

说明：Spring Boot 会自动将 classpath:/static/index.html 作为欢迎页，访问根路径即可进入前端入口页面。

注意事项

• 请确保 pnpm 可在构建机/开发机的环境变量中直接调用。
• 若前端构建输出目录（dist）有自定义，请同步更新 POM 中的复制路径。
• 如前端使用路由的 history 模式并期望后端兜底到 index.html，可按需添加后端控制器或使用前端服务器侧配置（当前方案以静态欢迎页为主）。

故障排查

• 构建失败（找不到 pnpm）：确认已安装并可在命令行执行 pnpm -v。
• 页面乱码：已在 POM 配置统一 JVM 编码为 UTF-8；在 Windows PowerShell 终端也应设置为 UTF-8。

完成上述配置后，只需使用 Maven 的标准命令，即可实现前后端一体化构建和打包运行。