企业官网建设流程全解析

• 文档
• 教程

本指南完整讲解如何在 IntelliJ IDEA 中通过 JDWP（Java Debug Wire Protocol）协议，对部署在远程服务器上的 Tomcat、Jetty 应用进行远程断点调试。文章以本仓库 remote-debugging.md 的实操流程为主线，覆盖本地 Remote 运行配置、服务器端 JVM 参数注入、连接验证与断点命中的全过程。读完本文，你将掌握一套不依赖 IDEA 与服务器同机、可直接落地的远程调试方案，并理解-agentlib:jdwp参数中每个字段的实际作用。

远程调试原理速览：JPDA 与 JDWP

远程调试的本质，是让远程 JVM 对外暴露一个调试端口，再由本地的 IntelliJ IDEA 以调试客户端身份连上这个端口，双方通过JDWP（Java Debug Wire Protocol）交换断点、变量、线程栈等调试信息。JDWP 是 Java 平台调试架构JPDA（Java Platform Debugger Architecture）三件套之一：

JDWP 的启用方式非常简单：在远程 JVM 启动命令上附加-agentlib:jdwp参数即可。本文反复使用的核心参数如下：

-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=5005

从本教程的定位看，这套流程适用于 README.md 中说明的 IntelliJ IDEA 14~2023 及同源的 WebStorm、PyCharm 等 JetBrains 系列 IDE——凡是基于 JVM 的远程调试，其配置入口与参数格式完全一致。

准备工作：确认 IP 与放行防火墙

远程调试的第一步，是确保本地 IDEA 能与远程服务器建立 TCP 连接：

• 明确远程服务器 IP：例如本文沿用文档示例192.168.92.128，请替换为你自己服务器的实际地址。
• 处理防火墙：远程调试端口5005必须对本地可达。原文档给出的做法是直接关闭防火墙：

service iptables stop

这是 CentOS 6 等旧系统惯用命令。若使用 CentOS 7+ 或 Ubuntu 等发行版，更推荐按需放行 5005 端口，而非整体关闭防火墙，例如：

# CentOS 7+（firewalld） firewall-cmd --permanent --add-port=5005/tcp && firewall-cmd --reload # Ubuntu（ufw） ufw allow 5005/tcp

建议只对可信网络或内网环境开放调试端口，避免将调试端口暴露在公网上。

本地 IDEA：创建 Remote 运行配置

远程调试的"客户端"侧配置在本地 IDEA 中完成，路径为：

1. 打开Run / Debug Configurations窗口（工具栏运行配置下拉框 → Edit Configurations，或Alt + Shift + F10→ 选择 Remote 类型）。在配置类型列表中选中Remote，点击+新建一条远程运行配置，如图所示：

2. 创建后，IDEA 会自动生成一段 JVM 参数，出现在配置面板的Command line arguments for remote JVM区域，即上文反复提到的：

-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=5005

请先复制这段参数，稍后要原样注入到远程服务器的启动脚本中。

3. 在配置面板中填写服务器信息：
   • Host：填入远程服务器 IP，如192.168.92.128；
   • Port：保持与address=5005一致；
   • Transport：选择Socket；
   • Debugger mode：保持默认的Attach（本地 IDEA 作为客户端去附着远程 JVM），这也是与server=y匹配的连接模式。

从图示可以看到，IDEA 给出的参数默认suspend=n，意味着远程 JVM 启动后不会阻塞等待调试器，应用可以立即对外提供服务——这对生产/预发环境的远程调试非常重要。

远程 Tomcat 开启调试

在 catalina.sh / catalina.bat 中注入参数

以 Linux 环境为例，假设 Tomcat 安装于/usr/program/tomcat7，其启动脚本为/usr/program/tomcat7/bin/catalina.sh：

1. 编辑启动脚本：

vim /usr/program/tomcat7/bin/catalina.sh

2. 在文件最上方添加（注意单引号保留，避免 Shell 拆分变量）：

export JAVA_OPTS='-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=5005'

3. 如果你的项目本身还有自定义 JVM 参数（如内存设置-Xmx、编码-Dfile.encoding等），请把调试参数与你原有的参数合并成同一个 JAVA_OPTS 字符串，不要重复赋值覆盖，例如：

