将 Vue 3 前端工程与红帽 JBoss EAP 集成，是金融、政务、制造等行业中非常典型的架构需求。JBoss EAP 作为 Java EE 应用服务器，承载着核心业务接口和遗留系统，而 Vue 3 负责构建现代化的单页应用。两者之间的工程化协作并不是简单的静态托管，还涉及开发联调、安全认证、路由策略和部署形态等多方面决策。本文围绕 Vue 3 工程如何顺畅对接 EAP 展开，并给出经过验证的配置实践。
理解 Vue 3 与 JBoss EAP 的协作边界
在企业项目中，Vue 3 通常以纯前端工程的形式存在，由 Vite 或 Vue CLI 管理。构建后生成一组静态资源（index.html、JS、CSS、图片等），这些资源需要被某个 Web 服务器托管。JBoss EAP 本身基于 Undertow，具备静态资源服务能力，但它的强项是运行 Jakarta EE 应用，比如 EJB、JPA、JAX-RS。因此把 Vue 3 构建产物直接放入 EAP 虽然可行，但需要理解 EAP 的部署结构。
EAP 的默认欢迎页内容位于 standalone/deployments/ROOT.war 或者 welcome-content 目录。可以创建一个自定义 WAR 包或使用 Undertow 的静态资源处理器，将 Vue 3 的 dist 目录映射到上下文根。这样做的好处是同一个域名和端口下提供前后端服务，避免跨域配置，同时可以复用 EAP 的 HTTPS 和安全域。但缺点也明显：静态资源更新需要重新部署 WAR 或重启服务，与前端快速迭代节奏不匹配；EAP 对静态资源的缓存和压缩配置不如 Nginx 灵活。
因此更常见的工程化方案是开发环境通过代理联调，生产环境则将 Vue 3 静态资源部署在 Nginx 或 CDN 上，仅将 API 请求反向代理到 EAP。这样前后端解耦，各自独立扩缩容。但也不排除一些内网或单体交付场景需要将 Vue 打包进 EAP。我们需要根据实际约束选择。
开发环境使用 Vite 代理打通 EAP 接口
在开发阶段，Vue 3 前端运行在 localhost:5173，而 EAP 接口通常监听在 localhost:8080 或 8443。直接请求会产生跨域。Vite 提供了强大的 server.proxy 配置，可以将 /api 等前缀的请求转发到 EAP，同时保留 Cookie 和认证头。
// vite.config.js
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
export default defineConfig({
plugins: [vue()],
server: {
port: 5173,
proxy: {
'/api': {
target: 'http://localhost:8080',
changeOrigin: true,
secure: false,
rewrite: (path) => path.replace(/^\/api/, '')
},
'/auth': {
target: 'http://localhost:8080',
changeOrigin: true
}
}
}
})
其中 changeOrigin 会将 Host 头修改为目标地址，避免 EAP 因虚拟主机校验拒绝请求。如果 EAP 使用自签名证书，需要设置 secure: false。如果认证采用基于 Cookie 的 Session，代理会默认转发 Cookie，但要注意路径和域。
此外，可以在 .env.development 中维护 VITE_API_BASE 变量，结合 axios 的 baseURL 统一管理。开发时 baseURL 设为 /api，生产构建时替换为实际网关路径，这样避免硬编码。如果直接跨域访问 EAP，则需要在 EAP 中配置 CORS 过滤器或通过 Undertow 添加响应头，但开发阶段使用代理通常更简单。
生产部署：构建产物放入 JBoss EAP 的两种方式
第一种方式是将 Vue 3 的 dist 内容打包成 WAR 文件部署到 EAP。可以新建一个空的 Maven 工程，在 src/main/webapp 目录下放入构建产物，然后使用 maven-war-plugin 打成 WAR。部署到 EAP 后，静态资源由 Undertow 直接服务。这种方式的优点是统一了发布单元，适合单体应用交付，并且可以利用 EAP 的安全域和会话管理。
第二种方式是使用 Nginx 反向代理，静态资源由 Nginx 托管，API 请求转发到 EAP。下面是一个典型配置：
server {
listen 80;
server_name app.ipipp.com;
root /var/www/vue-app/dist;
index index.html;
location / {
try_files $uri $uri/ /index.html;
}
location /api/ {
proxy_pass http://127.0.0.1:8080/;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_cookie_path / /;
}
}
对比两种方式，EAP 内置托管适合小型单体交付、内网环境或需要统一安全域的场景；Nginx 方案更灵活，适合微服务和 CDN 加速。如果 Vue Router 使用 history 模式，直接部署到 EAP 时必须配置回退规则，否则刷新页面会返回 404。EAP 的 Undertow 可以通过 undertow-handlers.conf 或 web.xml 中的 error-page 将未知路径重定向到 index.html。
认证联调与 Vue Router 回退策略
在 EAP 安全域保护下的接口，前端需要处理 401、403 和登录跳转。Vue 3 中通常使用 axios 拦截器统一处理。以下示例展示了如何根据状态码触发路由跳转：
import axios from 'axios'
import router from '@/router'
const http = axios.create({
baseURL: import.meta.env.VITE_API_BASE || '/api',
withCredentials: true,
timeout: 10000
})
http.interceptors.response.use(
(response) => response,
(error) => {
if (error.response) {
const { status } = error.response
if (status === 401) {
router.push({ name: 'login', query: { redirect: router.currentRoute.value.fullPath } })
} else if (status === 403) {
console.warn('权限不足')
}
}
return Promise.reject(error)
}
)
export default http
withCredentials 确保跨域请求携带 Cookie，但需要 EAP 的 CORS 配置中允许 Access-Control-Allow-Credentials 并且不能使用通配符 Origin。如果生产环境前后端同域，则无需额外配置。Vue Router 的 history 模式在 EAP 中刷新 404 的解决办法包括配置 error-page 404 到 index.html，或者直接使用 hash 模式规避。hash 模式对 SEO 不友好，但对内网系统影响较小。
如果 EAP 启用了 CSRF 防护，Vue 需要从 Cookie 或响应头中读取 token，并在后续请求头中回传。可以在 axios 请求拦截器中统一添加 X-CSRF-TOKEN 头。这样可以保持前后端安全体系的一致。
总的来说，Vue 3 与 JBoss EAP 的工程化集成需要根据部署架构灵活选择。开发阶段用好 Vite 代理，生产环境结合 Nginx 或 WAR 部署，配合合理的认证与路由策略，才能让前后端协作顺畅，避免常见的跨域、刷新 404 和 Cookie 丢失等问题。