openidea/docs/zh/guide/run.mdx

---
title: "运行配置"
description: "创建、编辑和启动运行配置，从装订区运行代码，并在“运行”工具窗口查看输出。"
---

运行配置描述了“怎么启动一样东西”：一条命令行、一个主类、一组测试、一个 npm 脚本或一个 Docker 容器。OpenIDEA 里的运行配置分三类：

- **检测到的**配置：从项目的构建文件读取，构建文件一变就重新读取。
- **用户**配置：你在“运行/调试配置”中新建或保存的配置。
- **临时**配置：运行光标处的代码或当前文件时自动生成，只保留最近 5 个。

当前选中的配置显示在标题栏的运行微件里，旁边是运行、调试和停止按钮。

## 检测到的配置

打开项目时，OpenIDEA 会扫描构建文件（文件夹里包含多个项目时也会扫描嵌套项目），列出能运行的内容：

| 构建文件                                                                                        | 生成的配置                                                                                                                         |
| ----------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `package.json`                                                                                  | 每个 `scripts` 条目一个，使用锁文件对应的包管理器（npm、pnpm、yarn 或 bun）。`test`、`test:*`、`jest`、`vitest` 脚本会标记为测试。 |
| `deno.json` / `deno.jsonc`                                                                      | Deno task                                                                                                                          |
| `Cargo.toml`                                                                                    | 每个二进制一个 `cargo run`，以及 `cargo test`、`cargo build`；包含 workspace 成员                                                  |
| `build.gradle(.kts)` / `pom.xml`                                                                | Gradle、Maven 运行配置                                                                                                             |
| `go.mod` / `go.work`                                                                            | Go 程序和测试                                                                                                                      |
| `pyproject.toml`、`setup.py`、`requirements.txt`、`pytest.ini`、`tox.ini`、`manage.py`、`.venv` | Python 程序、pytest、Django                                                                                                        |
| `composer.json`、`phpunit.xml`                                                                  | PHPUnit                                                                                                                            |
| Ruby 项目（`Gemfile`、`Rakefile` 等）                                                           | Rake task、RSpec、Minitest                                                                                                         |
| `CMakeLists.txt`                                                                                | CMake 构建和运行目标                                                                                                               |
| `.csproj` / `.sln`                                                                              | .NET 项目和测试                                                                                                                    |
| `Makefile`、`justfile`                                                                          | Make、just 目标                                                                                                                    |
| `project.godot`                                                                                 | Godot                                                                                                                              |

插件也可以提供检测器。构建文件变化时检测到的配置会自动重新加载；需要手动刷新时，在“查找操作”里运行 **重新加载运行配置**。

编辑检测到的配置后，改动会保存为一个同名覆盖的用户配置。删除检测到的配置，则会在当前工作区里隐藏它。

## 在编辑器里运行

<Steps>
  <Step title="点击装订区图标">
    Rust、Go、Java、Kotlin、Scala、Groovy、JavaScript / TypeScript、Python、PHP、Ruby、C# 和 C / C++ 中的 `main`
    函数、测试和测试类旁边会出现 ▶ 图标，`package.json` 的 `scripts` 条目旁也有。点击后可以选 **运行 '…'**、**调试
    '…'**、其他执行器（如覆盖率、性能分析）或 **修改运行配置…**。
  </Step>
  <Step title="或者运行上下文">
    **运行 › 运行上下文配置**
    会运行光标处的测试或程序，或者当前文件。编辑器、编辑器标签页和项目视图的右键菜单里也有对应的 **运行 '…'**、**调试
    '…'** 和 **更多运行/调试**。在项目视图里对目录使用时，会运行该目录下的测试。
  </Step>
  <Step title="保存下来">上下文运行生成的是临时配置。打开配置选择器，选择 **保存“…”配置**，就能把它转成用户配置。</Step>
</Steps>

测试运行过后，装订区图标会变成绿色或红色，表示该测试上一次的结果。

## 启动配置

| 操作                               | macOS        | Windows / Linux  |
| ---------------------------------- | ------------ | ---------------- |
| **运行**（选中的配置）             | `⌃R`         | `Shift+F10`      |
| **调试**（选中的配置）             | `⌃D`         | `Shift+F9`       |
| **运行上下文配置**                 | `⌃⇧R`        | `Ctrl+Shift+F10` |
| **调试上下文配置**                 | `⌃⇧D`        | —                |
| **运行…**（选择配置并运行）        | `⌃⌥R`        | `Alt+Shift+F10`  |
| **调试…**（选择配置并调试）        | `⌃⌥D`        | `Alt+Shift+F9`   |
| **编辑配置…**                      | `⌃⌥⇧R`       | —                |
| **停止**                           | `⌘F2`        | `Ctrl+F2`        |
| **重新运行**（在“运行”工具窗口中） | `⌘R`         | `Ctrl+F5`        |
| **运行任何内容…**                  | 连按两次 `⌃` | 连按两次 `Ctrl`  |

