企业官网建设流程全解析

前后端分离的项目做久了，总会遇到一个绕不开的问题：本地开发时前端跑在node服务上，后端跑在SpringBoot里，两边联调没问题，一到部署就头大。要么让运维去装Node环境、配Nginx、同时维护前端静态目录和后端jar包；要么开发自己手动打包传服务器，来回折腾。今天这篇就专门聊一个最省心的方案，把SpringBoot后端和Vue前端打包成一个jar文件，一个java -jar就全部跑起来，开发和部署两边都省事。

这套方案适合谁？主要是中小型团队和个人开发者，项目规模不需要几十个微服务同时扩容，一个jar包能扛住日常流量，又不需要单独申请一台机器专门挂Nginx。你只要会基本的Maven和Vue构建命令，照着下面的思路走，基本半小时内能搞定第一版合并包。我会把整个流程、关键配置、还有我踩过的坑都写出来，尽量让看过的人少走弯路。

1. 前后端分离项目为什么要合进一个jar包

先说说我自己的经历。之前接手过一个管理后台项目，前端是Vue2+ElementUI，后端是SpringBoot+MyBatis。最早部署的时候走的是标准前后端分离路线：前端npm run build产物丢到Nginx的html目录，后端打jar包单独用systemd托管，Nginx里做反向代理把/api开头的请求转发到后端端口。这套架构其实没毛病，问题出在维护成本上。

每次发版要同时更新两套东西，前端传静态文件要小心缓存，Nginx配置写错了整站白屏，后端jar更新还要重启服务，如果服务器上同时跑着三个环境，光配置文件就要来回切换。尤其是一个人负责多个项目的时候，这种两件套部署方式非常消耗精力。后来我给几个内部项目统一改成了前后端打进同一个jar的方案，部署就是传一个文件、跑一个命令，运维负担直接少了一大半。

1.1 分离开发、合并部署的取舍逻辑

这里要先说清楚一个概念：前后端代码合进一个jar，并不代表代码层面要耦合在一起。开发阶段依然是标准的前后端分离，前端用Vue CLI或者Vite起开发服务器，后端用SpringBoot的devtools热加载，两边各干各的。合并仅仅发生在构建阶段：把前端build出来的静态资源文件放进SpringBoot的classpath里，最终打成一个大jar，运行时由SpringBoot内置的Tomcat来托管这些静态文件。

说白了，这个方案牺牲的只是一点灵活性，换来的是部署模型的大幅简化。原来前端静态资源从磁盘路径读取，现在变成从classpath读取，对前端代码来说没有任何区别，因为浏览器拿到的还是同样的HTML、JS、CSS文件。对于不需要频繁独立扩容前端的项目，这种合并方式是最务实的。

1.2 什么场景不建议合并打包

当然，这个方案不是万能的。如果你的前端资源文件非常大，动辄几百MB，或者前端需要单独做CDN加速，再或者前后端团队分得很开、发版节奏完全不一致，那合并jar包反而会拖累你。比如前端三天小更新一次，后端一个月发一次版本，合并之后每一次前端改动都要重新打包整个后端jar，发布成本和风险都会上升。

另外，如果项目要跑多个实例做负载均衡，合并包会让所有实例的CPU都消耗在静态资源服务上，其实不太划算。这种情况下老老实实用Nginx或者OSS托管前端更合理。我在团队内部一般会给项目定个简单标准：单机部署、并发量不大、前后端发版周期接近的，优先考虑合并jar；超过这个范围再拆开部署。

2. 后端SpringBoot打包前的关键准备

后端侧要做的事情其实不多，但有几个细节值得提前确认，不然等到打包报错再去查会耽误很多时间。

2.1 确认Maven和JDK版本匹配

SpringBoot项目打包依赖Maven，这里最常见的问题就是Maven版本太老、JDK版本太新，两者不兼容导致编译都过不去。我之前遇到过JDK17搭配Maven 3.5的情况，编译时报"Unsupported major version"或者奇怪的依赖解析失败，最后把Maven升到3.8才解决。我的建议是JDK8用Maven 3.6.3以上，JDK11以上直接用Maven 3.8或者3.9，顺手把IDEA里Maven的JRE设置改成项目所用的JDK，别让它默认走IDEA自带的JBR。

