在不少传统企业项目中，后端一直跑在 WildFly（前身是 JBoss AS）上，而前端近年来逐步从 JSP、FreeMarker 迁移到了 Vue 3 这类现代框架。于是就产生了一个很现实的问题：Vue 3 的工程化产物，到底该怎么和 WildFX 这样的 Java 应用服务器结合起来？是把前端单独丢到 Nginx，还是直接打包进 WAR 一起发布？这篇文章就把整套方案捋清楚。
一、整体部署思路：合并部署还是分离部署
先说结论：两种方式都可行，选哪种取决于团队规模和运维习惯。分离部署指的是 Vue 3 单独构建，产物交给 Nginx 或 CDN，WildFly 只提供 REST 接口；合并部署则是把 Vue 3 的构建产物塞进后端 WAR 包的静态资源目录，随 Java 应用一起发布。
合并部署的最大好处是交付物只有一个 WAR，运维不需要维护两套发布流程，特别适合内网系统、管理后台这类对静态资源 CDN 要求不高的场景。缺点是每次前端改动都要重新打 WAR 包，构建链路变长。分离部署则相反，前端可以独立迭代、独立回滚，但需要额外维护一个静态服务器。
下面主要围绕合并部署展开，因为这是 WildFly 场景下最常见也最容易踩坑的方式。核心思路很简单：vite build 产出的 dist 目录，本质上就是一堆静态文件，只要放进 WAR 的 src/main/webapp 或者通过 Maven 插件拷贝进去，WildFly 内置的 Undertow 服务器就能直接伺服这些文件。
二、用 Maven 把 Vue 3 产物打包进 WAR
推荐的做法是让 Maven 在打包阶段自动执行前端构建，这样 CI 环境不需要单独配置 npm 命令。这里用到两个插件：frontend-maven-plugin 负责下载 Node 环境并执行构建，maven-war-plugin 负责把产物打进 WAR。
<plugin>
<groupId>com.github.eirslett</groupId>
<artifactId>frontend-maven-plugin</artifactId>
<version>1.15.0</version>
<configuration>
<workingDirectory>${project.basedir}/frontend</workingDirectory>
<installDirectory>target</installDirectory>
</configuration>
<executions>
<execution>
<id>install-node-and-npm</id>
<goals><goal>install-node-and-npm</goal></goals>
<configuration>
<nodeVersion>v20.11.0</nodeVersion>
</configuration>
</execution>
<execution>
<id>npm-install</id>
<goals><goal>npm</goal></goals>
<configuration>
<arguments>install</arguments>
</configuration>
</execution>
<execution>
<id>npm-build</id>
<goals><goal>npm</goal></goals>
<configuration>
<arguments>run build</arguments>
</configuration>
</execution>
</executions>
</plugin>
<plugin>
<artifactId>maven-war-plugin</artifactId>
<configuration>
<webResources>
<resource>
<directory>${project.basedir}/frontend/dist</directory>
<targetPath>/</targetPath>
</resource>
</webResources>
</configuration>
</plugin>
</plugin>注意目录结构：假设后端是一个标准的 Maven WAR 工程，前端代码放在 frontend 子目录里，两者共用一个 Git 仓库。构建时 frontend-maven-plugin 会在 target 目录下临时安装一份 Node，不影响系统环境，CI 机器上不需要预装 Node.js。
还有一个容易忽略的细节：Vue Router 如果用了 history 模式，直接打包部署后刷新页面会返回 404，因为 WildFly 收到的请求路径并不对应任何真实文件。解决办法是在 WAR 的 WEB-INF 下加一个 undertow-handlers.conf，内容只有一行：
not equals(%{RELATIVE_PATH}, /api) -> rewrite('/index.html')这行配置的含义是：除 /api 开头的请求外，其余全部重写到 index.html，交给前端路由接管。Undertow 的处理器表达式语法比较小众，写错了不会报明显错误，只是 rewrite 不生效，排查时可以直接看 WildFly 控制台输出的请求日志确认重写是否命中。
三、开发环境的跨域与联调配置
开发阶段不可能每次改一行代码都打一次 WAR，所以本地联调用的是 Vite 的开发服务器加代理。Vite 的 proxy 基于 http-proxy 实现，配置在 vite.config.js 中：
export default defineConfig({
server: {
port: 5173,
proxy: {
'/api': {
target: 'http://127.0.0.1:8080',
changeOrigin: true,
rewrite: (path) => path.replace(/^\/api/, '/api')
}
}
}
})这里的 target 指向本地启动的 WildFly，默认端口 8080。如果后端接口本身没有统一前缀，建议在 JAX-RS 应用上给所有接口加上 /api 前缀，这样代理规则写起来最简单，也不容易误把静态资源请求转发到后端。
另外一个方案是利用 Undertow 的 CORS 过滤器，直接允许开发端口跨域访问。但这种方式要求后端显式开启跨域头，生产环境如果忘了关会带来安全隐患，所以更推荐用代理方式，浏览器始终认为前后端同源，代码里不需要做任何特殊处理。
四、缓存策略与构建产物的版本管理
合并部署后，静态资源的缓存策略由 Undertow 控制。Vite 构建的产物文件名自带内容哈希，比如 index-a1b2c3.js，这类文件可以放心设置长缓存。而 index.html 本身不能缓存，否则发版后用户拿到的还是旧的入口文件，引用的还是旧版本 JS。
如果需要精细控制，可以在 WEB-INF/web.xml 里加一个过滤器，对 HTML 请求设置 Cache-Control: no-cache，对带哈希的资源设置较长的 max-age。更省事的做法是接受 Undertow 默认行为，配合文件名哈希机制，绝大多数场景已经够用。需要注意的是不要在 Undertow 层面对整个 WAR 开启 aggressive 缓存，否则 index.html 被缓存后排查起来非常痛苦。
最后总结一下选型建议：内网管理类系统、客户要求单一交付物的项目，用本文的合并部署方案，构建链路一次配好后非常省心；面向公网、迭代频繁的产品，还是建议 Vue 3 前端独立部署到 Nginx 或 CDN，WildFly 专心做业务服务，两边通过标准的 REST 接口通信，职责清晰也便于各自扩容。