Java Web 开发环境配置笔记（基于 Servlet + Tomcat + Thymeleaf）

本笔记整理自项目实战文档，涵盖 JDK、Tomcat、IDEA、MySQL 及各类依赖库的完整配置，适用于 Servlet + JSP + Thymeleaf + JDBC 的传统 Java Web 开发。

一、基础软件安装

二、JDK 环境配置

1. 安装 JDK

• 下载 Oracle JDK 或 OpenJDK，安装路径建议无中文、无空格，例如 C:\Java\jdk-17

2. 配置环境变量

提示：在命令行执行 java -version 验证安装成功。

三、Tomcat 服务器配置

1. 下载与解压

• 官网：https://tomcat.apache.org
• 建议下载 10.1.x 版本（对应 Jakarta EE 10，支持 jakarta.* 包）
• 解压到无中文路径，例如 C:\apache-tomcat-10.1.48

2. 配置环境变量

验证：在命令行执行 startup.bat，浏览器访问 http://localhost:8080 出现 Tomcat 首页即成功。

3. 修改端口（可选）

• 编辑 conf/server.xml，找到 <Connector port="8080" .../>，修改为其他端口（如 80 或 8888）

4. 解决控制台日志乱码（重要）

• 编辑 conf/logging.properties，将 java.util.logging.ConsoleHandler.encoding 从 UTF-8 改为 GBK（Windows 默认编码），或保持 UTF-8 但配合 IDEA VM options。
• 推荐方案：保持 logging.properties 为 UTF-8，在 IDEA 的 Tomcat 运行配置中添加 VM options：

  -Dstdout.encoding=UTF-8
  -Dfile.encoding=UTF-8
  

  如下图位置：

5. 配置 Tomcat 用户（用于 Manager 等）

• 编辑 conf/tomcat-users.xml，添加：

  <role rolename="manager-gui"/>
  <role rolename="admin-gui"/>
  <user username="admin" password="yourpass" roles="manager-gui,admin-gui"/>
  

四、IDEA 开发环境配置

1. 全局编码设置

• File → Settings → Editor → File Encodings
  • Global Encoding: UTF-8
  • Project Encoding: UTF-8
  • Default encoding for properties files: UTF-8
  • 勾选 Transparent native-to-ascii conversion

2. 配置 JDK

• File → Project Structure → SDKs → 添加本地 JDK 路径

3. 集成 Tomcat

• Run → Edit Configurations → Add New → Tomcat Server → Local
• 选择 Tomcat 安装目录，设置 HTTP 端口（默认 8080），JMX 端口（默认 1099）
• Deployment 选项卡：添加 Artifact（war exploded），设置 Application Context（如 / 或项目名）

4. 创建 Web 项目模块

• 新建 Java 模块 → 右键模块 → Add Framework Support → 勾选 Web Application（选择 Jakarta EE 版本，如 6.0）
• 目录结构：

  webapp/
    WEB-INF/
      web.xml
      lib/          （第三方 jar）
      classes/      （编译后字节码）
    css/ js/ images/ （静态资源）
    index.html
  

• web.xml 模板（Jakarta EE 6.0）：

  <?xml version="1.0" encoding="UTF-8"?>
  <web-app xmlns="https://jakarta.ee/xml/ns/jakartaee"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="https://jakarta.ee/xml/ns/jakartaee
           https://jakarta.ee/xml/ns/jakartaee/web-app_6_0.xsd"
           version="6.0">
  </web-app>
  

5. 添加项目依赖

• 编译期依赖（如 servlet-api.jar）：放在项目模块下的 lib/目录，右键 Add as Library（Scope 选 Provided）。

• 运行时依赖（如 MySQL 驱动、Thymeleaf、Logback 等）：放在 WEB-INF/lib/下，通常不需要手动添加为库，这些会在运行时自动被tomcat识别，只有当没能正确识别的时候，你才需要手动 Add as Library（Scope 选 Compile 或 Runtime）。

五、项目所需的 Jar 包清单

注意：若使用 Maven/Gradle，可自动管理依赖。但本笔记基于手动导入 jar 方式。

六、MySQL 数据库配置

1. 安装 MySQL

• 安装并启动 MySQL 服务（默认端口 3306）
• 创建数据库（例如 servlet 或 bank），设置字符集为 utf8mb4

2. 添加驱动到项目

• 下载 mysql-connector-java-8.0.x.jar，放入 WEB-INF/lib 并 Add as Library

3. JDBC 配置文件（jdbc.properties）

• 放在 src/main/resources（类的根路径）：

  driver=com.mysql.cj.jdbc.Driver
  url=jdbc:mysql://localhost:3306/数据库名?useSSL=false&serverTimezone=Asia/Shanghai
  user=root
  password=你的密码
  

4. 工具类 DbUtils（参考文档）

• 提供 getConnection() 获取连接，close() 释放资源
• 结合 ThreadLocal 实现事务管理（需在 Service 层控制事务）

七、日志框架配置（Logback）

1. 添加依赖

• slf4j-api-2.x.jar、logback-classic-1.x.jar、logback-core-1.x.jar 放入 WEB-INF/lib

2. 配置文件 logback.xml

