基于Spring Boot + Vue 3的前后端一体化部署方案

一、方案概述

1.1 方案背景

本项目采用前后端分离架构，前端使用Vue 3框架，后端使用Spring Boot。为简化部署流程、降低运维成本，本方案采用将Vue 3构建产物直接集成到Spring Boot静态资源目录中的一体化部署策略。

1.2 方案目标

部署简化：仅需部署一个可执行的JAR包，无需额外配置Web服务器
消除跨域：前后端同源访问，无需处理CORS问题
运维高效：降低部署门槛和运维复杂度

1.3 技术栈

组件	技术选型	版本要求
后端	Spring Boot	2.x / 3.x
前端	Vue 3 + Vue Router	Vue 3.x
构建工具（前端）	npm / yarn	-
构建工具（后端）	Maven / Gradle	-

二、部署架构

javascript 复制代码

┌─────────────────────────────────────────────────────┐
│                    用户浏览器                        │
└─────────────────────┬───────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────┐
│              Spring Boot 应用 (:8080)                │
│  ┌──────────────────────────────────────────────┐   │
│  │         静态资源 (static/)                   │   │
│  │  ┌─────────────────────────────────────┐   │   │
│  │  │  index.html                         │   │   │
│  │  │  css/  js/  assets/  ...            │   │   │
│  │  └─────────────────────────────────────┘   │   │
│  └──────────────────────────────────────────────┘   │
│  ┌──────────────────────────────────────────────┐   │
│  │          后端API接口 (/api/**)               │   │
│  └──────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────┘

说明：用户通过统一端口（默认8080）访问应用，前端页面和后端API共用同一域名和端口，不存在跨域问题。

三、构建与部署流程

3.1 前端构建

在Vue 3项目根目录下执行构建命令：

bash 复制代码

# 安装依赖（首次执行）
npm install

# 构建生产环境资源
npm run build

构建完成后，会在项目根目录生成 dist 文件夹，其目录结构示例如下：

bash 复制代码

dist/
├── index.html          # 入口页面
├── favicon.ico         # 网站图标
├── css/                # 样式文件
│   └── *.css
├── js/                 # JavaScript文件
│   └── *.js
└── assets/             # 其他静态资源（图片、字体等）
    └── ...

3.2 后端集成

步骤一：复制静态资源

将 dist 目录下的所有内容复制到Spring Boot项目的静态资源目录中：

csharp 复制代码

src/
└── main/
    └── resources/
        └── static/          # 如果没有该目录，请手动创建
            ├── index.html
            ├── css/
            ├── js/
            └── assets/

⚠️ 注意：请确保复制的是 dist 目录的内容，而非 dist 目录本身。例如，应直接将 index.html 放在 static/ 根目录下，而不是 static/dist/index.html。

步骤二：处理前端路由（仅限History模式）

如果Vue 3项目使用了 history 模式的路由，需要配置Spring Boot将所有前端路由请求转发到 index.html，否则直接访问子路径（如 /about）或刷新页面时会返回404。

方式一：Controller转发（推荐）

java 复制代码

import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.GetMapping;

@Controller
public class RouterController {

    /**
     * 将所有非静态资源的前端路由请求转发至 index.html
     * 匹配规则：路径中不包含 "."（用于区分静态资源文件）
     */
    @GetMapping(value = "/**/{path:[^\\.]*}")
    public String forwardToIndex() {
        return "forward:/index.html";
    }
}

方式二：WebMvcConfigurer配置

java 复制代码

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ViewControllerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

@Configuration
public class WebConfig implements WebMvcConfigurer {

    @Override
    public void addViewControllers(ViewControllerRegistry registry) {
        // 将根路径指向 index.html
        registry.addViewController("/").setViewName("forward:/index.html");
        // 其他非静态资源路径也可指向 index.html，但建议结合方式一统一处理
    }
}

方式三：使用Hash模式路由（规避方案）

如果不想增加后端配置，可以将Vue Router的模式改为 hash 模式（URL中带 #），该模式不会产生刷新404问题。但URL美观度会有所下降。

javascript 复制代码

// router/index.js
import { createRouter, createWebHashHistory } from 'vue-router'

const router = createRouter({
  history: createWebHashHistory(),  // 使用Hash模式
  routes: [...]
})

3.3 后端打包

使用Maven或Gradle构建可执行JAR包：

Maven：

bash 复制代码

mvn clean package

Gradle：

bash 复制代码

gradle build

构建产物（如 your-project-1.0.0.jar）将生成在 target/ 或 build/libs/ 目录下。

3.4 启动运行

bash 复制代码

java -jar your-project-1.0.0.jar

启动后，通过浏览器访问 http://localhost:8080 即可使用系统。

四、配置说明

4.1 静态资源配置（可选）

若需调整Spring Boot的静态资源路径，可在 application.yml 或 application.properties 中进行配置：

yaml 复制代码

# application.yml
spring:
  web:
    resources:
      static-locations: classpath:/static/          # 静态资源位置
      add-mappings: true                             # 启用默认映射
  mvc:
    static-path-pattern: /**                         # 静态资源访问路径

4.2 端口配置

yaml 复制代码

# application.yml
server:
  port: 8080                                         # 可根据实际需求修改

五、方案优缺点分析

维度	优点	缺点
部署	单JAR包部署，无需Nginx/额外服务器	前端更新需重新打包整个后端
运维	开箱即用，运维成本极低	无法单独更新前端静态资源
性能	适合中小规模访问	高并发下静态资源性能不如Nginx
开发	无跨域问题，前后端调试方便	前后端耦合，不适合大型团队并行开发
路由	可通过配置解决History模式问题	需额外代码处理前端路由转发

六、适用场景与建议

6.1 适用场景

✅ 中小型项目、内部管理系统、后台管理平台
✅ 个人项目或原型验证阶段
✅ 需要快速交付、一键部署的场景
✅ 前端页面较为简单，路由层级不多

6.2 不适用场景

❌ 大型企业级应用，前后端团队分离开发
❌ 前端页面访问量极大，对静态资源响应速度要求高
❌ 需要前端独立灰度发布、A/B测试等高级部署策略

6.3 升级建议

若未来项目规模扩大，可平滑迁移至以下方案：

独立部署：前端资源部署至Nginx或CDN，后端仅提供API服务，通过Nginx配置反向代理解决跨域。
容器化部署：前后端分别构建Docker镜像，通过Docker Compose或Kubernetes编排部署。

七、附录

7.1 Vue 3构建配置参考（vite.config.js）

javascript 复制代码

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

export default defineConfig({
  plugins: [vue()],
  base: '/',                    // 根路径，确保资源引用正确
  build: {
    outDir: 'dist',            // 输出目录
    assetsDir: 'assets'        // 静态资源子目录
  }
})

7.2 常见问题排查

问题现象	可能原因	解决方案
访问根路径显示空白	`index.html` 位置不正确	确认 `index.html` 是否在 `static/` 根目录下
刷新页面404	History模式下未配置路由转发	添加RouterController或改用Hash模式
CSS/JS资源404	资源路径错误	检查 `vite.config.js` 中的 `base` 配置
后端接口无法访问	接口路径被路由转发拦截	确保 `@GetMapping` 的匹配规则不拦截 `/api/**` 路径

文档版本 ：V1.0

编制日期 ：2026年8月

适用范围：Spring Boot + Vue 3 前后端一体化项目部署