Vue 3 前端如何部署到 IBM WebSphere Liberty？工程化实践详解

在前后端分离的架构下，Vue 3 项目最终要经历一次从开发环境到生产环境的跨越。如果后端恰好选用了 IBM WebSphere Liberty，很多前端同学会立刻遇到一连串问题：打包产物放在哪里、路由刷新后 404 怎么办、接口请求跨域如何处理。Liberty 是一款轻量级的 Java 应用服务器，虽然它的定位是承载后端应用，但它内置了对静态资源托管的良好支持，只要配置得当，Vue 3 的构建产物完全可以和后端服务部署在同一个服务器实例中，省去额外搭建 Nginx 的工作量。

一、Liberty 托管静态资源的基本方式

WebSphere Liberty 采用卡带式架构，功能按 feature 拆分。要让 Liberty 正确提供静态文件服务，首先要理解它对 Web 应用的目录约定。一个标准的 WAR 应用结构中，src/main/webapp 目录下的文件会被直接作为静态资源输出，所以把 Vue 3 的构建产物放到这个目录，是最直接的集成方式。

具体操作上，先在本地执行构建命令，将生成的 dist 目录内容复制到后端项目的 webapp 目录下。更推荐的做法是利用前端构建插件的输出路径配置，直接让产物落到后端工程里。在 vite.config.ts 中可以这样指定输出目录：

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

export default defineConfig({
  plugins: [vue()],
  build: {
    // 输出到后端 Maven 工程的 webapp 目录
    outDir: '../backend-service/src/main/webapp',
    emptyOutDir: true
  }
})

这样每次执行 npm run build，前端产物就会自动进入后端工程的静态资源区域。需要注意的是 emptyOutDir 设为 true 会清空目标目录，因此不要把后端自己的文件放在同一目录下，建议在 webapp 下单独建一个 app 子目录来隔离前端产物，避免误删后端资源。

此外，Liberty 的 server.xml 中需要确认已启用 servlet 相关 feature，例如 <feature>servlet-4.0</feature> 或更高版本，静态资源服务由 Servlet 容器默认提供，无需额外配置，这一点比传统 WebSphere 简化了不少。

二、history 路由模式下的 404 问题与解决

Vue 3 项目使用 Vue Router 的 history 模式时，刷新非根路径页面会直接返回 404。原因是静态资源服务器只认文件路径，而 /user/list 这样的地址在服务器上并没有对应的物理文件。在 Nginx 中通常用 try_files 配置回退，Liberty 中的等价方案是在 web.xml 中配置一个欢迎文件与错误页的重定向逻辑。

最简单可靠的做法是注册一个 Servlet 转发器，把所有未匹配静态文件的请求都转发到 index.html。示例代码如下：

import java.io.IOException;
import javax.servlet.ServletException;
import javax.servlet.annotation.WebServlet;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

@WebServlet(urlPatterns = "/app/*")
public class SpaForwardServlet extends HttpServlet {
    @Override
    protected void doGet(HttpServletRequest req, HttpServletResponse resp)
            throws ServletException, IOException {
        // 将所有前端路由请求统一转发到 index.html
        req.getRequestDispatcher("/app/index.html").forward(req, resp);
    }
}

这个 Servlet 拦截 /app/* 路径下的所有 GET 请求。静态文件请求会优先由容器的默认 Servlet 处理，匹配不到的部分才落到这个转发器上，从而实现了与 Nginx try_files 类似的效果。如果项目没有 Java 代码也可以通过 web.xml 中的 servlet-mapping 达到同样目的。

另一个思路是直接使用 hash 模式路由，URL 中带 # 号，服务器永远只请求根路径，天然规避 404。但 hash 模式在 SEO 和 URL 美观度上有所欠缺，是否采用需要根据业务场景权衡。对于内部管理系统，hash 模式往往是性价比最高的选择。

三、接口跨域与开发生产环境的统一

开发阶段 Vue 3 的 dev server 运行在 localhost:5173，而后端 Liberty 服务通常跑在 9080 端口，直接请求必然跨域。Vite 的 proxy 配置可以很好解决这个问题：

export default defineConfig({
  server: {
    proxy: {
      '/api': {
        target: 'http://localhost:9080',
        changeOrigin: true
      }
    }
  }
})

进入生产环境后，前端与后端同属一个 Liberty 实例，请求天然同源，跨域问题自动消失。这也是把前端产物放进后端 WAR 的最大好处之一，省去了生产环境的 CORS 配置。但如果前后端必须分开部署，Liberty 同样可以通过 server.xml 中的 CORS 配置支持跨域访问：

<server>
  <featureManager>
    <feature>cors-1.1</feature>
  </featureManager>
  <cors domain="/api"
        allowedOrigins="http://frontend.ipipp.com"
        allowedMethods="GET, POST, PUT, DELETE"
        allowedHeaders="Content-Type, Authorization"
        allowCredentials="true"
        maxAge="3600"/>
</server>

启用 cors-1.1 feature 后，Liberty 会在响应头中自动加入 Access-Control-Allow-Origin 等字段，前端无需任何额外处理。值得注意的是 allowCredentials 为 true 时，allowedOrigins 不能写成通配符星号，必须明确列出允许的来源域名，这是实际部署中最容易踩的坑之一。

四、用 Maven 打通前后端的完整交付链路

手工复制 dist 目录到后端工程终归不够优雅，容易遗漏。工程化的做法是在后端项目的 pom.xml 中集成前端构建插件，让 Maven 在打包 WAR 时自动执行 npm 构建：

<plugin>
  <groupId>com.github.eirslett</groupId>
  <artifactId>frontend-maven-plugin</artifactId>
  <version>1.15.0</version>
  <configuration>
    <workingDirectory>../frontend</workingDirectory>
  </configuration>
  <executions>
    <execution>
      <id>install-node-and-npm</id>
      <goals><goal>install-node-and-npm</goal></goals>
    </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>

配合前文提到的 Vite 输出目录配置，一条 mvn package 命令就能完成前端安装依赖、构建、产物注入 WAR 的全部流程。这样 CI 流水线只需关注一个 Maven 工程，前端源码变更也会被版本管理与流水线统一覆盖，显著降低了团队协作中的遗漏风险。

总体而言，Vue 3 与 WebSphere Liberty 的结合并不复杂，核心就三件事：产物放置、路由回退、跨域策略。把这三点纳入项目脚手架固化下来，前后端的交付就会变成一条顺畅的流水线，而不是每次上线都要人工修补的琐事集合。

Vue 3WebSphere Liberty前端部署修改时间：2026-09-08 23:41:05