# sbt

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

> **TL;DR**
> 必需插件：   Scala  ： [安装方法](get-started-with-scala.html#scala_plugin)

## 使用 sbt

当您导入或创建 sbt 项目后，您可以直接在编辑器中编辑其  `build.sbt`  文件。 在  `build.sbt` 中，您可以指定编译器选项、子项目的相关信息，还可以定义任务和设置。 每次您更改  `build.sbt`  文件时，您需要将更改与 IntelliJ IDEA 中的项目模型同步。

您可以配置   在构建脚本更改后同步项目   选项以自动同步对  `build.sbt`  所做的更改。 要访问此选项，请选择  `文件 | 设置 | 构建、执行、部署 | 构建工具` 。

若要进行手动同步，请使用  sbt projects  工具窗口工具栏上的相应操作： ![刷新](https://resources.jetbrains.com/help/img/idea/2026.3/app.actions.refresh.svg)。

请注意，任何 sbt 任务都可以附加在运行配置之前执行。

> **Note:**
> IntelliJ IDEA 还让您使用其他构建工具，如 [Gradle](gradle.html) 或 [Maven](maven-support.html) 来构建您的 Scala 项目。

## 打开一个现有的 sbt 项目

要创建新项目，请启动 [新建项目向导](new-project-wizard.html)，并按照向导中建议的步骤操作，例如选择   Scala   和   sbt  ；指定项目位置、JDK 以及 sbt 和 Scala 版本。 sbt 和 Scala 版本会自动获取。

在 IntelliJ IDEA 主屏幕上，点击   打开  。 如果已经打开了项目，请从主菜单中选择  `文件 | 打开` 。 然后，在对话框中选择一个包含您的 sbt 项目描述的文件  `build.sbt` 。 点击   OK  ，然后在下一个对话框中点击   选择作为项目  。

IntelliJ IDEA 在 IDE 中打开并同步 sbt 项目。 如果您在打开项目时需要调整导入选项，请参阅 [sbt settings](sbt.html)。

## 确保 sbt 和 Scala 版本兼容性

通常，您会在团队中共享项目，并需要使用特定版本的 sbt。 您可以在项目的  `build.properties`  文件中重写 sbt 版本。

创建或 [打开](#import_sbt)您的 sbt 工程。 在   项目  工具窗口中，在   源根  目录中，找到  `build.properties` 文件并在编辑器中打开它。 然后，在编辑器中明确指定您想在项目中使用的 sbt 版本。

```
sbt.version=xxx
```

重新导入您的项目。 （点击   sbt   工具窗口中的 ![](https://resources.jetbrains.com/help/img/idea/2026.3/app.actions.refresh.svg)。）

> **Note:**
> 当您尝试导入包含旧版本 sbt 的 sbt 项目时，您可能会遇到错误。 我们建议您升级到 sbt 1.0 及更高版本，这些版本与 Scala 2.12 版本兼容（需要 Java 8）。

## sbt 项目结构

当您创建或导入 sbt 项目时，IntelliJ IDEA 会生成以下 sbt 结构：

* sbt project（适当的构建），定义一个项目并包含 `build.sbt` 文件、 src 和 target 目录、模块；与常规项目相关的任何内容。 ![项目工具窗口](https://resources.jetbrains.com/help/img/idea/2026.3/sbt_main.png)

* 在 build 子目录中定义的 project 项目。 它包含构建定义的一部分附加代码。 ![sbt 源根](https://resources.jetbrains.com/help/img/idea/2026.3/sbt_source_root.png)

* 包含 sbt 任务、命令和设置的 sbt 工具窗口，您可以执行这些任务、命令和设置。 ![sbt 工具窗口](https://resources.jetbrains.com/help/img/idea/2026.3/sbt_tool_window_new.png)

> **Tip:**
> 有关 sbt 项目结构的更多信息，请参阅相关的 [sbt 文档](https://www.scala-sbt.org/1.x/docs/Organizing-Build.html)。

## 管理 sbt 项目

处理 sbt 项目时，请使用  `build.sbt`  文件对项目进行主要更改，因为 IntelliJ IDEA 将 sbt 配置视为单一事实来源。

每次您在编辑器中手动更改  `build.sbt`  时，您需要加载更改。 IntelliJ IDEA 会在编辑器右侧显示通知图标，建议   加载 sbt 更改  对项目所做的更改（ `Ctrl+Shift+O` (Windows), `Ctrl+Shift+O` (macOS), `Ctrl+Shift+O` (IntelliJ IDEA Classic (macOS)), `Ctrl+Shift+O` (macOS System Shortcuts), `Ctrl+Shift+O` (XWin), `Ctrl+Shift+O` (GNOME), `Ctrl+Shift+O` (KDE), `Ctrl+Shift+O` (Emacs), `Ctrl+Shift+O` (Sublime Text), `Ctrl+Shift+O` (Sublime Text (macOS)), `Ctrl+Shift+O` (Visual Studio), `Ctrl+Shift+O` (Visual Studio (macOS)), `Ctrl+Shift+O` (NetBeans), `Ctrl+Shift+O` (Eclipse), `Ctrl+Shift+O` (Eclipse (macOS))）。

![build.sbt 文件：加载 sbt 变更](https://resources.jetbrains.com/help/img/idea/2026.3/build_sbt_load_changes.png)

如果您想要控制项目的导入过程，您可以手动触发操作或配置自动重新加载过程。

Procedure: 重新加载 sbt 项目

1. 在 [sbt](sbt-tool-window.html) 工具窗口中，右键点击一个关联的项目。

2. 在上下文菜单中，选择   重新加载项目   ![重新加载项目图标](https://resources.jetbrains.com/help/img/idea/2026.3/app.actions.refresh.svg)。

调用此操作时，IntelliJ IDEA 会在   sbt   工具窗口中解析项目结构。

IntelliJ IDEA 无法只重新加载项目的一部分，而是会重新加载整个项目，包括子项目和依赖项。

> **Tip:**
> 要重新加载所有 sbt 项目，请点击工具栏上的 ![重新加载所有 sbt 项目的图标](https://resources.jetbrains.com/help/img/idea/2026.3/app.actions.refresh.svg)，在   sbt   工具窗口中。

Procedure: 配置自动重载

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))）中，转到  `构建、执行、部署 | 构建工具` 。

或者，在   sbt  工具窗口中，点击 ![构建工具设置](https://resources.jetbrains.com/help/img/idea/2026.3/app.expui.general.settings.svg)并选择   自动重新加载设置  选项。

![sbt 工具窗口](https://resources.jetbrains.com/help/img/idea/2026.3/sbt_auto_reload_settings.png)

2. 在   构建工具   设置中，指定以下选项：

![构建工具设置](https://resources.jetbrains.com/help/img/idea/2026.3/build_tools_reload_settings.png)

* 重新加载构建脚本中的更改 ：默认选中此选项。 如果要禁用自动重新加载并手动控制重新加载过程，请取消选中此复选框。

* 任何更改 ：如果希望在对 `build.sbt` 进行任何更改或发生外部更改后自动重新加载项目，请选择此选项。 每次您在编辑器中手动更改 sbt build 脚本时，都需要加载更改。 IntelliJ IDEA 会在编辑器右侧显示通知图标，建议 加载 sbt 更改 对项目所做的更改（ `Ctrl+Shift+O` (Windows), `Ctrl+Shift+O` (macOS), `Ctrl+Shift+O` (IntelliJ IDEA Classic (macOS)), `Ctrl+Shift+O` (macOS System Shortcuts), `Ctrl+Shift+O` (XWin), `Ctrl+Shift+O` (GNOME), `Ctrl+Shift+O` (KDE), `Ctrl+Shift+O` (Emacs), `Ctrl+Shift+O` (Sublime Text), `Ctrl+Shift+O` (Sublime Text (macOS)), `Ctrl+Shift+O` (Visual Studio), `Ctrl+Shift+O` (Visual Studio (macOS)), `Ctrl+Shift+O` (NetBeans), `Ctrl+Shift+O` (Eclipse), `Ctrl+Shift+O` (Eclipse (macOS))）。 ![sbt 构建脚本](https://resources.jetbrains.com/help/img/idea/2026.3/sbt_build_script.png) 使用 任何更改 选项，IntelliJ IDEA 将自动重新加载所有更改。

* 外部更改 ：选择此选项后，IntelliJ IDEA 仅会在发生 VCS 更改以及在 IDE 外部对构建文件进行更改后自动重新加载项目。

Procedure: 链接外部 sbt 项目

1. 打开您的  `build.sbt` 。

2. 请指定以下代码：

```
val localDep = RootProject(file("/path/to/project"))
                     
```

在这种情况下，  `localDep`  是位于文件系统某处的项目，并将作为模块导入。

3. 重新加载您的项目。 （点击   sbt   工具窗口中的 ![](https://resources.jetbrains.com/help/img/idea/2026.3/app.actions.refresh.svg)。）

IntelliJ IDEA 会在   项目  工具窗口以及   sbt  工具窗口中显示已添加的项目。

Procedure: 将子项目或模块添加到 sbt 项目

1. 在编辑器中打开  `build.sbt` 。

2. 例如：

```SCALA
lazy val sampleModule = (project in file("sampleModule"))
```

在这种情况下，  `"sampleModule"`  是您要添加的子项目。 您可以指定多个子项目。

3. 重新导入您的项目。 （点击   sbt   工具窗口中的 ![重新导入项目](https://resources.jetbrains.com/help/img/idea/2026.3/app.actions.refresh.svg)。）

IntelliJ IDEA 生成一个包含适当信息的子项目目录，并在   项目   和   sbt   工具窗口中显示。

Procedure: 更新子项目

如果您希望在更改 Scala 版本时子项目自动更新，请为每个子项目指定  `commonSettings` 和  `设置` 方法调用。

1. 打开  `build.sbt` 。

2. 例如，指定以下代码：

```SCALA
lazy val commonSettings = Seq(
    organization := "com.example",
    version := "0.1.0-SNAPSHOT",
    scalaVersion := "2.12.6"
)
lazy val moduleSample = (project in file("moduleSample"))
        .settings(
            commonSettings
        )

```

适当的 Scala 版本将作为依赖项添加到子项目目录中的   项目  工具窗口和   sbt  工具窗口。

## 使用 sbt shell

在项目启动时， sbt 项目中嵌入了一个 sbt shell。 您可以使用 sbt shell 来执行 sbt 命令和任务，运行和调试您的项目。

Procedure:

* 要启动 sbt shell，请按  `Ctrl+Shift+S` （Windows）或  `⌘+⇧+S` （macOS）。 或者，点击屏幕底部工具栏上的 ![sbt shell](https://resources.jetbrains.com/help/img/idea/2026.3/sbt_shell_icon.png)。

* 要使用 sbt shell 进行构建和导入过程，选择   使用 sbt shell   部分，位于 [sbt 设置](#sbt_settings) 中，并执行 [使用 sbt shell 运行 Scala 应用程序](run-debug-and-test-scala.html#run_sbt_scala_app) 部分中描述的步骤。

> **Note:**
> 推荐使用 sbt 版本 0.13.16.+ / 1.0.3.+。

* 如需使用 sbt shell 进行调试，请参阅 [使用 sbt shell 进行调试](run-debug-and-test-scala.html#sbt_shell_debug)一节。

* 要从 sbt shell 运行您的测试：

1.  打开运行/调试配置 (  `运行 | 编辑配置` )。

2.  创建一个 [测试配置](run-debug-and-test-scala.html#run_debug_use_sbt)并从可用设置中选择   使用 sbt  选项。

> **Tip:**
> 您也可以通过在 sbt shell 中输入  `test`  或  `test/Only`  命令来运行它。

## 运行 sbt 任务

> **Tip:**
> 您可以执行 sbt  命令  和  设置 ，就像执行 [sbt 任务](#sbt_task) 一样。

Procedure:

* 您可以通过从   sbt 任务   目录中选择所需的任务来运行 sbt 任务，并在   sbt   工具窗口中查看。

* 您可以在 sbt shell 中手动输入任务（支持代码补全），然后直接从那里运行。

* 您可以为任务创建运行配置。 例如，您可以创建一个不在   sbt   工具窗口任务列表中的自定义任务。

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)) 打开运行配置。

2.  指定运行配置设置并点击   OK  。 如果您需要，可以在运行配置之前添加另一配置或任务。 点击 !["添加"图标](https://resources.jetbrains.com/help/img/idea/2026.3/app.expui.general.add.svg) 在   启动前   部分中，从打开的列表中选择您需要执行的内容。

* 当您在无干扰模式（没有工具栏和工具窗口）下工作时，您可以从   运行任何内容  窗口运行 sbt 任务或命令。 按两次 `Ctrl` (Windows), `Ctrl` (macOS), `Ctrl` (IntelliJ IDEA Classic (macOS)), `Ctrl` (macOS System Shortcuts), `Ctrl` (XWin), `Ctrl` (GNOME), `Ctrl` (KDE), `Ctrl` (Emacs), `Ctrl` (Sublime Text), `Ctrl` (Sublime Text (macOS)), `Ctrl` (Visual Studio), `Ctrl` (Visual Studio (macOS)), `Ctrl` (NetBeans), `Ctrl` (Eclipse), `Ctrl` (Eclipse (macOS)) 将其打开，输入命令，然后按 `Enter` (Windows), `⏎` (macOS), `⏎` (IntelliJ IDEA Classic (macOS)), `⏎` (macOS System Shortcuts), `Enter` (XWin), `Enter` (GNOME), `Enter` (KDE), `Enter` (Emacs), `Enter` (Sublime Text), `⏎` (Sublime Text (macOS)), `Enter` (Visual Studio), `⏎` (Visual Studio (macOS)), `Enter` (NetBeans), `Enter` (Eclipse), `⏎` (Eclipse (macOS))。

IntelliJ IDEA 在   sbt shell   窗口中显示结果。

## 使用 sbt 设置

使用 sbt 设置来配置 sbt 项目的构建和运行操作、sbt 版本、项目更改导入等。

Procedure: 访问 sbt 设置

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)) 打开设置，然后选择  `构建、执行、部署｜sbt` 。

2. 或者，点击 ![sbt 设置](https://resources.jetbrains.com/help/img/idea/2026.3/app.expui.general.settings.svg) 工具窗口的工具栏上的   sbt   以访问 SBT 设置。

窗口分为两个部分：   常规设置   和   sbt 项目  。

![sbt 通用设置](https://resources.jetbrains.com/help/img/idea/2026.3/sbt_settings.png)

### 常规设置

在   常规设置   部分，可以配置以下选项：

|  条目  |  描述  |
| --- | --- |
|    JRE    |  选择用于运行此项目的 JRE，可以从下拉列表中选择，也可以提供自定义位置。 它优先于默认的项目 SDK。  |
|    最大堆大小    |  指定 sbt 启动时分配给它的最大堆大小。  |
|    VM 参数    |  指定要传递给 sbt 的 JVM 参数。 可以在  `JAVA_OPTS`  环境变量中，或在项目根目录下的  `.jvmopts`  文件中定义 JVM 选项。 在 IntelliJ IDEA 设置中配置的选项优先级最高，其次是  `.jvmopts`  文件中的选项，然后是  `JAVA_OPTS`  环境变量中的选项。  |
|    SBT 选项    |  指定要传递给 sbt 的 sbt 选项。 要查看所有可用选项，请运行  `sbt --help` 。 可以在  `SBT_OPTS`  环境变量中，或在项目根目录下的  `.sbtopts`  文件中定义 sbt 选项。 这些选项的优先级遵循与 JVM 形参相同的规则。  |
|    环境变量    |  指定要 inject 到 sbt 进程中的环境变量。  |
|    启动器(sbt-launch.jar)    |  指定自定义 sbt 启动器。 默认情况下，IntelliJ IDEA 使用捆绑的 sbt-launch.jar。  |

### sbt 项目

在   sbt 项目   部分，可以配置以下选项：

|  条目  |  描述  |
| --- | --- |
|    下载    |     选择一个选项，以便在从 sbt 重新加载项目时下载源代码：        * 库源 ：下载项目库依赖项的源代码。    * sbt 源 ：下载 sbt 和 sbt 插件的源代码。    |
|    将交叉编译的 Scala 3 / Scala 2 项目作为 Scala 2 打开    |  选择此选项，将同时针对 Scala 2 和 Scala 3 交叉编译的项目作为 Scala 2 打开。  |
|    使用单独的编译器输出路径    |  选择此选项，使用与 sbt 所用目录不同的类文件目录进行编译。  |
|    在项目同步期间生成托管源    |     指示 sbt 在项目同步期间生成由项目中启用的源生成器管理的源代码（例如 sbt-buildinfo、abt-twirl 和其他类似的 sbt 插件）。 也可作为操作使用。      > **Tip:** > 如果源代码生成耗时过长，请禁用此设置。    |
|    sbt shell    |     使用复选框控制在项目重新加载和构建时是否使用 sbt shell。      > **Tip:** > 使用 sbt shell 可以加快重新加载速度，但需要 IntelliJ IDEA 将 shell 保留在内存中。    |
|    启用调试    |  选择此选项，将 sbt shell 作为可调试进程启动。 这样便可调试在 sbt shell 中运行的 sbt 插件代码和测试。  |

如需检查最常见的 sbt 问题及解决方法，请参阅 [sbt 故障排除](troubleshoot-common-scala-issues.html) 部分。

## 对 sbt 的软件包检查器支持

软件包检查器是一个插件，用于检查第三方依赖项是否存在已知漏洞。 如果有可用的安全版本，则会建议使用该版本，以提高代码的安全性。 它还会扫描源代码中易受攻击的 API 调用，以高亮显示最关键的问题。 该插件与 IntelliJ IDEA 捆绑在一起。

软件包检查器识别出的问题会报告在   问题   工具窗口的  `存在漏洞的依赖项`  选项卡中。 该插件还提供  `分析 | 漏洞依赖项`  操作。

在此可以看到软件包检查器如何描述  `org.apache.commons % commons.io % 1.3.2`  中的漏洞：

![软件包检查器存在漏洞的依赖项视图](https://resources.jetbrains.com/help/img/idea/2026.3/sbt_package_checker.png)

有关更多信息，请参阅 [查找易受攻击和恶意依赖项](package-analysis.html)