在pom.xml里还要顺便检查一下spring-boot-starter-parent的版本。有些老项目用的SpringBoot 1.x，打包方式和新版本差别很大，如果执意要用新姿势，建议直接把SpringBoot升到2.5以上的稳定版本。版本号这东西宁稳勿新，除非你明确知道要踩某个新特性，否则不要一上来就冲最新版，我见过太多被SpringBoot 3.x+JDK17组合折磨到怀疑人生的案例。

2.2 spring-boot-maven-plugin需要单独配置吗

SpringBoot项目一般都会在pom.xml里引入spring-boot-starter-parent，这个parent自带spring-boot-maven-plugin的默认配置。但很多新手直接在pom里只放了starter依赖，忘了加build插件，结果打出来的jar根本不是可执行jar，要么直接双击没反应，要么命令行跑的时候报"no main manifest attribute"。

正确的做法是在pom.xml的build节点下显式声明插件，至少包含如下内容：

<build> <finalName>demo-project</finalName> <plugins> <plugin> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-maven-plugin</artifactId> <version>${spring-boot.version}</version> <executions> <execution> <goals> <goal>repackage</goal> </goals> </execution> </executions> </plugin> </plugins> </build>

这里finalName可以理解成最终jar包的名字，不配置的话默认是"项目名+版本号"，比如demo-0.0.1-SNAPSHOT.jar。有人觉得太长，想改成demo.jar或者按日期命名，都可以在这个标签里改。repackage这个goal是关键，它的作用是把普通jar重新加工成SpringBoot可执行jar，让内部的嵌套依赖能被识别加载，少了这一步打出来的jar会小很多，也跑不起来。

2.3 环境差异：开发、测试、生产配置怎么隔离

打包前还有一个容易忽略的问题：数据库地址、Redis地址这些配置在开发环境、测试环境、生产环境往往不一样。如果打包时把本地配置带进了生产环境，启动时就等着报连接超时吧。我的习惯是在application.yml里配一套默认值，然后不同环境用application-dev.yml、application-prod.yml来做覆盖，打包时通过启动参数指定profile，例如java -jar demo.jar --spring.profiles.active=prod。这样既能保证开发环境跑得起来，又能在生产环境一键切换，配置文件的维护也集中在后端工程里，不会出现jar包跟配置文件分离导致忘记更新配置的情况。

3. 前端Vue项目的构建配置调整

后端准备工作做完，接下来要动的是前端。很多人在这个环节踩坑，核心原因是没搞懂Vue构建出来的资源默认为什么访问不到。

3.1 publicPath必须设置为相对路径

Vue CLI构建时默认的publicPath是/，这意味着打包出来的HTML里引用的JS、CSS路径都是以根路径开头的，比如/assets/index.xx.js。以前端静态资源放在Nginx根目录下的架构，这个默认值没毛病。但现在静态资源要从jar包里访问，SpringBoot默认的context-path是/，静态资源挂在classpath:/static/下，如果部署的URL路径不是恰好对应根路径，比如你通过http://ip:8080/访问，那没问题；但如果你后面还有一层网关或者路径前缀，比如http://ip:port/myapp/，那默认的绝对路径就会失效，页面白屏，控制台报一堆资源404。

解决办法是把Vue的publicPath改成相对路径"./"。以Vue CLI为例，在vue.config.js里这样设置：

const { defineConfig } = require('@vue/cli-service') module.exports = defineConfig({ publicPath: './', outputDir: 'dist', assetsDir: 'static' })

publicPath设置成./之后，构建出来的HTML会使用相对路径引用JS和CSS，这样无论jar部署在什么子路径下，资源都能按当前位置找到。Vite项目对应的是base配置项，同样设置成'./'即可。

3.2 history路由模式会带来什么麻烦

Vue Router默认是hash模式，URL里带#号，比如http://ip:8080/#/user。这个模式在合并jar包方案里是最稳妥的，因为它不依赖后端做history fallback。如果你用了history模式，URL变成http://ip:8080/user，浏览器直接访问这个地址时，请求会打到SpringBoot，而SpringBoot的DispatcherServlet只认自己映射的接口，不认识的路径就返回404。除非你额外写一个转发控制器或者配置errorPage把未知路径全部转发到index.html，否则在合并jar包里用history模式基本就是自找麻烦。

如果确实想用history模式，可以在SpringBoot里加一个简单的转发配置，但我觉得大多数内部系统完全没必要追求这种URL美观，hash模式够用且省心。你只需要在router的创建代码里确保没有强制history模式即可。

3.3 开发环境的跨域代理不会影响打包