• 放在类根路径（src/main/resources）
• 示例配置（含控制台和文件输出）：

  <configuration>
    <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
      <encoder>
        <pattern>%d{HH:mm:ss} [%thread] %-5level - %msg%n</pattern>
      </encoder>
    </appender>
    <appender name="ERROR_FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
      <file>logs/error.log</file>
      <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
        <fileNamePattern>logs/error.%d{yyyy-MM-dd}.log</fileNamePattern>
        <maxHistory>7</maxHistory>
      </rollingPolicy>
      <encoder>
        <pattern>%d{yyyy-MM-dd HH:mm:ss} [%thread] %-5level %logger{36} - %msg%n</pattern>
      </encoder>
    </appender>
    <logger name="org.thymeleaf" level="ERROR"/>
    <logger name="com.jkweilai" level="INFO"/>
    <root level="WARN">
      <appender-ref ref="CONSOLE"/>
      <appender-ref ref="ERROR_FILE"/>
    </root>
  </configuration>
  

八、Thymeleaf 初始化配置

1. 添加 Thymeleaf 到项目

• 将 thymeleaf-3.1.x.RELEASE.jar 放入 WEB-INF/lib

2. 编写监听器初始化模板引擎

• 类：ThymeleafInitializer，实现 ServletContextListener
• 代码要点（参考文档）：

  JakartaServletWebApplication jakartaServletWebApplication = 
      JakartaServletWebApplication.buildApplication(application);
  WebApplicationTemplateResolver resolver = new WebApplicationTemplateResolver(jakartaServletWebApplication);
  resolver.setPrefix("/WEB-INF/templates/");
  resolver.setSuffix(".html");
  resolver.setTemplateMode(TemplateMode.HTML);
  resolver.setCacheable(false);
  TemplateEngine engine = new TemplateEngine();
  engine.setTemplateResolver(resolver);
  application.setAttribute("templateEngine", engine);
  

• 使用 @WebListener 注解注册

3. 创建 ThymeleafViewServlet（统一渲染）

• 从请求域中获取模板名称，通过 TemplateEngine.process(template, webContext, writer) 渲染

4. 模板目录

• 在 WEB-INF 下创建 templates 文件夹，存放所有 .html 模板（受保护，不能直接访问）

九、项目结构示例（三层架构 + MVC）

项目根目录/
├── src/main/java/
│   ├── com.jkweilai.xxx.controller/   （Servlet 控制器）
│   ├── com.jkweilai.xxx.service/      （业务接口与实现）
│   ├── com.jkweilai.xxx.dao/          （数据访问接口与实现）
│   ├── com.jkweilai.xxx.entity/       （PO/实体）
│   ├── com.jkweilai.xxx.dto/          （数据传输对象）
│   ├── com.jkweilai.xxx.vo/           （视图对象）
│   ├── com.jkweilai.xxx.common/       （工具类、异常、常量）
│   └── com.jkweilai.xxx.listener/     （监听器）
├── src/main/resources/
│   ├── jdbc.properties
│   ├── logback.xml
│   └── ...
├── webapp/
│   ├── WEB-INF/
│   │   ├── web.xml
│   │   ├── lib/                        （运行时 jar）
│   │   ├── classes/                    （编译输出）
│   │   └── templates/                  （Thymeleaf 模板）
│   ├── css/                             （静态资源）
│   ├── js/
│   └── index.html

十、常见问题与解决方案

1. Tomcat 启动报错 CATALINA_HOME 或 JAVA_HOME 未定义

• 确保环境变量正确设置，并重启命令行/IDE。

2. IDEA 控制台中文乱码

• 见上文 Tomcat 乱码部分，配置 VM options 或修改 logging.properties。

3. 404 错误

• 检查部署的 Application Context 是否匹配 URL。
• 检查 web.xml 中 <url-pattern> 是否以 / 开头且不含项目名。
• 检查静态资源是否放在 WEB-INF 外部（受保护资源不能直接访问）。

4. 405 错误（方法不允许）

• 前端请求方式（GET/POST）与 Servlet 重写的方法（doGet/doPost）不一致。

5. 响应中文乱码

• 在 Servlet 中添加 response.setContentType("text/html;charset=UTF-8");
• 或使用字符编码过滤器（@WebFilter("/*")）统一设置。

6. 请求参数中文乱码（POST）

• 在 request.getParameter() 之前调用 request.setCharacterEncoding("UTF-8")。
• 或在过滤器中统一处理。

7. 连接数据库异常（ClassNotFoundException）

• 检查 MySQL 驱动 jar 是否放在 WEB-INF/lib 并正确添加到 classpath。
• 检查 jdbc.properties 中 driver 类名是否正确（8.0 驱动为 com.mysql.cj.jdbc.Driver）。

十一、快速验证环境

完成配置后，可编写一个最简单的 Servlet 测试：

@WebServlet("/hello")
public class HelloServlet extends HttpServlet {
    protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws IOException {
        resp.setContentType("text/html;charset=UTF-8");
        resp.getWriter().print("<h1>Hello, 环境配置成功！</h1>");
    }
}

部署到 Tomcat，访问 http://localhost:8080/项目名/hello，看到中文正常显示即为成功。

总结：以上即为 Java Web 开发（基于 Servlet + Tomcat + Thymeleaf + JDBC）所需的所有环境配置，包括软件安装、环境变量、IDE 设置、依赖管理、数据库连接、日志配置等。建议按顺序逐一完成，确保每一步验证通过后再进入开发阶段。