52 lines
3.1 KiB
Markdown
52 lines
3.1 KiB
Markdown
# 前后端一体化构建与打包说明
|
||
|
||
本文档说明如何在 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 的标准命令，即可实现前后端一体化构建和打包运行。 |