开发时前端调用后端接口通常靠Webpack的proxy解决跨域，比如vue.config.js里的devServer.proxy。这块很多人打包时会担心：打出来的包还带不带代理？答案是根本不相关。proxy只作用于本地开发服务器，构建产物里的接口请求地址是写在静态JS里的真实URL。如果你在代码里写的是/api/login这种相对路径，部署后请求会自动发到当前域名和端口下，正好匹配SpringBoot的接口路径，这是推荐做法；如果你开发时写的是http://localhost:8081这种绝对地址，打包后请求还是会指向localhost，部署到服务器后就会出问题。

我在实际项目里一般统一要求前端调用接口时使用相对路径/api/xx，然后开发环境的proxy把它转发到后端8080端口，生产环境合并jar后相对路径自然命中后端接口，两边都不用改代码。这是前端项目进阶时必须建立的好习惯。

4. 把前端构建产物整合进SpringBoot工程

前端build完之后，产出的是dist目录，里面有个index.html和一堆静态资源。现在需要把这些文件搬到SpringBoot能访问到的地方。

4.1 落实拷贝动作：资源目录与手动步骤

SpringBoot默认会从classpath下的static目录读取静态资源，所以最粗暴的方式就是手动把dist里的内容复制到src/main/resources/static/下面。比如把dist/index.html、static/js等文件直接拷贝过去，然后重新打包。这种方式直观，但有个致命问题：每次前端改动都要手动拷贝，容易漏文件、容易带上旧文件，而且那些打包出来的哈希文件名每次都在变，手动维护很容易出错。

更稳的方案是让Maven在构建时自动把前端dist目录里的文件复制到打包产物中。思路是这样：前端构建在前，后端打包含在后，通过maven-resources-plugin或者frontend-maven-plugin把前端构建这一步也纳管进来。如果你不想引入太多插件，可以先用npm run build在本地或者CI里执行，然后让Maven打包时把dist目录作为资源目录合并进去：

<build> <resources> <resource> <directory>src/main/resources</directory> </resource> <resource> <directory>../frontend/dist</directory> <targetPath>static</targetPath> </resource> </resources> </build>

这段配置的意思是把前端dist目录里的内容放置到classpath的static目录下，SpringBoot启动后自动就能托管这些文件。注意里的路径要按你前端工程的实际位置调整，比如前端和后端是平级目录，那路径就是../frontend/dist；如果前端目录就在后端工程内，就写成src/main/webapp/dist之类的相对路径。

4.2 静态资源优先级与后端接口冲突问题

把前端资源放进static后，SpringBoot的静态资源映射和Controller接口可能存在路径冲突。假如你有个接口路径是/index，同时前端也产出了一个index.html，那么访问/index时到底走接口还是静态文件？SpringBoot的处理顺序是Controller优先于静态资源，所以接口会被命中，静态文件只有在没有对应Controller的情况下才会被处理。大多数情况下这种冲突不太会出现，但你得心里有数，避免后端把/api之外的路径占得太满，导致前端页面无法正常访问。

另外，如果项目里配置了WebMvcConfigurer去自定义资源映射，记得保留SpringBoot默认的多个资源位置，别偷懒只写一个static，否则classpath下的其他静态文件可能会404。比如：

@Configuration public class WebConfig implements WebMvcConfigurer { @Override public void addResourceHandlers(ResourceHandlerRegistry registry) { registry.addResourceHandler("/**") .addResourceLocations("classpath:/static/", "classpath:/public/"); } }

这里一般不需要额外写，除非你有特殊需求。SpringBoot默认的静态资源位置包括classpath:/static/、classpath:/public/、classpath:/resources/等，默认情况下dist里的文件放在static目录下就够了。

4.3 前后端时间戳版本管理的小技巧

合并打包后，浏览器缓存是个必须处理的问题。Vue构建出来的文件名自带hash，比如app.8f3b2a.js，所以只要文件内容变了，文件名就会变，不用担心缓存问题。但index.html本身如果没有禁用缓存，浏览器可能短时间缓存住旧的html，进而引用旧的资源文件名，导致页面加载失败。处理方式很简单，在SpringBoot里给index.html设置Cache-Control: no-cache，或者在前端项目的public目录里加一个meta标签禁止缓存。我个人习惯在服务器层或者SpringBoot过滤器里统一处理，核心思路是保证html每次都回源校验，静态资源靠hash文件名自然缓存。

5. 完整打包与运行实录

配置都准备好了，实际操作其实就几步。我把从构建到运行的完整流程按顺序过一遍，每一步会说明我通常会怎么做、可能出现什么问题。

