将 Vue 项目打包并集成到后端 JAR 包中的完整教程

原创于 2025-10-08 08:04:48 发布 · 1.4k 阅读

16 ·

CC 4.0 BY-SA版权

文章标签：

#vue.js #jar #前端

前端专栏收录该内容

59 篇文章

订阅专栏

本教程将指导你如何将 Vue 前端项目打包并嵌入到 Spring Boot 后端项目的 JAR 包中，实现前后端一体部署。

一、前提条件

已有 Vue 前端项目和 Spring Boot 后端项目
Node.js 和 npm/yarn 已安装（用于 Vue 项目）
Java 和 Maven/Gradle 已安装（用于后端项目）
熟悉基本的 Vue 和 Spring Boot 开发

二、Vue 项目配置与打包

1. 配置 Vue 项目的公共路径

Vue 项目默认期望部署在网站根目录，如果你的 Vue 项目要放在后端静态资源目录下（通常是 / 或者自定义的路径），需要修改 vue.config.js 文件中的 publicPath。

步骤：

在 Vue 项目根目录下创建或编辑 vue.config.js 文件：

// vue.config.js
module.exports = {
  publicPath: './', // 使用相对路径，这样打包后的资源能正确加载
  outputDir: 'dist', // 打包输出目录，默认就是 dist，可保持不变
  assetsDir: 'static', // 可选：静态资源子目录，如 js, css, img 等会放在 dist/static 下
  indexPath: 'index.html', // 打包后的首页文件名，默认是 index.html
}

说明：

publicPath: './' 是关键，它让所有静态资源使用相对路径加载，这样在 JAR 包内也能正确找到 JS、CSS 等文件。
如果你的 Vue 路由使用了 history 模式，还需后端做相应配置支持（见后文）。

2. 打包 Vue 项目

在 Vue 项目根目录下运行以下命令进行打包：

npm run build
# 或者如果你使用 yarn
yarn build

打包成功后，会在项目根目录下生成一个 dist 文件夹，里面包含：

index.html：应用的入口 HTML 文件
static/ 文件夹：包含打包后的 JavaScript、CSS、图片等静态资源

三、将 Vue 打包结果集成到 Spring Boot 项目中

方案一：将 Vue 打包内容复制到 Spring Boot 的 `src/main/resources/static/` 目录（推荐）

这是最常见、最简单的集成方式，适合大多数前后端分离但希望最终打成一个 JAR 包的场景。

步骤：

在 Spring Boot 项目中创建静态资源目录（如果还没有）

Spring Boot 默认会从以下位置加载静态资源：
- classpath:/static/
- classpath:/public/
- classpath:/resources/
- classpath:/META-INF/resources/
我们推荐使用 src/main/resources/static/。

将 Vue 打包后的 dist 内容复制到 static 目录

你可以手动操作，也可以通过构建脚本自动完成。

手动方式：

将 Vue 项目打包后生成的 dist 文件夹中的所有内容（比如 index.html 和 static/ 文件夹）复制到 Spring Boot 项目的：
```
src/main/resources/static/
```
即把 index.html 和 static/ 直接放在 static/ 目录下，最终结构类似：
```
src/main/resources/static/
    index.html
    static/
        js/
        css/
        img/
```

自动方式（推荐）：使用 Maven/Gradle 插件或在构建时复制

以 Maven 为例，你可以使用 maven-resources-plugin 在打包前将 Vue 的 dist 内容拷贝到 target/classes/static/（即最终打包进 JAR 的静态资源位置）。

示例：在 pom.xml 中添加如下插件配置

