妞妞牛波1. 为什么2017版的IDEA配置Tomcat，照着新教程反而弄不明白
先说个我自己的经历。前阵子公司翻出一个老项目，开发机上一装就是IntelliJ IDEA 2017.2，网上随手搜的配置教程全是2020甚至2022版本之后的界面，照着走第一步就卡住了——新教程说“点右侧的Add Configuration”，老版本根本没有这个入口；新教程说“Services窗口里找到Tomcat”，2017版里连Services窗口都还没有。这不是你笨，是IDEA这些年界面改动确实太大了，老版本的配置路径跟现在的完全是两套逻辑。
这篇文章就专门解决这件事：在2017版本IDEA（2017.1、2017.2、2017.3都能用）里，把一个JavaWeb项目配上Tomcat并成功跑起来。内容覆盖从Tomcat准备、JDK匹配、Project Structure设置、Artifacts创建，到Run Configurations里添加Tomcat Server、启动运行和常见报错排查的完整链路。
2017版IDEA的配置流程存在一个很关键的逻辑：你必须先把项目的“Web工件（Artifact）”建好，才能在运行配置里把项目挂到Tomcat上。新版本IDEA在很大程度上简化了这个流程，所以用新思路处理老版本就会到处找不到入口。明白这个底层逻辑之后，菜单路径再怎么变你也不会慌。
适合看这篇文章的读者有两类：一是还在用2017版IDEA完成课程设计、毕业设计的学生，机房电脑可能就装了这个版本；二是和我一样，因为老项目维护不得不用旧版IDE的开发者。我下面写的都是实测走过的步骤，不是从新教程里倒推出来的。
2. 动手前的准备：Tomcat版本怎么选、JDK怎么配、IDEA版本怎么确认
这一步看起来很基础，但恰恰是翻车率最高的地方。很多人下了一个最新版的Tomcat 10或11，然后拿JDK 8去配，结果Tomcat起都起不来，日志里全是类找不到的报错，最后还以为是IDEA配置错了。
2.1 Tomcat版本与JDK版本的匹配关系
2017版IDEA那个年代，主流的开发组合就是JDK 1.8配Tomcat 8或8.5。Tomcat 8.5是当时最稳的选择，完美兼容Servlet 3.1和JSP 2.3，Spring MVC这类框架也都能正常跑。尽量别用Tomcat 9，虽然Tomcat 9理论上也支持JDK 8，但它改了部分包名和规范实现，在2017版IDEA的老式部署方式下容易出现一些莫名其妙的兼容问题。
如果你现在去Apache官网下载，版本已经到Tomcat 11了，别下最新的，直接往下翻，找到Tomcat 8.5的下载链接。Windows选64-bit Windows zip包，Mac或Linux选tar.gz包。我推荐下载压缩包而不是安装版，因为IDEA定位Tomcat时需要一个明确的目录路径，压缩包解压即用，不污染系统环境，出问题删掉重来也方便。
提示：Tomcat是绿色软件，不需要“安装”到系统里。解压到一个纯英文路径下（比如
D:\apache-tomcat-8.5.100），路径不要带空格和中文，否则后续启动可能遇到隐藏的编码或路径解析问题。
2.2 JDK环境变量必须提前确认
IDEA自身的运行不强制要求Java环境变量，但Tomcat的启动脚本（startup.bat / catalina.sh）必须依赖JAVA_HOME环境变量。虽然IDEA配置Tomcat时也会用自带JDK启动，但为了减少变量，我建议先把环境变量配好。
具体检查方式：命令行里分别执行java -version和echo %JAVA_HOME%（Mac/Linux用echo $JAVA_HOME）。如果JAVA_HOME为空，就需要到系统环境变量里手动添加，指向JDK安装目录，比如C:\Program Files\Java\jdk1.8.0_202。注意是JDK的根目录，不是bin目录。
2.3 确认你是Ultimate版还是Community版
这是2017版IDEA的一个大坑，很多新手卡在这里大半天，实际原因就四个字：版本不对。
IntelliJ IDEA分Ultimate（旗舰版）和Community（社区版）。社区版根本不支持JavaWeb项目的Tomcat Server配置功能，Run Configurations里面永远找不到Tomcat选项。如果你用的是Community版，无论怎么翻菜单都不可能配置成功。
确认方法很简单：打开IDEA，菜单栏选Help → About，弹出的对话框里会明确写IntelliJ IDEA 2017.x Ultimate Edition还是Community Edition。如果是Community版，要么装一个Ultimate版，要么去JetBrains官网申请学生授权（学生邮箱可以免费使用旗舰版）。这个限制在2017版里非常严格，不像后来的版本可以通过插件扩展部分功能。
另外提醒一句：2017版IDEA还没有内置的Tomcat集成插件下载入口，不需要额外装插件，旗舰版原生就支持。
3. 核心配置第一站：Project Structure里的三处关键设置
很多教程上来就让你配Run Configuration，这是本末倒置的逻辑。项目还没被IDEA识别为Web项目，你就算配好Tomcat Server，部署列表里也是空的，什么Artifact都添加不进去。所以必须先过Project Structure这一关。
按下Ctrl+Alt+Shift+S（Mac是Cmd+;）打开Project Structure窗口，这里有三处要改：Project、Modules、Artifacts。
3.1 Project选项卡：SDK和Language Level
左侧选Project，右侧确认Project SDK选择的是1.8，Project语言级别（Project language level）选8或7都可以，千万别选更高的版本，否则和Tomcat 8.5的字节码兼容性可能出现问题。同时还需要确认Project compiler output有值，比如直接填D:\project\out，这个目录是编译产物的出口，后面Artifacts会引用它。
3.2 Modules选项卡：给项目标记Web能力
Modules这一步是整个配置成败的分水岭。选中你的项目模块，然后：
-
在Sources页签下，确认
src目录被标记为Sources（蓝色），web目录被标记为Web Resources（如果有这个标记选项）。这一步的作用是告诉IDEA“哪些文件夹是Java源码、哪些是Web静态资源”，直接影响后面的编译和打包范围。 -
切到Paths页签，把Compiler output改成
D:\project\out（跟Project里填的保持一致）。 -
切到Dependencies页签，点右侧的“+”号，选Library或者JARs，把Tomcat安装目录下
lib文件夹里的servlet-api.jar加进来，作用范围（Scope）选Provided。这里解释一下为什么要选Provided：意思是这个jar在编译时需要，但部署时由Tomcat自己提供，不要打包进你的应用里，否则可能和服务器内置的实现冲突。
之后左侧轻轻点一下模块上方的Facets（如果没有这个入口就右键模块选Add → Framework Support，然后勾选Web Application），在Facets设置里指定Web资源目录为web，并配置web/WEB-INF/web.xml的路径。如果项目还没有web.xml，IDEA会提示自动创建，直接同意就行。
3.3 Artifacts选项卡：创建war exploded
这是2017版IDEA配置流程里最核心的一步。左侧点Artifacts，如果列表是空的，就点“+”号选Web Application → Exploded，然后选From modules，把你的模块添加进去。
这里有两个概念容易混淆，我用最简单的话解释：
- Archive：打成一个war包。部署时Tomcat需要把整个war包解压，启动慢，开发和调试效率低。
- Exploded（字面意思是“展开的”）：相当于把war包解开后的目录直接作为部署目录。IDEA会把这个目录里的内容和Tomcat建立映射，改代码后可以热更新，不用每次重启服务器，开发体验好很多。
在2017版IDEA里，开发调试阶段务必选Exploded。选完以后，确认Output directory指向D:\project\out\artifacts\xxx_war_exploded，这个路径后面部署时会用到。
Artifacts创建完成后，Project Structure窗口就可以关掉了。到此为止，项目已经被IDEA识别为“可部署的Web应用”，去配Tomcat才有了意义。
4. 配置Tomcat Server：Run Configurations里的完整链路
现在进入大家最熟悉的环节——配置运行配置。菜单栏打开Run → Edit Configurations，点左上角的“+”，往下拉，找到Tomcat Server，选择Local。注意不要选TomEE，TomEE是另一个服务器，不是我们需要的。
4.1 Server页签：定位Tomcat安装目录和端口
选中新建的Tomcat Server后，主要配置都集中在两个标签页里，先看Server页签：
-
Application server：点后面的Configure按钮，弹出窗口里选Tomcat安装根目录，也就是你解压后的那个文件夹路径。IDEA会自动识别版本号，例如Apache Tomcat 8.5.100。识别成功后点OK。
-
Open browser：默认勾选After launch，URL填
http://localhost:8080/。这个配置的作用是在Tomcat启动成功后自动打开浏览器访问地址，省得手动敲。 -
HTTP port：默认8080。如果这个端口被其他程序占用，可以改成8081、8082等任意空闲端口。后面访问路径要跟着改。
-
VM options：建议填一行参数：
-Dfile.encoding=UTF-8。2017版IDEA里Tomcat控制台中文乱码问题很常见，提前加这个参数可以避免一半的乱码问题。
4.2 Deployment页签：把Artifact挂到Tomcat上
切到Deployment标签页，点“+”，选Artifact，在弹出的列表里选择之前创建好的那个xxx:war exploded。添加完成后，下方会出现一个Application context输入框，默认是/项目名，比如/demo。这个就是你的Web应用访问根路径，最终访问地址就是http://localhost:8080/demo/。
如果你希望直接通过http://localhost:8080/访问，不想要项目名前缀，那就把Application context删成空（或者改成/）。两种方式都合法，看个人习惯，但我建议新手保留项目名作为context，这样多个应用部署在同一个Tomcat上时不容易混淆。
到这里运行配置就基本完成了。点OK保存，然后点工具栏上的绿色三角形按钮启动。第一次启动时IDEA可能会弹一个警告框，大概意思是“Artifact xxx会被部署到Tomcat”，直接点OK。
启动成功后在IDEA底部控制台能看到Tomcat的启动日志，并出现Server startup in [xxx] milliseconds这一行，同时浏览器自动打开访问地址，看到项目页面就说明配置成功。
4.3 修改代码后的更新方式：Update resources
2017版IDEA已经支持热更新，但不完全是那种改了就能自动刷新的模式。如果你修改的是JSP、JS、CSS这类静态资源，在Run窗口里有个更新按钮（圆形的刷新箭头图标），点一下选Update resources，浏览器刷新就能看到效果，Tomcat不用重启。
如果你改了Java类，选Update classes and resources，IDEA会重新编译并热替换类。但是注意，修改了web.xml或者pom.xml这类配置，必须重启Tomcat才生效，热更新不会重新加载这些文件。这是Tomcat类加载机制决定的，不是IDEA的锅。
5. 启动过程中的高频报错：从端口占用到ClassNotFoundException
配完Tomcat后第一次运行，很少能一次通过。下面这几个报错是2017版IDEA配Tomcat时出现频率最高的，我把排查思路写清楚，遇到时按路径走就行。
5.1 端口被占用：Address already in use: JVM_Bind
日志里出现java.net.BindException: Address already in use: JVM_Bind，说明8080端口被占了。这种情况最常见的来源是：之前启动过的Tomcat没关干净、其他程序占用了端口（比如某些开发工具的内置服务）。
排查方法：命令行执行netstat -ano | findstr 8080（Windows）或lsof -i:8080（Mac/Linux），拿到占用端口的进程PID后，到任务管理器里结束对应进程。如果你不想杀进程，更省事的做法是直接把IDEA里Tomcat配置的HTTP port改成8081，然后访问http://localhost:8081/项目名。
5.2 浏览器404：上下文路径与Artifact不符
Tomcat正常启动了，日志也没有报错，但浏览器打开404。排查次序：先确认Tomcat自带首页http://localhost:8080/能不能访问。如果能访问但带项目名的地址404，问题几乎一定出在Deployment的Application context和Artifact的匹配上。
回到Run → Edit Configurations，看Deployment页签里的Application context是不是跟浏览器地址栏一致。最常见的手误是把context写成/demo/（多了一个斜杠）或者漏了开头的/。另外要注意，修改context之后必须重启Tomcat，IDEA不会自动同步这个设置。
5.3 启动直接失败：No artifacts marked for deployment
日志里出现No artifacts marked for deployment，说明你的Deployment列表是空的。回到Project Structure的Artifacts里，确认Exploded是否创建成功。如果在Artifacts里看不到内容，大概率是第三步的Modules没有正确添加Web依赖。
还有一种情况：Artifacts创建好了，但Deployment标签页里点“+”后列表是灰的。这种情况通常是你选的Tomcat Server类型不对，检查一下是不是选成了TomEE Server。
5.4 ClassNotFoundException：Servlet API相关类找不到
启动时日志报java.lang.ClassNotFoundException: javax.servlet.ServletException、NoClassDefFoundError: javax/servlet/...这类错误，根因是项目编译时缺少Servlet API相关依赖。
回到Project Structure → Modules → Dependencies，点“+”添加JARs，定位到Tomcat的lib目录，选中servlet-api.jar和jsp-api.jar，Scope选Provided，然后重新Build → Build Artifacts → Rebuild。这一步我强烈建议养成习惯：所有跟Servlet、JSP相关的依赖，都用Tomcat自带的，不要自己从网上下载。版本对应关系最准，不会有冲突。
还有一种隐蔽的情况：你自己从Maven仓库引了javax.servlet-api，但用的是3.0甚至2.5的版本，而Tomcat 8.5是Servlet 3.1规范，老版本API里某些新注解不认识，也会类加载异常。统一换成Tomcatlib目录下的jar是最省心的方案。
5.5 控制台中文乱码：编码三层排查法
2017版IDEA里中文乱码通常出现在两个位置：一是IDEA控制台打印乱码，二是浏览器页面显示乱码。
控制台乱码的优先解法：菜单栏Help → Edit Custom VM Options，打开idea64.exe.vmoptions文件后追加一行-Dfile.encoding=UTF-8，保存重启IDEA。如果还是乱码，去Tomcat的conf/logging.properties里，把java.util.logging.ConsoleHandler.encoding从UTF-8改成GBK（Windows）试试。这个文件不会出现在IDEA里，需要手动用文本编辑器打开改。
页面乱码的处理思路：JSP页面顶部检查<%@ page contentType="text/html;charset=UTF-8" language="java" %>，同时确认File菜单里的File Encoding三处都设成UTF-8。2017版IDEA默认文件编码是GBK（在中文Windows环境下），所以新建JSP文件时手动改一次编码并转码，这个小细节能救很多人的命。
6. 2017版老一点的IDEA，还有几个容易被忽略的设计
文章走到这里，核心配置链路已经完整。最后再补充几个老版本特有的使用细节，这些在实际开发中会频繁遇到。
6.1 没有Services窗口，多个Tomcat怎么管理
新手可能不知道，2017版IDEA底部工具窗口列表里是没有Services的，这个窗口是后来版本才加入的。那要同时管理多个Tomcat（比如一个正式环境、一个测试环境）怎么办？
做法是：在Run → Edit Configurations里创建多个Tomcat Server配置，每个配置指定不同的Tomcat安装目录或至少不同端口。运行后打开View → Tool Windows → Run，在Run窗口左侧的下拉列表里手动切换当前激活的配置。虽然不如新版Services窗口直观，但功能完全够用。
实际维护多环境时，我习惯把配置命名为Tomcat-Dev-8080、Tomcat-Test-8081这种带端口号的格式，一眼就能认出是哪个环境。
6.2 Maven项目的替代配置路径
如果你的项目是Maven结构（有pom.xml），可能还想用更“Maven原生”的方式跑Tomcat。2017版IDEA里可以在pom.xml里加tomcat7-maven-plugin插件，然后通过右侧Maven Projects窗口执行tomcat7:run命令启动。这种方式的好处是部署过程完全由Maven接管，不依赖IDEA的部署机制，在持续集成交付场景下更常用。
但它有局限性：tomcat7插件用的是嵌入式Tomcat，只支持到Servlet 3.0规范，如果你的项目用了Servlet 3.1的新特性，还是会老老实实按上面讲的方式配置本机Tomcat。另外，嵌入式启动的调试体验不如外部Tomcat直观，断点有时候会失效。
6.3 整个配置链路的核心逻辑是什么
花点时间把配置的底层逻辑梳理一下：IDEA要把你的项目跑在Tomcat上，需要三样东西对齐——项目本身要能被编译成Web应用（Project Structure里的Modules和Artifacts）、Tomcat要能被IDEA启动和停止（Run Configurations里的Application server）、项目编译产物要能部署到Tomcat的应用目录（Deployment里的Artifact和Application context）。三者缺一不可，这就是为什么先配Project Structure、再配Run Configurations的顺序不能乱。
记住这个逻辑，你就不会再被不同版本的IDEA菜单绕晕——界面入口再变，背后的关系始终不变。这比记住任何一个具体按钮位置都有用。
最后分享一个我踩过几次后养成的习惯：每次配完环境，先启动一次Tomcat自带的ROOT应用，确认服务器本身没问题，然后再部署自己的项目。这样一旦出问题，你至少能分清是Tomcat的问题还是项目的问题。配置这套东西本身并不难，难的是在十几条路径里找到正确的组合，希望这篇文章能帮你一次趟过去。