5.1 前端构建命令与产物检查

进入前端工程目录，先执行依赖安装：

npm install

这里要注意，如果你的项目node_modules之前装过，且package.json没有变化，可以跳过install直接build。但换了机器、切了分支，最好还是重新install，避免依赖缺失或者版本错乱。接着执行构建：

npm run build

构建完成后检查dist目录，确认其中包含index.html和static/js、static/css等子目录。我习惯用ls -l看一下dist目录的文件大小，如果index.html只有几KB、js/css文件夹齐全，那基本没问题。如果dist目录是空的，或者只有一堆map文件，多半是构建报错或者配置有误，回到控制台看构建日志。

5.2 Maven打包的两种方式

后端打包可以用IDEA的Maven面板双击package，也可以直接用命令行：

mvn clean package -DskipTests

-DskipTests是跳过测试，很多人打包失败就是因为测试类里连了数据库或者依赖外部服务，在打包环境里跑不通。如果你希望测试代码编译但不执行，用-Dmaven.test.skip=true更彻底，它会连测试代码都不编译，速度更快。我一般本地打包用skipTests，CI上才跑完整测试。

打出来的jar在target目录下，名字取决于前面配置的finalName，比如demo-project.jar。你可以用压缩工具打开这个jar看一眼，里面应该包含BOOT-INF/classes/static/index.html以及BOOT-INF/lib下的一堆依赖jar，确认无误后就说明前端资源已经合并进去了。

5.3 java -jar运行与启动参数

运行合并包最简单的方式就是：

java -jar demo-project.jar

如果你的服务器上同时部署了多个Java应用，端口可能冲突。SpringBoot默认是8080端口，冲突时启动日志会直接报"Port already in use"。解决办法是指定端口运行：

java -jar demo-project.jar --server.port=9090

也可以把端口写到application.yml里统一管理。如果要用生产配置，再加一个profile参数：

java -jar demo-project.jar --spring.profiles.active=prod

启动日志里看到"Tomcat started on port 9090"以及包含前后端接口的启动信息后，打开浏览器访问http://ip:9090，如果能看到前端页面并且登录接口正常，说明整个合并打包流程跑通了。

5.4 使用脚本简化启动与停止

每次手动敲java -jar还是太原始，我习惯写一个简单的启停脚本放在jar包旁边，比如start.sh内容大致是：

#!/bin/bash nohup java -Xms256m -Xmx512m -jar demo-project.jar \ --spring.profiles.active=prod \ --server.port=9090 > app.log 2>&1 & echo $! > app.pid

停止脚本stop.sh就是读取pid再kill，这种脚本虽然简单，但对日常运维来说足够可靠。生产服务器上还可以配合systemd托管，这里不展开，但思路就是让Java进程变成一个可控的系统服务，崩溃自动重启。

6. 常见问题排查与避坑经验

合并打包的思路本身就容易踩坑，我从实际项目里整理了几个高频问题，基本覆盖了最常见的翻车场景。

6.1 前端页面白屏：资源路径与history路由

页面白屏是合并包方案里出现频率最高的问题。排查步骤我一般按顺序来：

1. 浏览器F12打开控制台，看Network面板里哪些资源请求失败。如果JS、CSS都是404，那基本是publicPath问题，检查vue.config.js里的publicPath是否为./，重新构建再试。
2. 如果页面能加载但路由页面是空白的，可能是Vue Router用了history模式，直接改成hash模式，或者在SpringBoot里做转发处理。
3. 再看控制台有没有明显的JS报错，比如某个全局变量找不到，这种情况一般是环境变量注入没做好，检查前端代码里用到的VUE_APP_开头的变量是否在构建时已经生效。

6.2 接口404：context-path与接口前缀不一致

合并后接口404一般是两种情况。一是后端改了context-path，比如配置了server.servlet.context-path=/api，而前端请求用的还是根路径，那所有接口都会404。这种情况要么前端请求统一加前缀，要么把context-path去掉，让接口保持在根路径下。二是前后端对接口路径的约定不一致，比如前端请求/api/user/list，后端Controller实际映射的路径是/user/list，开发时靠proxy转发所以没暴露，合并后没有proxy，自然就404了。我的建议是尽早统一接口前缀规范，至少保证在开发环境和生产环境路径语义一致。

6.3 启动报错：端口被占用、内存不足、JDK版本不匹配

启动jar时最常遇到三个问题：