<build>
    <plugins>
        <!-- 其他插件，如 spring-boot-maven-plugin -->
        <plugin>
            <artifactId>maven-resources-plugin</artifactId>
            <executions>
                <execution>
                    <id>copy-vue-resources</id>
                    <phase>generate-resources</phase>
                    <goals>
                        <goal>copy-resources</goal>
                    </goals>
                    <configuration>
                        <outputDirectory>${project.basedir}/src/main/resources/static</outputDirectory>
                        <resources>
                            <resource>
                                <directory>${project.basedir}/../your-vue-project/dist</directory>
                                <includes>
                                    <include>**/*</include>
                                </includes>
                            </resource>
                        </resources>
                    </configuration>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

注意：${project.basedir}/../your-vue-project/dist 是假设你的 Vue 项目与后端项目在同一个父目录下，根据你的项目结构调整路径。

更推荐的方式：使用脚本或 CI/CD 自动化拷贝，或者在开发时手动复制一次，后续打包时 Vue 的 dist 内容已经位于 src/main/resources/static/ 下。

确保 Spring Boot 能正确服务静态资源

Spring Boot 默认就会从 static/ 目录提供静态资源，无需额外配置。

如果你使用的是 Vue Router 的 history 模式，还需要配置一个 Fallback，确保刷新页面或直接访问某个路由时不会返回 404。

配置 Fallback（针对 Vue Router history 模式）：

如果你的 Vue 项目使用了 mode: 'history'，那么需要添加一个 Controller 来重定向所有前端路由到 index.html。

创建一个 Controller，例如：
```
@Controller
public class VueAppController {

    @RequestMapping(value = {"/", "/{path:[^\\.]*}"})
    public String forward() {
        return "forward:/index.html";
    }
}
```
这个配置会将所有不带文件后缀的请求（比如 /home, /user/1）都转发到 index.html，由 Vue Router 接管路由。

注意：
- 该 Controller 应放在能匹配所有前端路由的位置，但不要拦截 API 请求（比如以 /api/ 开头的）。
- 确保你的 API 路径与前端路由路径不会冲突，比如 API 用 /api/**，前端路由用其它路径。
重新打包后端项目

使用 Maven 或 Gradle 打包你的 Spring Boot 项目：
```
mvn clean package
```
打包成功后，你会在 target/ 目录下得到一个 JAR 文件，其中已经包含了 Vue 的静态资源。
运行并测试

运行 JAR 包：
```
java -jar your-application.jar
```
访问 http://localhost:8080/，你应该能看到 Vue 应用正常运行。

方案二：将 Vue 的 `dist` 文件夹内容打包到 JAR 的特定目录（灵活方案）

如果你不想将 Vue 文件直接放在 src/main/resources/static/，也可以选择在构建时将 Vue 打包内容拷贝到 target/classes/ 下的某个目录，或者使用 Maven/Gradle 插件自动处理。

这种方式本质与方案一类似，只是更灵活，适合复杂构建流程。

四、常见问题及解决方案

1. Vue 页面空白，JS/CSS 未加载？

检查浏览器开发者工具 Network 面板，查看 JS/CSS 是否 404。
确保 Vue 的 publicPath 设置为 './'，而不是 '/'。
确保打包后的 index.html 中引用的 JS/CSS 路径是相对路径，如 ./static/js/app.xxxx.js。
确保 Spring Boot 能正确访问 static/ 目录下的文件。

2. 刷新页面 404？

如果你用了 Vue Router 的 history 模式，必须配置 Fallback，将所有非 API、非静态资源的路径请求转发到 index.html。
确保没有其他 Controller 拦截了这些路径。

3. 如何区分 API 和前端路由？

通常约定 API 路径以 /api/ 开头，例如 /api/user。
前端路由为其他路径，如 /, /home, /about 等。
Spring Boot 中可通过 @RequestMapping("/api/**") 来处理 API，剩下的交给前端。

4. 打包时自动拷贝 Vue 文件（进阶）

可以使用 Maven/Gradle 插件，或者编写脚本，在每次构建后端之前/之后自动将 Vue 的 dist 拷贝到后端的 resources/static/ 目录。

例如使用 Maven 的 exec-maven-plugin 在打包前执行 npm build 并拷贝文件，但会增加构建复杂度，推荐手动或 CI 完成。

五、总结

步骤	操作内容
1	配置 Vue 项目的 `publicPath: './'`，执行 `npm run build` 打包
2	将 Vue 打包后的 `dist` 内容（`index.html` + `static/`）复制到 Spring Boot 的 `src/main/resources/static/` 目录
3	（可选）如果使用 Vue Router history 模式，添加一个通配 Controller 将所有非 API 路径请求转发到 `index.html`
4	打包 Spring Boot 项目为 JAR，运行测试