在配置选择器里按住 `Shift` 选择，会以调试方式启动。第一项 **当前文件** 会运行当前编辑器里的文件。

**停止** 会停止当前聚焦的运行标签页的进程；在其他地方触发时，如果只有一个进程在跑就直接停止，有多个时列出它们并提供 **全部停止**。进程不退出时再按一次停止即可强制结束。

**运行任何内容…** 可以在项目目录运行一条 shell 命令、一个运行配置或一个构建工具目标。以 `mvn` 或 `gradle` 开头的命令会补全目标和任务。

## 编辑配置

打开 **运行 › 编辑配置…**（运行微件的菜单里也有）。“运行/调试配置”对话框左侧按文件夹列出所有配置。

- **添加新配置**（`⌘N` / `Ctrl+N`，或 `Alt+Insert`）：弹出配置类型列表。
- **复制配置**、**创建新文件夹**、**上移** / **下移**：整理列表。按 `Delete` 删除选中项。
- **编辑配置模板…**：设置每种类型新建配置时的默认值。
- **存储为项目文件**：决定配置保存在哪里（见下文“配置的存储位置”）。
- **修改选项**（`⌥M` / `Alt+M`）：往表单里加可选字段。

### 配置类型

| 类型                                                  | 运行的内容                                                      |
| ----------------------------------------------------- | --------------------------------------------------------------- |
| **Shell 脚本**                                        | 脚本文件、脚本文本或命令行                                      |
| **程序**                                              | 带参数的可执行文件                                              |
| **npm**                                               | 用 npm、pnpm、yarn 或 bun 运行 `package.json` 脚本              |
| **Gradle** / **Maven**                                | Gradle 任务或 Maven 目标，可选择通过 wrapper 运行               |
| **应用程序** / **JAR 应用程序** / **Spring Boot**     | Java 主类、可执行 JAR、Spring Boot 应用                         |
| **Tomcat 服务器**                                     | 在本地 Tomcat 里运行 WAR 应用                                   |
| **pytest** / **Django 测试**                          | pytest 测试、`manage.py test`                                   |
| **Ruby 语言** / **Rake 任务** / **RSpec 测试**        | Ruby 脚本、Rake 任务、RSpec 用例                                |
| **PHPUnit**                                           | PHPUnit 测试                                                    |
| **Go 构建** / **Go 测试**                             | Go 应用、Go 测试                                                |
| **.NET 项目** / **dotnet test**                       | 按启动配置文件运行 .NET 项目、.NET 测试                         |
| **Godot**                                             | Godot 项目的主场景或指定场景                                    |
| **Dockerfile** / **Docker 镜像** / **Docker Compose** | 从 Dockerfile 构建并运行容器、从镜像启动容器、启动 Compose 服务 |
| **复合**                                              | 同时运行多个配置                                                |

调试器另外提供只用于附加的类型，如 **远程 JVM 调试**、**Go 远程**、**Python 远程调试 (debugpy)**、**附加到 Node.js**、**PHP 远程调试 (Xdebug)**，详见[调试](/zh/guide/debugging)。插件也可以注册自己的类型。

### 通用字段

- **运行于**：本地计算机，或在 **设置 › 构建、执行、部署 › 运行目标** 中添加的 SSH 主机。运行目标上不支持调试。参见 [SSH](/zh/guide/remote/ssh)。
- **工作目录**：相对于项目根目录，留空即项目根目录。
- **环境变量**：`VAR=value` 形式，用 `;` 分隔。点旁边的列表按钮打开“环境变量”对话框，可以关闭 **包括系统环境变量**。
- **调试适配器**：按“调试”时这个配置使用哪个调试器（如 `debugpy`、`js-debug`、`codelldb`、`delve`）。

### 环境变量与 `.env` 文件

打开 **修改选项 › ".env" 文件路径** 后，可以加载一个或多个 `.env` 文件（相对项目根目录，用 `;` 分隔）。支持 `KEY=value`、`export` 前缀、`#` 注释、带引号的值以及 `${VAR}` 引用。配置里直接写的变量优先级高于 `.env` 文件。

开启 **包括系统环境变量** 时，进程还会继承 IDE 的环境变量和登录 shell 里的变量。

### 修改选项