export JAVA_OPTS='-Xms512m -Xmx1024m -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=5005'

Windows 环境则编辑catalina.bat，在文件顶部添加（Windows 下不加引号）：

set JAVA_OPTS=-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=5005

更推荐的注入方式：setenv.sh

直接修改catalina.sh的缺点是升级 Tomcat 或重装后容易丢失配置。Tomcat 官方支持在bin目录下创建独立的setenv.sh（Windows 为setenv.bat），其内容会在启动时被catalina.sh自动加载，是隔离调试配置的常见做法：

# 新建 /usr/program/tomcat7/bin/setenv.sh export JAVA_OPTS='-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=5005'

两种方式最终都会把参数交给 JVM 进程，原理相同，可任选其一。

远程 Jetty 开启调试

Jetty 与 Tomcat 的差异在于：Jetty 无需安装，只要有对应的 jar 包即可直接启动应用，因此调试参数可以直接内联在启动命令中。在启动应用的命令里追加之前复制的 JDWP 参数即可：

java -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=5005 -jar {your jetty path} {your port} --path {your war} 1>/dev/null 2>&1 &

对这段命令的说明：

注意这里的address=5005是调试端口，与 Jetty 的业务端口（{your port}）相互独立，不要混淆。

连接与断点调试

完成以上配置后，按如下顺序操作：

1. 先启动远程服务器（Tomcat 或 Jetty），确认 JVM 已带 JDWP 参数启动，并成功监听 5005 端口。可用netstat -anp | grep 5005或ss -lntp | grep 5005验证。
2. 再在本地启动 Remote 运行配置：选中刚创建的 Remote 配置，点击 Debug 按钮（绿色甲虫图标，或Shift + F9）。

如果连接成功，IDEA 的 Debug 工具窗口会输出类似信息：

Connected to the target VM, address: '192.168.92.128:5005', transport: 'socket'

出现Connected to the target VM即代表本地 IDEA 已与远程 JVM 建立 JDWP 通道，接下来就可以像本地调试一样操作：

• 在本地源码中需要的位置打上断点（Ctrl + F8）；
• 用浏览器或接口工具访问远程服务的对应 URL，请求进入断点行时，执行会在本地 IDEA 中停住，可以看到线程栈、变量值等调试信息，且能正常进行单步、步入、求值等操作。

关于断点命中后的常用操作（F7步进、F8步过、F9恢复运行、Alt + F8表达式求值、Drop Frame回退栈帧等），本仓库的 debug-introduce.md 中有完整的 Win/Mac 快捷键对照表与进阶调试技巧（条件断点、Pass count、断点自动删除、内存查看等），远程调试与本地调试在断点操作上完全一致，可直接参考该文。

常见问题与注意事项

1. suspend=y与suspend=n的选择：调试应用启动阶段（如 Spring 容器初始化）的代码时，可临时改为suspend=y，这样 JVM 会等待 IDEA 连接后才继续启动，保证不遗漏早期代码；平时保持n避免服务阻塞。
2. 端口冲突与防火墙：address=5005必须未被占用，且防火墙/安全组需放行该端口；多实例部署时可把各实例的调试端口错开（如 5005、5006）。
3. 连接失败的常见原因：远程 JVM 未真正加载 JDWP 参数（检查启动日志）、Host/Port 填写不一致、transport不是dt_socket、服务器防火墙拦截等。
4. 安全提醒：远程调试端口暴露在公网有被利用的风险，建议仅在内网/测试环境使用，或调试完成后移除启动参数并重启应用。
5. 与热部署插件搭配：若希望远程修改代码后自动生效，可结合本仓库 jrebel-setup.md 介绍的 JRebel 插件使用，进一步缩短远程调试的迭代周期。

关联阅读

• remote-debugging.md：本文依据的原始实操文档
• debug-introduce.md：Debug 设置、快捷键与进阶断点技巧
• jrebel-setup.md：Java 热部署插件 JRebel 的安装与使用
• README.md：本套 IntelliJ IDEA 简体中文专题教程的完整目录与适用范围

• 文档
• 教程