• 端口占用：SprintBoot启动日志提示端口被占用，要么换端口，要么找到占用进程杀掉。Linux下可以用lsof -i:8080定位到占用的进程，确认不是重要服务再kill。
• 内存不足：jar包启动直接OOM，可以调大JVM堆内存，前面脚本里的-Xms和-Xmx参数就是干这个的，一般给512MB到1GB足够跑中小型项目。
• 高版本JDK不兼容低版本SpringBoot：老项目用SpringBoot 2.0以下配合JDK17，很可能启动时直接抛UnsupportedClassVersionError或者依赖注入异常。这种情况优先升级SpringBoot版本，别硬扛。

6.4 修改前端代码后没生效：缓存、构建产物、manifest问题

这个坑很隐蔽，很多人明明改了前端代码，重新构建也成功了，但浏览器访问还是老页面。原因基本是浏览器缓存了之前的index.html。解决办法除了前面说的给index.html加no-cache，还可以在地址栏强制刷新，或者用无痕窗口测试。另外排查一下dist目录里的index.html资源引用路径是否已经变化，如果文件名和之前一样，说明构建可能没有真正重新生成，先把dist目录删掉再build。

还有一个容易忽略的点：有些前端工程用了PWA插件或者Service Worker，构建产物的sw.js会对页面做离线缓存，导致无论怎么部署都显示旧版本。遇到这种情况，检查public目录下是否有service-worker相关配置，PWA引入复杂，大多数管理系统根本不需要，直接去掉即可。

6.5 使用Process Explorer排查jar包内部结构

如果你怀疑jar包里前端资源没打进去，或者某个依赖缺失，可以用压缩工具打开jar检查BOOT-INF/classes目录下的文件结构。常见工具比如7-Zip、WinRAR都能直接打开jar包看目录树。如果静态文件确实都在，但访问还是404，那就要看SpringBoot的资源映射配置是不是出了问题，或者确认你的访问路径是否带上了上下文前缀。这个过程不复杂，养成检查jar包内部结构的习惯，能帮你快速判断问题是出在打包阶段还是运行阶段。

7. 打包后的运维部署经验

真正把jar包跑起来只是第一步，能不能稳定运行才是关键。我再来分享一些部署层面比较务实的经验，这些在官方文档里很难找到现成答案。

7.1 日志输出与排查

nohup方式启动的话，日志都写进app.log。运行久了日志文件会特别大，我一般会在启动脚本里加上按天切割的JVM参数，或者在应用里配置logback的滚动策略。SpringBoot自带的logging配置可以做到按大小切割：

logging: file: name: logs/app.log logback: rollingpolicy: max-file-size: 10MB max-history: 30

这样日志单文件超过10MB会自动归档，最多保留30份，不至于把磁盘撑爆。排查生产问题时，先看启动日志有没有异常堆栈，再看近期日志里的WARN和ERROR，大多数问题都能定位到方向。

7.2 配置文件外置化

虽然我们把前后端代码合并成了一个jar，但配置最好还是留在jar外面，不然每次改数据库密码都要重新打包。SpringBoot支持外部配置优先的机制，你只需要在jar包相同目录下放一个application.yml，这个文件会覆盖jar内部的同名配置。启动命令不需要额外参数，SpringBoot自动扫描当前目录的config目录和当前目录的application.yml。需要改端口或者数据库地址，直接编辑外部配置文件，然后重启应用，不用动jar包本体。

7.3 监控与健康检查

合并jar包的方案虽然简单，但该做的监控不能缺。SpringBoot自带的Actuator可以暴露健康检查接口，加个依赖就能用。对于单机部署的项目，我会定期用curl请求health接口并把结果写到监控系统，接口不通就告警。这样即使没有复杂的K8s环境，也能保证问题发生时第一时间知道。

如果你担心jar包被杀掉或者服务器重启后服务没起来，可以在crontab里加一条简单的进程守护，每分钟检查一次进程是否存在，不存在就重新nohup启动。虽然粗糙，但对小团队来说比引入一套完整的进程管理器要划算得多。

说起来，这套"前后端打成一个jar"的方案我自己已经带过好几个项目落地，每次都能把部署时间从半小时压缩到几分钟。它不是什么高深技术，但只要把Maven资源拷贝、前端相对路径、静态资源位置这三件事想明白，剩下的就是水到渠成。你现在就可以打开手头的项目试一下，第一次跑通了，后面就会觉得部署原来真的可以这么简单。