| 分组     | 选项                                                                                                                  |
| -------- | --------------------------------------------------------------------------------------------------------------------- |
| 操作系统 | **允许多个实例**、**重定向输入**、**".env" 文件路径**、**在输出控制台中模拟终端**                                     |
| 日志     | **将控制台输出保存到文件**、**当消息输出到 stdout 时显示控制台**、**当消息输出到 stderr 时显示控制台**                |
| 测试     | **在测试运行器中显示结果**                                                                                            |
| 启动前   | **构建**（Java、Maven、Gradle）、**添加启动前任务**、**启动时打开运行/调试工具窗口**、**启动时聚焦运行/调试工具窗口** |

**在输出控制台中模拟终端** 会把进程放在终端里运行，适合需要 TTY 的程序；它和 **重定向输入** 不能同时使用。

### 启动前任务

在 **修改选项 › 添加启动前任务** 中添加，进程启动前按顺序执行：

- **运行另一个配置**
- **构建项目**、**构建模块**、**构建工件**、**构建 .NET 项目**（仅 .NET 配置）
- **运行外部工具**
- **运行 Shell 命令**
- **激活工具窗口**

Java、Maven、Gradle 配置还可以通过 **构建** 选项决定启动前怎么构建：**自动（增量）**、**构建（Make）**、**重新构建**、**不构建** 或 **构建，不检查错误**。

Maven 模块在 **自动** 和 **构建（Make）** 时由 jdtls（ECJ）构建，**重新构建** 时由 Maven 构建。打开 **设置 › 构建、执行、部署 › Maven › 将 IDE 构建/运行操作委托给 Maven** 后每次都用 Maven（项目的 `javac`）构建；编辑器的 **问题** 仍来自 jdtls。

### 复合配置

**复合** 配置一次启动多个配置：运行它会启动全部成员，调试它会逐个调试每个成员。在运行微件上点停止会把它们一起停掉。

## “运行”工具窗口

每次启动都会在底部的 **运行** 工具窗口里开一个标签页。工具栏有 **重新运行**、**调试**、**重新运行失败的测试**（测试运行时）、**更新应用**、**查找…**、**滚动到末尾**、**软换行**、**全部清除** 和 **编辑配置…**。

- 输出里的文件路径和堆栈帧都可以点击跳转。
- 重复的行可以折叠。折叠规则、缓冲区大小和控制台编码在 **设置 › 构建、执行、部署 › 控制台** 中配置。
- 日志行可按级别着色（`ERROR`、`WARN`、`INFO`、`DEBUG`、`TRACE`）；程序自行输出的颜色保持不变。默认关闭，可在 **设置 › 构建、执行、部署 › 控制台** 开启并修改颜色。
- 测试运行时，标签页会在输出旁显示测试树，参见[测试](/zh/guide/testing)。

**设置 › 构建、执行、部署 › 运行/调试** 控制进程启动时是否打开工具窗口、重新运行或关闭正在运行的标签页前是否确认，以及按停止后等待进程退出的时间。

## 导入已有配置

“查找操作”里有两个导入操作（对话框里也有入口）：

- **从 .vscode/launch.json 导入运行配置**：导入 Python 和 Node.js 的 launch / attach 配置以及 compounds。`${workspaceFolder}`、`${env:NAME}` 这类含义固定的变量会被替换；用到 `${file}`、`${input:…}`、`${command:…}` 的条目会被跳过。
- **从 JetBrains 导入运行配置（.run、.idea）**：读取 `.run/*.run.xml`、`.idea/runConfigurations/*.xml` 和 `.idea/workspace.xml`。Python、Django、pytest、npm、Jest、Vitest、Node.js、Shell Script、Application、JAR Application、Spring Boot、Go 和复合配置会被转换，其他类型跳过。

导入完成后会有通知告诉你导入了多少、哪些被跳过以及原因。

## 配置的存储位置

| 文件                       | 内容                                                                        |
| -------------------------- | --------------------------------------------------------------------------- |
| `.openidea/run.toml`       | 勾选了 **存储为项目文件** 的配置和配置模板。提交到仓库即可与团队共享。      |
| `.openidea/run.local.toml` | 其余配置，以及你删除掉的检测配置。该文件会自动加入 `.openidea/.gitignore`。 |

两个文件都是普通 TOML，可以手动编辑：

```toml
[[configurations]]
id = "user:server"
name = "Server"
kind = "shell"
command = "cargo"
args = ["run", "--release"]
cwd = "server"
env = { RUST_LOG = "debug" }
env-files = [".env"]
before-launch = [{ kind = "build" }, { kind = "run", target = "user:migrate" }]

[[templates]]
kind = "npm"
env = { NODE_ENV = "development" }
```

文件在磁盘上变化后会自动重新加载。