# 调试 GraalVM 本机镜像

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

IntelliJ IDEA 可让您调试 GraalVM native images。

Procedure: 安装 GraalVM Native Debugger 插件

此功能性依赖于 GraalVM Native 调试器插件，需要安装并启用该插件。

> **Note:**
> 在没有 Ultimate 订阅的情况下，IntelliJ IDEA 中无法使用 GraalVM Native 调试器插件。

1. 按 `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)) 打开设置，然后选择  `插件` 。

2. 找到  GraalVM Native 调试器 插件，然后点击   安装  。 如果出现提示，请重启 IDE。

## 操作系统

GraalVM 构建还无法为除 Linux 以外的操作系统生成 [调试信息](https://www.graalvm.org/latest/reference-manual/native-image/debugging-and-diagnostics/DebugInfo/)。

要在其他操作系统上调试本地映像，您必须编译 Linux 的可执行文件，并在 Docker 容器中 [运行](run-targets.html)。 如果您使用 Windows，您也可以使用 [WSL](how-to-use-wsl-development-environment-in-product.html) 来实现此目的。

有关 Docker 容器的要求，请参阅 [Docker 镜像](#docker_image)。

## 前提

在调试 GraalVM Native 镜像之前，请确保检查以下先决条件：

* 该构建产物必须使用 [调试信息](https://www.graalvm.org/latest/reference-manual/native-image/debugging-and-diagnostics/DebugInfo/)进行编译。 调试信息是调试器用来理解运行的程序与源代码之间映射关系的元数据。 它由编译器标志在构建阶段控制，并且通常在生产构建中不存在。

* 构件必须以最小（最好为零）的优化进行编译。 在启用优化的情况下，您可能能够调试本机可执行文件；但是，这可能会限制调试器功能。 例如，如果可执行文件是使用 `-O2` 优化级别（也称为 release ）编译的，您将只能检查线程的堆栈和一些全局变量。

* 由于调试器依赖于应用程序的源代码，请确保您能够访问用于构建该应用程序的 确切版本 的源代码。

* 如果在 Docker 容器或远程环境中调试，目标必须安装并运行 `gdbserver` 。

## 在 Linux 上进行本地调试

如果您在 Linux 上使用   GraalVM Native Image   运行配置运行可执行文件，您可以在不进行额外设置的情况下对其进行调试。

Procedure: 调试 'GraalVM Native Image' 运行配置

* 在 [运行微件](guided-tour-around-the-user-interface.html#toolbar) 中选择运行配置，然后点击   调试  。

![主工具栏上的“Debug”按钮](https://resources.jetbrains.com.cn/help/img/idea/2026.3/native-debug-run-widget.png)

> **Tip:**
> 有关调试运行配置的详细信息，请参阅 [启动调试器会话](starting-the-debugger-session.html)

## 附加到正在运行的本地可执行文件

如果您不是在 Linux 上或不是从 IntelliJ IDEA 执行程序，请使用   GraalVM Native Attach   运行配置。

Procedure: 创建运行配置

1. 在 [运行小部件](guided-tour-around-the-user-interface.html#toolbar)中点击运行配置菜单并选择   编辑配置  。

2. 点击工具栏上的   添加新配置   ![](https://resources.jetbrains.com.cn/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))，然后选择   GraalVM Native Attach  。

3. 请指定以下数值：

|    连接字符串 (host:port)    |  将要附加到进程的主机和端口，格式如下：  `host:port` 。  |
|    使用模块的类路径    |  请选择将用于编译应用程序的模块类路径。  |
|    符号文件    |  [调试符号](https://www.graalvm.org/latest/reference-manual/native-image/debugging-and-diagnostics/DebugInfo/)的文件。 调试器使用这些信息将编译程序的二进制指令映射回原始源代码。  |
|    系统根    |     用于远程主机的系统库（例如 libc）调试符号的目录。 如果留空，调试器将在远程主机上搜索这些库的调试符号。     |
|    源映射    |  可选的特殊情况源映射。 例如，如果远程应用是从  `/tmp/buildserver/my_app/MyApp.java` 中的源码构建的，并且您本地拥有  `/home/me_user/my_app/MyApp.java` 中的源码，正确的映射将是：  `/tmp/buildserver/my_app/ , /home/me_user/my_app/MyApp.java`   |

> **Note:**
> 如需常见的运行配置设置，请参考 [运行/调试配置](run-debug-configuration.html)

在您设置好   GraalVM Native Attach   运行配置之后，请像往常一样运行本机可执行文件。 当目标进程启动后，启动您为调试创建的运行配置。

Procedure: 启动运行配置

* 在 [运行微件](guided-tour-around-the-user-interface.html#toolbar) 中选择运行配置，然后点击   调试  。

![主工具栏上的“Debug”按钮](https://resources.jetbrains.com.cn/help/img/idea/2026.3/native-debug-run-widget.png)

> **Tip:**
> 有关调试运行配置的一般信息，请参阅 [启动调试器会话](starting-the-debugger-session.html)

当调试器成功附加时，应用程序输出将显示在控制台中。

Procedure: 终止调试器会话

* 点击 ![停止按钮](https://resources.jetbrains.com.cn/help/img/idea/2026.3/app-client.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)) 并选择要终止的进程（如果有两个或更多）。

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

## Docker 镜像

您可以在 Docker 容器中调试 GraalVM 本机可执行文件时使用 [以下 Docker 镜像](https://hub.docker.com/r/jetbrains/graalvm-debugger)作为参考：

```DOCKERFILE
ARG JAVA_VERSION=21
FROM ghcr.io/graalvm/native-image-community:${JAVA_VERSION}
RUN microdnf update -y oraclelinux-release-el9 \
&& microdnf --enablerepo ol9_codeready_builder install -y gdb-gdbserver gcc maven \
&& microdnf clean all

```

有关运行和调试 Docker 镜像的步骤，请参阅 [运行目标](run-targets.html)。

## 从表达式创建对象

如果您要 [评估涉及创建新对象的表达式](examining-suspended-program.html#evaluating-expressions)，您需要使用以下选项构建应用程序：

```
-H:ReflectionConfigurationFiles=reflection-config.json

```

`reflection-config.json`  文件必须包含以下配置：

```JSON
[
    {
        "name" : "jdk.internal.misc.Unsafe",
        "methods": [
            { "name":  "getUnsafe" },
            { "name":  "allocateInstance" }
        ]
    }
]

```