简介本资源是一份面向Java Web开发初学者与中级工程师的Tomcat部署实战指南聚焦SpringBoot后端与Vue.js前端分离架构在传统Servlet容器中的落地难题。文档系统梳理了从JAR转WAR打包、Vue生产构建、Tomcat目录结构适配、Context路径配置、404路由重定向含WEB-INF/web.xml完整配置、跨域CORS解决方案等关键环节覆盖无Nginx环境下的全流程部署细节特别适用于政务系统、企业官网等需兼容Tomcat的政企级Web项目交付场景。资源为单文件Word文档.doc共1个文件大小72KB内容精炼、步骤明确、配置代码可直接复用。目前已有1456人学习下载读者可直接获取可运行的部署方案、常见报错如空白页、404、跨域拦截的定位逻辑与修复模板以及Tomcat与前后端协同工作的底层原理说明。1. Tomcat 部署 SpringBoot Vue为什么不用 Nginx 却要硬啃 web.xml 和 Context 配置你手头有个刚联调完的 SpringBoot Vue 项目前后端分离跑得飞起本地npm run servemvn spring-boot:run丝滑如德芙。但一到部署环节领导一句“就用公司现成的 Windows Tomcat别上新东西”你瞬间头皮发紧——SpringBoot 默认打 jar 包、Vue 路由是 history 模式、刷新 404、跨域报错、后台接口 404、前端静态资源找不到……全来了。这不是部署是闯关。这份文档不是教你怎么优雅上线而是告诉你当必须把 SpringBoot 打成 war、把 Vue dist 塞进 Tomcat、且不能加 Nginx 做反向代理时每一步配置背后的真实作用、不配会翻车的具体现象、以及为什么web.xml里那行error-page是 Vue history 路由在 Tomcat 上的唯一后悔药。它面向两类人一是被临时指派去维护老 Tomcat 环境的后端同学你得懂前端路由怎么兜底二是刚从 Vue CLI 脚手架跳出来、第一次直面Context path和docBase的前端同学你得知道npm run build出来的文件到底该往哪扔。全文不碰 Docker、不提云服务、不聊 Kubernetes只聚焦 Windows 下 Tomcat 9.x实测兼容 8.5这一条窄路所有操作均可离线复现所有配置项都带参数级解释。2. SpringBoot 打 WAR 包从内嵌容器到外置 Tomcat 的三步断舍离SpringBoot 默认以内嵌 Tomcat 启动打 jar 包即运行。但要塞进外部 Tomcat就得主动“卸载”内嵌容器让 SpringBoot 退化为一个标准 Servlet 应用。这不是简单改个 packaging而是涉及启动生命周期、Servlet 初始化、依赖冲突三重校验。常见误区是只改 pom 就打包结果部署后 404 或 500连日志都看不到——因为应用根本没初始化成功。2.1 修改 pom.xmlpackaging 排除内嵌 Tomcat 继承 SpringBootServletInitializer关键不是把packagingjar/packaging改成war而是整套配套动作。缺一不可!-- 1. 明确打包类型 -- packagingwar/packaging !-- 2. 排除内嵌 Tomcat否则会和外部 Tomcat 冲突 -- dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-tomcat/artifactId scopeprovided/scope !-- 注意必须是 provided -- /dependency /dependencies提示scopeprovided/scope是生死线。若漏写或写成compile打包时会把tomcat-embed-core打进 WAR外部 Tomcat 加载时因类加载器优先级问题直接抛java.lang.NoClassDefFoundError: javax/servlet/ServletContext或IllegalStateException: StandardEngine[Tomcat].StandardHost[localhost].StandardContext[] failed to start。这是新手踩坑率最高的点。2.2 主启动类继承 SpringBootServletInitializer 并重写 configure()SpringBoot 2.x 要求主类必须继承SpringBootServletInitializer否则外部 Tomcat 无法识别其为 Servlet 应用压根不会调用SpringApplication.run()// 假设你的主类叫 ProdApiApplication.java SpringBootApplication public class ProdApiApplication extends SpringBootServletInitializer { // 必须继承 Override protected SpringApplicationBuilder configure(SpringApplicationBuilder builder) { // 这行必须有告诉 Tomcat这个 WAR 的入口是这个类 return builder.sources(ProdApiApplication.class); } public static void main(String[] args) { SpringApplication.run(ProdApiApplication.class, args); } }逻辑说明configure()方法是 Tomcat 启动时扫描 WAR 的钩子。外部 Tomcat 在加载WEB-INF/web.xml或注解后会查找实现了ServletContainerInitializer的类而SpringBootServletInitializer正是为此设计。若没重写configure()Tomcat 认为这是个普通 WAR不会触发 SpringBoot 的自动配置你的RestController全部失效所有接口返回 404。2.3 Maven 打包验证检查 target 目录下的 WAR 结构执行mvn clean package -Dmaven.test.skiptrue后不要急着丢进 Tomcat。先解压target/prod-api.war确认三件事根目录下有WEB-INF/classes/里面应包含你编译后的.class文件如ProdApiApplication.classWEB-INF/lib/中没有tomcat-embed-*相关 jar如tomcat-embed-core-9.0.83.jar但应有spring-boot-starter-web-3.1.5.jar等业务依赖WEB-INF/web.xml可为空或不存在SpringBoot 2.0 默认无 web.xml靠注解驱动。参数说明-Dmaven.test.skiptrue是提速关键。单元测试在部署阶段无意义跳过可节省 60% 构建时间。若项目含集成测试如SpringBootTest建议改用-DskipTests跳过执行但保留编译避免因测试类路径污染导致 WAR 构建失败。3. Vue 项目构建与静态资源落位dist 目录不是终点而是 Tomcat 的起点Vue CLI 默认生成dist/目录但直接复制进去就完事错。dist/是前端构建产物而 Tomcat 是 Java Web 容器二者对“根路径”“路由解析”“资源定位”的理解天差地别。尤其 Vue Router 使用history模式时/user/profile这种 URL 在 Tomcat 看来就是个不存在的物理路径不干预必 404。这里的核心矛盾是Vue 的前端路由需要服务端兜底而 Tomcat 默认只认真实文件。3.1 Vue CLI 配置public/index.html 与 vue.config.js 的双重锚点确保vue.config.js中publicPath设置为/非./或空字符串否则构建后 JS/CSS 路径会错// vue.config.js module.exports { // 关键必须为 /表示所有静态资源从根路径加载 publicPath: /, // 若后端 API 地址不在同域需配置代理仅开发用生产环境由 Tomcat 处理 devServer: { proxy: { /api: { target: http://localhost:8080, // 开发时指向 SpringBoot changeOrigin: true, } } } }逻辑说明publicPath: /决定了index.html中script src/js/app.xxx.js的路径前缀。若设为./则生成script src./js/app.xxx.js在 Tomcat 的Context path/prod-api下浏览器会尝试请求http://ip:8080/prod-api/./js/app.xxx.js404。设为/则请求http://ip:8080/js/app.xxx.js路径正确。3.2 构建并校验 dist 内容三个文件一个都不能少执行npm run build后进入dist/目录必须存在index.html唯一 HTML 入口js/目录含app.xxx.js,chunk-vendors.xxx.jscss/目录含app.xxx.cssfavicon.ico可选但建议保留注意若dist/下还有index.html之外的.html如404.html请删除。Tomcat 的error-page机制只认web.xml中定义的location多出的 HTML 文件会被忽略徒增混乱。3.3 dist 目录落位策略绝对路径 vs 相对路径的取舍文档中提到docBasedist 的绝对路径但实际部署中强烈推荐使用相对路径。原因Windows 路径含空格或中文如C:\Program Files\Apache Software Foundation\Tomcat 9.0\webapps\dist会导致 Tomcat 解析失败日志报java.io.FileNotFoundException: ... (系统找不到指定的路径)。正确做法将dist/整体复制到webapps/下命名为prod-ui与后端 WAR 名prod-api.war区分然后在server.xml中写Context path/ docBaseprod-ui reloadabletrue crossContexttrue/参数说明path/表示访问http://ip:8080/即进入 Vue 前端docBaseprod-uiTomcat 自动在webapps/下查找prod-ui/目录无需写webapps/prod-uireloadabletrue开发期可热重载生产环境建议设为false提升性能crossContexttrue允许prod-api后端与prod-ui前端跨 Context 通信解决fetch(/api/user)被拦截问题。4. Tomcat 核心配置server.xml 与 web.xml 的协同救火机制光有 WAR 和 dist 不够Tomcat 的配置文件才是串联前后端的神经中枢。server.xml定义容器结构web.xml定义应用行为二者配合才能让 Vue 的 history 路由不崩、API 请求不跨域、404 有兜底。这里没有“默认配置”每一行 XML 都是针对具体问题的精准手术。4.1 server.xml 修改Host 节点下注入 Context绑定前端入口打开conf/server.xml找到Host namelocalhost appBasewebapps ...节点在其内部末尾添加Context path/ docBaseprod-ui reloadablefalse crossContexttrue/注意必须加在Host内部不能加在Engine或Server下path/表示此 Context 为默认应用用户访问根路径即命中若同时部署多个 Vue 项目可设path/admin则需通过http://ip:8080/admin/访问。4.2 web.xml 创建404 兜底的唯一合法方案在webapps/prod-ui/目录下新建文件夹WEB-INF/再在其中创建web.xml?xml version1.0 encodingUTF-8? web-app xmlnshttp://xmlns.jcp.org/xml/ns/javaee xmlns:xsihttp://www.w3.org/2001/XMLSchema-instance xsi:schemaLocationhttp://xmlns.jcp.org/xml/ns/javaee http://xmlns.jcp.org/xml/ns/javaee/web-app_4_0.xsd version4.0 metadata-completetrue display-nameVue Router Fallback/display-name error-page error-code404/error-code location/index.html/location /error-page /web-app逻辑说明这是 Vue history 模式的救命稻草。当用户直接访问http://ip:8080/user/profile时Tomcat 查找user/profile对应的物理文件找不到 → 触发 404 → 读取web.xml中的error-page→ 重定向到/index.html→ Vue Router 捕获 URL 并渲染对应组件。没有这一步任何非根路径的直接访问或刷新都会白屏。4.3 跨域问题的 Tomcat 层解法Filter 替代后端 CORS 注解文档提到“解决调用第三方 API 如百度地图 API 的跨域问题”。注意这是前端跨域即 Vue 页面中fetch(https://api.map.baidu.com/)被浏览器拦截。SpringBoot 的CrossOrigin对第三方域名无效它只管自己后端接口。真正解法是在 Tomcat 层加CorsFilter在webapps/prod-ui/WEB-INF/web.xml的web-app内error-page后添加filter filter-nameCorsFilter/filter-name filter-classorg.apache.catalina.filters.CorsFilter/filter-class init-param param-namecors.allowed.origins/param-name param-value*/param-value /init-param init-param param-namecors.support.credentials/param-name param-valuetrue/param-value /init-param /filter filter-mapping filter-nameCorsFilter/filter-name url-pattern/*/url-pattern /filter-mapping参数说明cors.allowed.origins*允许任意源生产环境应改为具体域名如https://your-domain.comcors.support.credentialstrue支持 Cookie 传递若百度地图 API 需登录态则必须开启。5. 避坑 / 常见问题 / 排查血泪经验总结的五条铁律部署过程中90% 的失败不是代码问题而是配置细节的微小偏差。以下五条均来自真实翻车现场按发生频率排序每条附带日志特征和秒级定位法。5.1 现象Tomcat 启动后访问http://localhost:8080/显示 Tomcat 默认首页而非 Vue 页面原因server.xml中Context的path/与 Tomcat 默认ROOT应用冲突。Tomcat 会优先加载webapps/ROOT/若存在则忽略其他path/的 Context。解决删除webapps/ROOT/目录或重命名确保prod-ui/是唯一的根路径应用。验证ls webapps/输出应不含ROOT。5.2 现象Vue 页面能打开但点击路由链接如/user后空白控制台报Failed to load resource: the server responded with a status of 404 ()原因web.xml中error-page的location路径错误。常见写成/dist/index.html或index.html缺/前缀。解决确认location值为/index.html绝对路径且index.html确实在prod-ui/根目录。验证直接浏览器访问http://localhost:8080/index.html应正常显示。5.3 现象SpringBoot 接口返回 404如http://localhost:8080/api/user报错但http://localhost:8080/prod-api/api/user可通原因server.xml中未设置crossContexttrue导致前端fetch(/api/user)发送到根路径而 SpringBoot 应用实际部署在/prod-api下。解决在Context标签中显式添加crossContexttrue并确保前端请求地址为/api/user而非http://localhost:8080/prod-api/api/user。验证查看浏览器 Network 面板请求 URL 应为http://localhost:8080/api/user。5.4 现象Tomcat 启动卡住日志末尾停在INFO [main] org.apache.catalina.startup.HostConfig.deployWAR Deploying web application archive [D:\tomcat\webapps\prod-api.war]原因prod-api.war中spring-boot-starter-tomcat未设为provided导致类加载冲突Tomcat 无限等待ServletContext初始化。解决解压prod-api.war检查WEB-INF/lib/是否含tomcat-embed-*jar。若有回退 pom 修改重新打包。验证启动时日志应出现INFO [main] org.springframework.boot.web.servlet.context.ServletWebServerApplicationContext: Root WebApplicationContext: initialization completed in XXX ms。5.5 现象Vue 页面打开后控制台报Uncaught SyntaxError: Unexpected token 且 Network 中 JS 文件返回 HTML 内容原因vue.config.js中publicPath设为./或导致index.html中引用的 JS 路径错误Tomcat 将错误路径解析为/js/app.xxx.js→ 404 → 触发web.xml的 404 重定向 → 返回index.html→ 浏览器尝试把 HTML 当 JS 解析。解决严格设publicPath: /并确认dist/index.html中script标签的src以/开头。验证查看dist/index.html源码搜索src确认所有路径为/js/xxx.js形式。6. 进阶验证与上线 checklist从本地调试到生产环境的七步闭环部署不是复制粘贴完就结束而是要建立一套可重复、可验证、可回滚的闭环流程。我给自己定的铁律是每次部署前必须在本地 Tomcat 完成七步验证缺一不可。这套流程已用于某高校教务系统迁移零线上事故。6.1 本地 Tomcat 环境准备最小化复现下载 Tomcat 9.0.83Windows zip 版解压至D:\tomcat清空webapps/目录保留webapps/ROOT/用于对比确保JAVA_HOME指向 JDK 17SpringBoot 3.x 要求启动bin/startup.bat访问http://localhost:8080/确认 Tomcat 首页正常。6.2 七步验证 checklist 表步骤操作预期结果失败定位点1. WAR 解压验证解压prod-api.war检查WEB-INF/classes/下有主类.class存在ProdApiApplication.classMaven 打包失败检查maven-compiler-plugin版本2. dist 结构验证检查prod-ui/下有index.html、js/、css/无多余.htmlindex.html在根目录npm run build命令执行异常检查vue.config.js3. Context 加载验证启动 Tomcat观察日志INFO [main] org.apache.catalina.core.StandardContext: Starting ...日志出现Starting Servlet web applicationserver.xml格式错误用 XML 验证工具检查4. 前端根路径验证访问http://localhost:8080/显示 Vue 首页Network 中index.html状态 200Context path/未生效检查webapps/ROOT/是否残留5. Vue 路由兜底验证访问http://localhost:8080/user/profile非首页路径页面正常渲染Network 中index.html状态 200web.xml的error-page未生效检查路径是否为/index.html6. 后端接口连通验证浏览器访问http://localhost:8080/api/ping假设后端有此接口返回{code:200,msg:ok}crossContexttrue缺失或后端 Controller 路径错误7. 第三方 API 跨域验证在 Vue 控制台执行fetch(https://api.map.baidu.com/location/ip?akxxx)返回 JSON 数据Network 中状态 200CorsFilter未启用检查web.xml中 filter-mapping 的url-pattern6.3 生产环境上线前的强制三动作关闭reloadable将server.xml中Context的reloadabletrue改为false避免热重载消耗 CPU移除WEB-INF/web.xml中的CorsFilter生产环境第三方 API 跨域应由 Nginx 或 CDN 处理Tomcat 层开启*有安全风险添加 JVM 参数优化在bin/catalina.bat的set JAVA_OPTS行后追加-Xms512m -Xmx1024m -XX:MetaspaceSize256m防止内存溢出。从那以后我每次部署 SpringBoot Vue 到 Tomcat都强制走一遍这七步验证。哪怕只是改了一行 CSS也要本地 Tomcat 过一遍——因为线上环境的 404 白屏从来不是代码写的错而是web.xml里少了一个/或是server.xml中多了一个空格。希望帮到你。本文还有配套的精品资源点击获取
