1. 开局先理清JavaWeb项目到底要跑通哪些环节很多刚接触 JavaWeb 的同学第一个绕不过去的坎就是把工程在本地跑起来、能通过浏览器访问、再连上数据库。看起来流程不长但中间牵扯的环节实在不少项目结构、依赖管理、编译产物、Servlet 容器、Tomcat 生命周期、JDBC 驱动、数据库连接串。任何一个环节没对齐都会冒出一堆让人摸不着头脑的报错。这篇内容就是把这条链路完整串一遍从“建工程”到“部署到 Tomcat”再到“连接数据库”每一步都按实际操作来写。这篇内容适合这几类人看正在学 JavaWeb 的初学者、刚接手别人项目却跑不起来的同学、以及需要把老工程迁移到新环境的人。内容不堆概念只讲怎么落地。我会把操作步骤、配置文件、常见报错和排查思路全拆开讲。你跟着做完之后至少能自己搭一个“浏览器能访问、数据库能读写”的最小 Web 应用。做过一段时间 Java 开发的人都懂很多项目不是死在业务逻辑复杂而是死在“本地跑不起来”这个起点上。跑不起来的原因往往高度相似没有用构建工具、手动拷 jar 拷错位置、Tomcat 版本和 JDK 不匹配、数据库驱动没放进正确目录。这篇文章就是想把这些坑先填平。1.1 一个JavaWeb项目到底由什么构成从运行视角来看一个标准的 JavaWeb 工程最终会被打包成 war 包放入 Tomcat 的 webapps 目录。Tomcat 负责启动、监听端口、接收 HTTP 请求再把请求交给工程里的 Servlet 处理。工程内部包含这些典型内容编译后的 class 文件、静态资源、项目依赖的 jar 包以及 web.xml 这种描述文件。在没有 Maven 的年代维护这套结构全靠手工。开发时把用到的 jar 拷贝到WEB-INF/lib发布时用 IDE 导出 war 包。现在主流做法是用 Maven 管理依赖源码目录统一为src/main/java、src/main/resources、src/main/webapp。构建工具会自动收集依赖、编译源码、最终打包成可部署的 war。这里要建立一个关键认知Tomcat 不只是一个“服务端程序”它本质是 Servlet 容器核心能力是加载 Web 应用、管理请求线程、执行 Servlet 的生命周期方法。所以“部署”这个动作不是把源码复制到 Tomcat 目录就完事而是把编译后的产物按约定目录放好让容器能加载到。1.2 为什么很多教程跑不通我经常看到有人拿着网上的教程一步步做最后还是卡住原因主要有三类。第一依赖没有对齐。比如用了 Tomcat 10 却套用 Servlet 4 的代码包名从javax.servlet换成了jakarta.servlet这一步没改就直接编译报错。第二部署路径不对。有人把项目丢进 webapps却用错误的 URL 访问端口、上下文路径、Servlet 映射三个概念混在一起自然访问不到。第三代码编译都通过了运行时却抛ClassNotFoundException尤其是数据库驱动经常因为 jar 没有打进最终产物而消失。还有一种很隐蔽的情况Tomcat 版本和项目编译级别不匹配。比如用 JDK 17 编译出的 class放到仅支持 JDK 8 的 Tomcat 上运行会直接抛UnsupportedClassVersionError。这些问题的共性就是“环境不一致”。所以接下来的章节我会从环境准备一路讲到数据库连通把每一步的版本选择和路径规划都说清楚。2. 开发环境与工具版本不要让版本成为第一个坑做实际开发前先确认三样东西JDK、Tomcat、Maven。很多新手的第一行代码还没写就栽在版本排列组合上。你下载了最新版 JDK又下载了最新版 Tomcat结果某个类找不到翻遍代码也定位不了原因——因为问题根本不在代码而是版本错位。我的建议是基础 JavaWeb 项目不要追新。选一套“保守但足够用”的组合把所有精力放在理解运行链路上等流程跑通了想升级再升级。现在网上的教程和论坛讨论绝大多数都基于稳定版本你拿着新版本去适配会额外引入很多变量。2.1 建议的版本组合JDK如果使用 Tomcat 9选择 JDK 8 或 JDK 11 都合适。如果使用 Tomcat 10.1建议 JDK 11 以上。对于刚入门的人我推荐“JDK 8 Tomcat 9”这套经典组合。Tomcat下载 9.0.x 的 zip 压缩包不要用安装版。zip 解压即用卸载也简单还能直接观察目录结构。Maven3.6 或 3.8 系列足够用。在命令行确认mvn -version能正常执行这是后续打包部署的基础。数据库MySQL 5.7 或 8.0 都行。MySQL 8.0 需要注意时区和驱动类名变化文章后面会专门说明。为什么这么选因为大量示例代码默认跑在 Servlet 4.0 下的。如果你拿着新的容器去匹配旧代码又要把包名全部替换新手很难分清到底是代码问题还是环境问题。等基础链路打通再用新版本你才能准确判断差异点在哪。2.2 IDE与构建方式的选择逻辑IDE 方面入门用 Eclipse 的 Java EE 视图或者 IntelliJ IDEA 社区版都可以不用在这个环节纠结太多。关键是不要把 IDE 当成黑盒它只是帮你封装了“构建”和“部署”两个动作。你点一个 “Run on Server”背后其实发生了启动 Tomcat、部署上下文、监听端口等一系列操作。但真实生产环境不会有人帮你点这个按钮所以你必须亲手走一遍原始部署流程。如果 IDE 没有正规授权就用社区版或 Eclipse不要为激活问题分心。项目构建尽量用 Maven而不是 IDE 自带的项目格式。Maven 工程换电脑、换 IDE 都能快速导入依赖也不会散架。手动操作时最常打交道的四个命令是mvn clean、mvn compile、mvn package、mvn install前三个在部署里足够用。提示项目创建阶段先确认命令行能执行mvn -version。命令行可用后续就能自主完成打包、部署、手工验证不会被困在 IDE 的可视化按钮里。3. 保姆级创建流程从新建项目到能输出第一行响应这一章开始真正动手。我们用 Maven 新建一个基础 Web 工程然后挂到 Tomcat 上先不急着连数据库而是先把“浏览器能访问到一段文字”这个最小闭环打通。这一步通了后面数据库部分就只是“加配置、加代码”的事情。3.1 用 Maven 创建 Web 工程骨架如果你使用 IDEA可以在新建项目时选择“Maven”和“Web application”它会自动生成 webapp 目录。如果你更想感受工程结构是怎么来的可以手工用 Maven 命令生成mvn archetype:generate -DarchetypeGroupIdorg.apache.maven.archetypes -DarchetypeArtifactIdmaven-archetype-webapp -DgroupIdcom.demo -DartifactIdjavawab-demo -DinteractiveModefalse执行完成后会得到一个javawab-demo目录里面包含pom.xml、src/main/webapp/WEB-INF/web.xml和src/main/webapp/index.jsp。这就是最基础的 Web 工程骨架。生成的pom.xml里默认依赖很少没有 Servlet API。Servlet API 在编译阶段需要显式依赖但运行时由 Tomcat 提供所以 Maven 中要加scopeprovided/scope。这个作用域的意思是“编译时需要但打包时不要打进去”避免和 Tomcat 自带的 Servlet API 冲突。如果漏掉providedwar 包会同时携带一份 Servlet API很容易引发奇怪的兼容问题。3.2 补齐目录结构和基础文件手动创建src/main/java目录IDE 需要把该目录标记为 Sources Root否则写了代码也无法编译。再创建src/main/resources存放配置属性文件。还要创建src/main/webapp用来放静态页面和前端资源。标准 Maven Web 工程最后打包时会把编译后的 classes、webapp 下的资源、依赖 jar 全部聚合到 war 包中。web.xml是 JavaWeb 应用的核心描述文件。即使现在可以通过注解配置 Servlet新手也最好保留一份因为很多老工程、老文档仍然依赖它。一个最小的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 display-nameJavaWeb Demo/display-name /web-app3.3 写一个最简单的 Servlet 并编译打包创建HelloServlet让访问/hello时返回一段文字。这样可以验证“代码 - 编译 - 打包 - 容器加载 - HTTP响应”整条链路。我按 Tomcat 9 Servlet 4.0 写一版稳定代码package com.demo; import javax.servlet.ServletException; import javax.servlet.annotation.WebServlet; import javax.servlet.http.HttpServlet; import javax.servlet.http.HttpServletRequest; import javax.servlet.http.HttpServletResponse; import java.io.IOException; WebServlet(/hello) public class HelloServlet extends HttpServlet { Override protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException { resp.setContentType(text/plain;charsetUTF-8); resp.getWriter().write(hello from javawab); } }这里有最容易踩的差别javax和jakarta两个包名。Tomcat 9 及以前用javax.servletTomcat 10.1 开始改为jakarta.servlet。如果代码里发现 Servlet 相关的类无法导入先检查两件事Maven 依赖是否引入了 Servlet API、依赖版本是否与 Tomcat 匹配。在项目根目录执行打包mvn clean package正常情况下target 目录下会出现javawab-demo.war。这一步能通过说明依赖管理和编译链路没问题接下来就可以去部署了。3.4 在 IDE 里把项目挂到 Tomcat如果你是在 IDE 里调试最简单的方式是配置一个本地 Tomcat Server。IDEA 操作路径是Run - Edit Configurations - 添加 Tomcat Server - Local然后指定 Tomcat 安装目录在 Deployment 标签里添加当前项目选择 war exploded 或 war 都是可以的。war exploded 是展开目录形式开发阶段修改代码后不用反复打包体验更流畅。配置完成后启动浏览器访问http://localhost:8080/javawab-demo/hello看到自己写的那行文字最小项目就通了。如果启动时报Port 8080 is already in use说明端口被占用。你可以停掉占用进程也可以直接改 Tomcat 的server.xml端口。但改完端口后访问地址也要跟着变这一点要记得。4. 连接数据库的三条路径从 JDBC 直连到连接池Web 应用跑通后下一步就是连数据库。数据库连接不是“写几行 JDBC 代码”这么简单它涉及驱动坐标、连接串参数、classpath 路径、资源释放等问题。我会把这一整套拆开讲并给出一套稳定可靠的方案。4.1 先把数据库和账号准备好在写代码前先把数据库创建好。MySQL 中可以通过客户端执行create database demo_db default character set utf8mb4; create user demolocalhost identified by Demo12345; grant all privileges on demo_db.* to demolocalhost; flush privileges;这里建议不要直接用 root 账号跑业务代码。给应用单独建一个账号并只授权一个库是生产环境的通用习惯。万一代码里出现 SQL 注入问题破坏范围也只会限制在这个库内。数据库名采用utf8mb4字符集是为了兼容中文以及 emoji 字符。4.2 数据库驱动编译时和运行时是两回事以 MySQL 为例需要在 Maven 中引入mysql-connector-java依赖。这里有个重要区别5.x 驱动连接类名是com.mysql.jdbc.Driver8.x 驱动是com.mysql.cj.jdbc.Driver。如果你用 8.x 驱动却写 5.x 的类名代码能编译通过运行时直接抛ClassNotFoundException。在pom.xml中加入dependency groupIdmysql/groupId artifactIdmysql-connector-java/artifactId version8.0.33/version /dependency这个坐标默认会把驱动 jar 打进 war 包的WEB-INF/lib目录。如果你采用手动部署把驱动 jar 放到 Tomcat 的 lib 目录那么这个驱动会对所有应用可见。看起来省事但升级驱动时需要整个容器重启所以更多团队会选择让每个应用自包含依赖而不是共享公共目录。4.3 最直接的 JDBC 连接写法先把最朴素的 JDBC 写法跑通这能帮你理解数据库连接的完整过程。建议初学者先跑通这段代码再做封装package com.demo; import java.sql.Connection; import java.sql.DriverManager; import java.sql.ResultSet; import java.sql.Statement; public class JdbcDemo { public static void main(String[] args) throws Exception { Class.forName(com.mysql.cj.jdbc.Driver); String url jdbc:mysql://localhost:3306/demo_db?useUnicodetruecharacterEncodingutf8serverTimezoneAsia/Shanghai; String user demo; String password Demo12345; try (Connection conn DriverManager.getConnection(url, user, password); Statement stmt conn.createStatement(); ResultSet rs stmt.executeQuery(select 1)) { if (rs.next()) { System.out.println(连接成功: rs.getInt(1)); } } } }这里有两个新手必踩的坑。第一serverTimezone参数不配置MySQL 8.0 驱动会报时区错误。第二JDBC 4.0 之后驱动可以通过META-INF/services机制自动注册Class.forName实际上可以省略。但我建议还是写上它能帮助你感知类加载过程而且当你切换到老版本驱动时也不会出问题。4.4 别在 Servlet 里手写连接连接池的必要性上面的直连写法只适合测试不能直接用在 Servlet 里。如果每个请求到达时都用DriverManager新建连接那数据库很快就会被拖垮。因为每一次数据库连接都要经过 TCP 建立、身份认证、权限检查等多重开销高并发下毫无扩展性。所以真实项目会用连接池。连接池的职责是启动时预先创建一定数量的连接请求到来时从池里借用用完归还而不是销毁。这样连接可以被反复使用。目前主流方案包括 HikariCP、dbcp2 等。HikariCP 性能好、配置简单作为入门首选没问题。Maven 引入 HikariCPdependency groupIdcom.zaxxer/groupId artifactIdHikariCP/artifactId version4.0.3/version /dependency初始化数据源时要指定驱动、URL、用户名、密码并合理设置最大连接数。比如HikariConfig config new HikariConfig(); config.setDriverClassName(com.mysql.cj.jdbc.Driver); config.setJdbcUrl(jdbc:mysql://localhost:3306/demo_db?serverTimezoneAsia/Shanghai); config.setUsername(demo); config.setPassword(Demo12345); config.setMaximumPoolSize(10); DataSource dataSource new HikariDataSource(config);这里要特别注意maximumPoolSize不要盲目调大。连接池的数值超过了数据库本身的连接数上限等压力一上来数据库会在池外拒绝新连接。我见过不少项目把连接池调到 200结果 MySQL 默认最大连接数只有 151最终应用一片报错。4.5 用 JNDI 数据源让 Tomcat 管理连接另一种符合 JavaWeb 标准的做法是用 JNDI 数据源也就是把数据源配置放到 Tomcat 的context.xml或应用的META-INF/context.xml中。Tomcat 启动时负责创建连接池程序通过javax.naming.InitialContext查找获得DataSource实例。这样业务代码里不写数据库账号密码配置统一由容器管理。在项目目录src/main/webapp/META-INF/context.xml中写入?xml version1.0 encodingUTF-8? Context Resource namejdbc/demoDB authContainer typejavax.sql.DataSource maxTotal10 maxIdle5 usernamedemo passwordDemo12345 driverClassNamecom.mysql.cj.jdbc.Driver urljdbc:mysql://localhost:3306/demo_db?serverTimezoneAsia/Shanghai/ /Context代码中通过 JNDI 获取Context ctx new InitialContext(); DataSource ds (DataSource) ctx.lookup(java:/comp/env/jdbc/demoDB); try (Connection conn ds.getConnection()) { // 使用连接 }这里最常犯的错误是 JNDI 名称写错。Resource的 name 是jdbc/demoDB完整 lookup 路径必须带java:/comp/env/前缀。漏掉这个前缀就会抛NameNotFoundException。这类问题在初学阶段非常典型报错时先检查名称对应关系。5. 部署到 Tomcat 的实操细节与可视化验证很多人会在 IDE 里点启动一切正常但换成手动部署就手足无措。其实手动部署反而更直观把一个 war 包放到指定目录让 Tomcat 自己解压并加载。理解了这个过程你在任何环境下都能完成部署。5.1 三种常用部署路径对比第一种是 IDE 部署。开发阶段比较方便IDEA 会自动构建并启动 Tomcat适合频繁改代码的场景。第二种是直接把 war 文件复制到 Tomcat 的webapps目录。Tomcat 启动后会自动扫描到新的 war 包解压生成同名目录并加载。这种方式的优点是简单替换也方便适合手动部署和测试。第三种是修改server.xml通过Context docBase.../指定应用目录。这种方式适合应用目录不在 webapps 下的场景比如希望将应用和容器目录分离。对初学者来说第二种方式最能帮助你理解部署的本质。把 war 放进去然后通过 URL 访问如果能得到响应就说明整套部署机制已经通了。5.2 从 Maven 构建到部署的全流程结合前面创建的示例工程完整部署流程如下mvn clean package cp target/javawab-demo.war tomcat_home/webapps/ tomcat_home/bin/startup.shWindows 下的启动脚本是startup.bat。Tomcat 启动后webapps 目录下会自动出现javawab-demo/目录这是 Tomcat 自动解压 war 的结果。如果目录出现得慢不用太担心解压和初始化需要一点时间尤其是在首次启动时。访问地址的上下文路径默认就是 war 包文件名但不含.war后缀。所以完整访问地址是http://localhost:8080/javawab-demo/hello如果你想用根地址访问应用比如通过http://localhost:8080/直接到达首页可以把 war 包改名为ROOT.war。Tomcat 会把ROOT.war识别为根应用。这是很多后端接口项目为了简化 URL 而采用的常见操作。5.3 部署后如何验证接口和日志验证不要只盯着“页面有没有出来”而要看路径拼接是否正确。Servlet 的注解是/hellowar 包名是javawab-demo完整地址就是localhost:8080/javawab-demo/hello。如果你访问localhost:8080/hello大概率是 404因为这里少了上下文路径。遇到 404先分两层排查。第一层是 Tomcat 有没有启动成功启动成功的日志里会出现类似Server startup in [xxx] milliseconds这样的句子。第二层是应用有没有加载成功加载失败会在日志中留下异常堆栈。日志在 Windows 下一般直接滚动在启动窗口里Linux 下可以查看logs/catalina.outtail -f tomcat_home/logs/catalina.out看到异常后优先读堆栈第一行以及 “Caused by” 后面的信息。很多ClassNotFoundException并不是代码写错而是依赖没有真正放进 war 包。排查时可以打开 target 下的 war 文件检查WEB-INF/lib目录里是否存在对应的 jar。5.4 改代码后重新部署的操作要点IDE 开发模式下修改代码后热部署比较方便。但如果你改了web.xml、context.xml或依赖版本通常需要重启 Tomcat。很多新手改了一个常量后刷新页面没变化就怀疑浏览器缓存其实是应用没有重新加载。手动部署时更新 war 包的标准动作应该是先停掉 Tomcat清空 webapps 下对应的展开目录再替换成新的 war 包最后启动。为什么不能直接覆盖因为运行中的 Tomcat 可能正持有某个类或文件的句柄直接覆盖会导致新代码加载不完整出现各种诡异行为。宁可麻烦一点也要保持“停掉-清空-替换-启动”的节奏。提示开发调试阶段可以把 IDE 部署模式从 war 切换成 war exploded这样能省去反复打包的时间。但 war exploded 只适合开发环境生产部署永远要用完整的 war 包。5.5 在远程服务器上部署的额外检查项如果你要把项目部署到云服务器或公司测试机除了拷贝 war 包之外还要额外确认几个点。第一防火墙端口是否放行。第二数据库账号是否允许远程主机访问比如demo%。第三MySQL 的连接串要写成服务器的内网地址而不是 localhost。还有一个常见问题Tomcat 的启动脚本权限。在 Linux 上执行startup.sh时如果提示 Permission denied需要先给脚本加执行权限chmod x tomcat_home/bin/*.sh这些看起来是小细节但部署环境一旦切换问题形态就会从“代码报错”变成“网络不通”或“认证失败”排查维度一下子多出好几层。所以部署前把端口、账号授权、脚本权限三个点先检查一遍可以省下很多时间。6. 常见报错与排查思路把试错成本打下来这一章我把自己遇到过的、以及帮别人排查过的高频问题整理成速查表。很多报错实际上不是代码问题而是配置、依赖、路径、版本不对齐。遇到问题时先对照表格能少走很多弯路。6.1 高频问题速查表报错或现象最常见原因排查动作Port 8080 is already in use端口被占用或上次 Tomcat 没关干净查端口占用调整 server.xml 或结束旧进程ClassNotFoundException: com.mysql.cj.jdbc.Driver驱动依赖没引入或 jar 路径不对检查 war 包内 WEB-INF/lib 是否存在驱动 jarUnsupportedClassVersionErrorJDK 编译版本与 Tomcat 运行 JDK 不一致检查编译级别和java -version404 页面上下文路径写错、Servlet 映射未命中、应用未启动成功看 catalina.out再对比完整 URL数据库连接报时区错误MySQL 8.x 驱动需要显式serverTimezone连接串增加serverTimezoneAsia/ShanghaiNameNotFoundExceptionJNDI 名称不匹配或遗漏前缀检查java:/comp/env/jdbc/xxx前缀Access denied或Unknown database用户权限或库名拼写错误用数据库客户端先验证凭据和库名这张表不能替代读日志。遇到表格里没有的问题就先抓catalina.out里的异常堆栈。不要只盯第一行很多关键信息藏在Caused by后面尤其是多层嵌套的异常。6.2 我在实际部署中踩过的几个细节坑第一个坑是 Web 应用里的资源路径。JSP 或 HTML 页面中如果写死/css/style.css这种根路径在应用上下文不是/时资源会全部 404。最稳妥的做法是在 JSP 中用${pageContext.request.contextPath}拼接完整路径不要写死绝对路径。第二个坑是数据库连接对象没有关闭。如果你在 Java 7 以后用try-with-resources问题不大。但很多老项目用手写try/catch/finally最后忘了在 finally 里关闭Connection、Statement、ResultSet。连接池再大也会被这些忘记归还的连接耗尽。排查时看到数据库max_connections被打满先不要急着调连接池先看是不是存在连接泄漏。第三个坑是编码不一致。建项目时统一用 UTF-8如果启动 Tomcat 后页面显示乱码要依次排查server.xml里的 URIEncoding、JSP 页面头部是否声明 UTF-8、数据库连接的characterEncoding。三个地方只要有一处不一致就会出现中文乱码。第四个坑是 Tomcat 的“双启”。有时候你在 IDE 里点了一次启动又手动跑了一次 startup 脚本两个 Tomcat 进程同时抢 8080 端口。日志上表现为端口被占用但实际上是因为你忽略了同一个端口的另一份进程。遇到端口冲突时先杀掉所有 Tomcat 进程再重启这个顺序比直接改端口更符合排查逻辑。6.3 让排错过程可复现的一个小习惯我建议每个项目都写一份简短的部署说明文档内容包含 Tomcat 版本、JDK 版本、启动命令、访问地址、数据库连接串、war 包构建命令。别小看这个习惯它能让排错过程变得可复现。我在实际项目中见过太多人今天用一台电脑手动启动明天换 IDE 跑后天又改了端口最后报错了连自己都说不清楚是哪个环境出来的问题。排错的另一个思路是缩小范围。先判断是“应用没起来”还是“应用起来了但请求处理失败”。前者看启动日志后者看运行日志。只要把这两类问题分开大多数 JavaWeb 报错都能在短时间内定位。顺便说一句如果换了环境后项目突然跑不起来优先怀疑环境配置而不是业务代码。这种时候重新读一遍pom.xml、web.xml、context.xml往往比返工找代码逻辑更有效。我个人觉得JavaWeb 这条链路本身不难难的是把版本、路径、作用域这些隐含信息对齐。你只要按顺序把环境、创建、部署、数据库全部跑通一遍再回头去看任何 JavaWeb 框架的文档都会顺畅很多因为所有框架都是在这条链路上套了一层壳而已。唯一要做的就是把这个基础链路练到熟练踩过的坑才会真正变成你自己的经验。