# 附加到进程

> For the complete documentation index, see [llms.txt](https://www.jetbrains.com/zh-cn/help/idea/llms.txt).

> **TL;DR**
> `运行 | 附加到进程`  `Ctrl+Alt+F5` (Windows), `⌥ ⇧ F5` (macOS), `⌥ ⇧ F5` (IntelliJ IDEA Classic (macOS)), `⌥ ⇧ F5` (macOS System Shortcuts), `Ctrl+Alt+5` (XWin), `Ctrl+Alt+5` (GNOME), `Ctrl+Alt+5` (KDE), `Ctrl+Alt+F5` (Emacs), `Ctrl+Alt+F5` (Sublime Text), `⌥ ⇧ F5` (Sublime Text (macOS)), `Ctrl+Alt+P` (Visual Studio), `⌘ ⌥ P` (Visual Studio (macOS)), `Ctrl+Alt+F5` (NetBeans), `Ctrl+Alt+F5` (Eclipse), `⌥ ⇧ F5` (Eclipse (macOS))

IntelliJ IDEA 提供了一种连接调试器到本地和远程进程的方法。

连接到进程的步骤取决于进程的启动方式和位置。

> **Note:**
> 如果您想调试可以从 IntelliJ IDEA 启动的程序，最好的方法是 [启动本地调试会话](starting-the-debugger-session.html)。 这可以为您提供完整的调试器功能，同时避免额外配置的开销。

虽然 IntelliJ IDEA 调试器能够附加到任何进程，但建议在有更简单的方法时优先选择更简单的方法。 不必远程附加到在同一台机器上运行的 'hello world'。

本主题中描述的选项在更复杂的情况下非常有用，例如当我们需要调试远程运行的进程，或以不允许调试的方式启动的进程时。

## 前提

虽然附加并非绝对必要，但需要满足以下先决条件以启用完整的调试功能：

* 远程进程应使用 [debug agent](#debug-agent)启动。

* 该应用程序需要用 [调试信息](#debug-info) 编译。

* 您需要拥有 [应用程序的源代码](#sources)。

调试在这些条件都不满足时仍然是可能的，然而，每个条件都有其相关的限制。 这些要求将在后续章节中详细描述。

### 调试代理

允许调试器连接的进程由调试代理启动。  Debug agent  是宿主应用程序的一个组件，负责与调试器进行通信。 通信通过套接字连接进行，无论进程是本地还是远程。

Procedure: 使用调试代理启动进程

* 启动该进程时，在其 VM 选项中添加以下行：

附加:

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

```

该选项具有以下形参：

* `address` ——将用于调试的端口

* `server=y` ——指定进程应监听传入的调试器连接（作为服务器）。

* `suspend` – 指定 VM 应等待调试器连接还是立即开始执行应用程序代码

监听:

```
-agentlib:jdwp=transport=dt_socket,server=n,address=192.168.1.178:5005,suspend=y,onthrow=<FQ exception class name>,onuncaught=<y/n>

```

该选项具有以下形参：

* `address` - 服务器端的 IP 地址和端口。 支持 IPv4 和 IPv6。

* `server=n` 指定该进程应连接到调试器（作为客户端）

* `suspend=y` – 指定 VM 应等待调试器连接后再执行应用程序代码。

* `onthrow` — 可选地延迟连接，直到抛出指定的异常。 使用异常的完全限定名称作为值。

* `onuncaught` - 可选地延迟连接，直到抛出未捕获的异常。 使用异常的完全限定名称作为值。

格式可能会根据 JDK 版本有所不同。 为了获取适用于您的 JDK 的格式化字符串，您可以在 [Remote JVM debug](#create-rc) 运行/调试配置中选择所需的 JDK 版本并从那里复制。

如果该进程是通过另一个进程启动的，例如像 Apache Tomcat 这样的 web 容器，则可能需要间接指定 debug agent VM 选项。 例如，其他进程可能使用配置文件将选项传递给主机 VM。 对于常用的 Web 服务器和框架，IntelliJ IDEA 提供了 [运行/调试配置](list-of-run-debug-configurations.html)来为您完成此操作。

Procedure: 添加 IntelliJ IDEA 的调试代理

当调试在 IntelliJ IDEA 之外启动的进程时，您可以使用 IntelliJ IDEA 的高级功能，例如 [异步堆栈跟踪](debug-asynchronous-code.html)。 为此，您需要将 IntelliJ IDEA 的调试代理加载到进程中。

* 从 IntelliJ IDEA 的安装目录中添加  `debugger-agent.jar` ，使用  `javaagent`  VM 选项。 例如：

```
java -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=\*:5005
-javaagent:"/Users/me.user/Applications/IntelliJ IDEA Ultimate 2024.3.app/Contents/plugins/java/lib/rt/debugger-agent.jar" Alphabet

```

如果本地进程未使用调试代理，您仍然可以以只读模式附加到该进程。 调试器功能将仅限于查看调用栈和检查相关的局部变量。

在程序批量处理某些文件时挂起，就是这种情况可能有用的一个示例。 使用只读模式，您可以找出是哪个方法导致程序挂起，以及它正在处理哪个文件。

### 调试信息

调试信息 是一种特殊的信息，存在于应用程序字节码中。 调试器使用此信息来识别局部变量、行号等。 应用程序的字节码可能包含或不包含调试信息。

调试信息在编译时提供给程序。 这是通过  `-g`  编译器标志控制的。 默认情况下，编译器会包含大部分调试所需的信息，但如果不是您编译的应用程序，可能会发生这样的情况：您要调试的程序在编译时没有包含这些信息。

如果应用程序的字节码不包含调试信息，调试器仍然可以附加，但某些调试器功能可能不可用。 例如，没有行号信息时，无法查看行号或在断点处停止：

![debug_line_numbers_unavailable.png](https://resources.jetbrains.com/help/img/idea/2026.3/debug_line_numbers_unavailable.png)

无论是否存在调试信息，始终可用的最低限度：

* 类名，除非代码被混淆

* 静态变量和实例变量

* 调用堆栈

有关配置调试信息生成的更多信息，请参阅 [Java 编译器文档](https://docs.oracle.com/javase/7/docs/technotes/tools/windows/javac.html)。

### 应用程序源文件

建议您拥有调试项目源代码的访问权限。 IntelliJ IDEA 将调试事件与源代码匹配，并在编辑器中显示与调试会话相关的信息。 这使您可以将调试会话视为正在执行的源代码。

![debug_in_editor.png](https://resources.jetbrains.com/help/img/idea/2026.3/debug_in_editor.png)

为了让 IntelliJ IDEA 找到源文件，它们必须包含在类路径中。

## 附加到远程进程

连接到远程进程包括两个步骤：

* [创建运行/调试配置](#create-rc) – 运行/调试配置指定了如何建立连接。 创建运行/调试配置后，可以将其重新用于同一主机和端口上的其他连接。

* [启动运行/调试配置](#start-rc) – 当您启动运行/调试配置时，IntelliJ IDEA 会根据运行/调试配置中定义的设置启动并连接调试器。

> **Tip:**
> 本地和远程会话都使用套接字连接，唯一的区别是地址。 因此，可以按照以下步骤附加到任何使用调试代理的应用程序。

Procedure: 创建运行/调试配置

1. 前往  `运行 | 编辑配置` 。 或者，按 `Alt+Shift+F10` (Windows), `⌃ ⌥ R` (macOS), `⌥ ⇧ F10` (IntelliJ IDEA Classic (macOS)), `⌃ ⌥ R` (macOS System Shortcuts), `Alt+Shift+F10` (XWin), `Alt+Shift+F10` (GNOME), `Alt+Shift+F10` (KDE), `Alt+Shift+F10` (Emacs), `Alt+Shift+F10` (Sublime Text), `⌃ ⌥ R` (Sublime Text (macOS)), `Ctrl+Alt+Shift+R` (Visual Studio), `⌘ ⌥ ⇧ R` (Visual Studio (macOS)), `Alt+Shift+F10` (NetBeans), `Alt+Shift+F10` (Eclipse), `⌃ ⌥ R` (Eclipse (macOS))，然后按 `0` (Windows), `0` (macOS), `0` (IntelliJ IDEA Classic (macOS)), `0` (macOS System Shortcuts), `0` (XWin), `0` (GNOME), `0` (KDE), `0` (Emacs), `0` (Sublime Text), `0` (Sublime Text (macOS)), `0` (Visual Studio), `0` (Visual Studio (macOS)), `0` (NetBeans), `0` (Eclipse), `0` (Eclipse (macOS))。

2. 在 [运行/调试配置](run-debug-configurations-dialog.html)对话框中，点击 ![](https://resources.jetbrains.com/help/img/idea/2026.3/app.expui.general.add.svg)工具栏上的按钮或按下 `Alt+Insert` (Windows), `⌘ N` (macOS), `⌃ N` (IntelliJ IDEA Classic (macOS)), `⌘ N` (macOS System Shortcuts), `Alt+Insert` (XWin), `Alt+Insert` (GNOME), `Alt+Insert` (KDE), `Alt+Insert` (Emacs), `Ctrl+N` (Sublime Text), `⌘ N` (Sublime Text (macOS)), `Ctrl+N` (Visual Studio), `⌘ N` (Visual Studio (macOS)), `Alt+Insert` (NetBeans), `Alt+Insert` (Eclipse), `⌘ N` (Eclipse (macOS))。 选择   远程 JVM 调试   从列表中。

3. 在   调试器模式   指定调试器是应连接到远程 JVM 还是监听传入的连接。

> **Note:**
> 确保所选的   调试器模式   与远程 JVM 的 VM 选项一致。 例如，如果远程 JVM 正在监听（扮演服务器），调试器必须附加（扮演客户端）。

如果您选择   侦听远程 JVM  ，请指定在远程 JVM 断开连接后是否要自动重新启动调试器。 这样，调试器将随时准备处理传入的连接。

4. （适用于 Windows）可选择指定所需的 [传输方式](https://docs.oracle.com/javase/7/docs/technotes/guides/jpda/conninv.html#Transports)。 IntelliJ IDEA 会自动选择适当的传输方式，因此除非您对通信方法有特殊要求，否则无需配置。

5. 指定远程 JVM 的主机和端口。 支持 IPv4 和 IPv6。 请确保端口指定正确、未被占用且未被防火墙阻止。

6. 指定查找源代码的模块。 IntelliJ IDEA 将首先检查选定的模块，然后是其他模块（如果有的话）。 源使用完全限定类名进行匹配。 如果完全限定名称没有匹配项，IntelliJ IDEA 会尝试通过文件名查找匹配项。

7. 可选：配置日志。 有关日志设置，请参阅 [日志](setting-log-options.html)。

8. 如果您尚未为调试对象 JVM 配置调试代理，您可以从   远程 JVM 的命令行参数   字段中复制所需的 VM option。

![debug-agent-option.png](https://resources.jetbrains.com/help/img/idea/2026.3/debug-agent-option.png)

Procedure: 开始运行/调试配置

1. 请确保主机应用程序正在运行，并以添加调试代理的 [VM option](#debug-agent) 启动。

2. [启动](starting-the-debugger-session.html)运行/调试配置 [您之前创建的](#create-rc)。

![debug_select_rc.png](https://resources.jetbrains.com/help/img/idea/2026.3/debug_select_rc.png)

##  浏览可用进程 

Procedure:

1. 按 `Ctrl+Alt+F5` (Windows), `⌥ ⇧ F5` (macOS), `⌥ ⇧ F5` (IntelliJ IDEA Classic (macOS)), `⌥ ⇧ F5` (macOS System Shortcuts), `Ctrl+Alt+5` (XWin), `Ctrl+Alt+5` (GNOME), `Ctrl+Alt+5` (KDE), `Ctrl+Alt+F5` (Emacs), `Ctrl+Alt+F5` (Sublime Text), `⌥ ⇧ F5` (Sublime Text (macOS)), `Ctrl+Alt+P` (Visual Studio), `⌘ ⌥ P` (Visual Studio (macOS)), `Ctrl+Alt+F5` (NetBeans), `Ctrl+Alt+F5` (Eclipse), `⌥ ⇧ F5` (Eclipse (macOS)) 或从主菜单中选择  `运行 | 附加到进程` 。

2. IntelliJ IDEA 将显示正在运行的进程列表。 如果要附加到的进程未列出，请尝试刷新列表 ![](https://resources.jetbrains.com/help/img/idea/2026.3/app.expui.inline.refresh.svg)。 请选择要附加的进程。

> **Tip:**
> 当进程过多时，您可以通过输入进程名称或 PID 的首字母缩小列表范围。
>
>
>
> 此外，您可以按类型筛选进程。 使用 [debug agent](#debug-agent) 启动的进程显示在   Java   下。 不使用 [调试代理](#debug-agent)的列在   Java Read Only  下。 更多关于只读模式的信息 [在这里](#read-only)。

## 附加到当前进程

如果您使用 IntelliJ IDEA 的调试代理运行该进程，您可以直接从控制台附加到它。

Procedure:

1. 从 IntelliJ IDEA 运行带有调试代理的进程。

2. 当控制台出现时，点击   附加调试器  嵌入提示。

![控制台中显示了一个将调试器附加到进程的按钮](https://resources.jetbrains.com/help/img/idea/2026.3/debug_attach_to_current.png)

## 从进程中分离

从远程进程分离的步骤与停止本地调试会话的步骤相同。 但是，与本地会话不同，调试器分离后目标进程会继续运行。

Procedure:

* 点击   停止   ![停止按钮](https://resources.jetbrains.com/help/img/idea/2026.3/app.expui.run.stop.svg) 按钮，位于   调试   工具窗口的工具栏上或 [调试工具窗口](debug-tool-window.html) 中。

![调试工具窗口工具栏上的停止按钮](https://resources.jetbrains.com/help/img/idea/2026.3/debug_stop.png)

* 或者，点击   停止   ![停止按钮](https://resources.jetbrains.com/help/img/idea/2026.3/app.expui.run.stop.svg)主工具栏上的 `Ctrl+F2` (Windows), `⌘ F2` (macOS), `⌘ F2` (IntelliJ IDEA Classic (macOS)), `⌃ ⇧ .` (macOS System Shortcuts), `Ctrl+F2` (XWin), `Ctrl+F2` (GNOME), `Ctrl+2` (KDE), `Ctrl+F2` (Emacs), `Ctrl+F2` (Sublime Text), `Ctrl+F2` (Sublime Text (macOS)), `Shift+F5` (Visual Studio), `⇧ F5` (Visual Studio (macOS)), `Shift+F5` (NetBeans), `Ctrl+F2` (Eclipse), `⌘ F2` (Eclipse (macOS))，然后选择要关闭的会话。

![debug_stop_select.png](https://resources.jetbrains.com/help/img/idea/2026.3/debug_stop_select.png)

## 终止远程进程

当您不再需要远程进程时，可以通过关闭相应的调试器选项卡来终止它。 默认情况下，IntelliJ IDEA 会询问您是否要终止进程或与其断开连接：

![询问是否终止进程或与其断开连接的对话框](https://resources.jetbrains.com/help/img/idea/2026.3/debug-terminate-or-disconnect.png)

您可以在   外观与行为 | 系统设置   设置页面 `Ctrl+Alt+S` (Windows), `⌘ Comma` (macOS), `⌘ Comma` (IntelliJ IDEA Classic (macOS)), `⌘ Comma` (macOS System Shortcuts), `Ctrl+Alt+S` (XWin), `Ctrl+Alt+S` (GNOME), `Ctrl+Alt+S` (KDE), `Ctrl+Alt+S` (Emacs), `Ctrl+Alt+S` (Sublime Text), `⌘ Comma` (Sublime Text (macOS)), `Ctrl+Alt+S` (Visual Studio), `⌘ Comma` (Visual Studio (macOS)), `Ctrl+Alt+S` (NetBeans), `Ctrl+Alt+S` (Eclipse), `⌘ Comma` (Eclipse (macOS)) 上自定义默认选项。