# Makefile 项目

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

在 CLion 中对 [Makefile](https://www.gnu.org/software/make/manual/make.html) 项目的全面支持仍在进行中。 使用链接到 [CPP-494](https://youtrack.jetbrains.com/issue/CPP-494) 的工单留下您的反馈并为所需功能投票。

> **Tip:**
> 如果您的 Makefile 项目需要预配置，请参阅 [Autotools](gnu-autotools.html)。

Procedure: 打开一个 Makefile 项目

1. 从主菜单中选择  `文件 | 打开` 。

2. 将 CLion 指向包含顶层 Makefile 的文件夹。

3. 系统将提示您清理项目：

![加载项目对话框](https://resources.jetbrains.com/help/img/idea/2026.3/cl_makefile_cleandialog.png)

加载项目需要清理，因为 Make 构建是增量式的，仅编译更新的文件。 在未清理的项目上运行时，重新加载将遗漏所有未更改的文件，并可能导致运行不正确。

如果您希望在不清理的情况下加载，请取消选中   清理项目   复选框。 您可以稍后清理并 [重新加载](#manual-reload) 项目（例如，在执行必要的引导操作后）。

4. CLion 开始加载项目，并在   构建   工具窗口中显示进度和状态：

![在构建工具窗口中的项目加载状态](https://resources.jetbrains.com/help/img/idea/2026.3/cl_makefile_syncwindow.png)

加载过程中可能会出现警告消息，但如果加载以绿色勾号 ![加载成功指示器](https://resources.jetbrains.com/help/img/idea/2026.3/app.actions.commit.svg) 完成并显示在项目名称旁边，则表示加载成功。 如果您的项目未正确加载，请查看 [故障排除](#troubleshooting) 部分。

Procedure: 为已打开的项目加载一个 Makefile

您还可以将项目作为文件夹打开，并稍后加载  `Makefile` 。 例如，如果您的项目需要某些预配置步骤或运行脚本以准备最终的 Makefile，而在 CLion 中打开项目时尚未准备好，这将非常有用。

准备好后，要加载  `Makefile` ，请在编辑器中打开它并点击通知中的   加载 Makefile 项目   链接：

![加载 Makefile 项目通知](https://resources.jetbrains.com/help/img/idea/2026.3/cl_makefile_load_notification.png)

或者，使用项目树中文件上下文菜单中的   加载 Makefile 项目   操作。

> **Note:**
> 在 VCS 下处理 Makefile 项目时，请考虑不要共享  `.iml`  文件，因为它将在导入时重新生成。 有关更多信息，请参阅 [此说明](https://intellij-support.jetbrains.com/hc/en-us/articles/206544839-How-to-manage-projects-under-Version-Control-Systems)。

## 配置自动重新加载

默认情况下，CLion 不会自动更新或重新加载您的项目，除非发生外部事件（如 VCS 更新）。 您可以在   构建工具   设置中更改此行为。

Procedure:

1. 转到  `设置 | 构建、执行、部署 | 构建工具` 。

2. 选择一个自动重新加载选项：

![自动重新加载设置](https://resources.jetbrains.com/help/img/idea/2026.3/cl_autoreload_settings.png)

* 任何更改 - 在 Makefile 中的任何更改时触发项目重新加载。

* 外部更改 （默认）- 您的项目仅在外部事件（如 VCS 更新）时重新加载。 如果发生其他更改（例如，添加新文件），您将在 Makefile 上收到通知： ![Makefile 重新加载通知](https://resources.jetbrains.com/help/img/idea/2026.3/cl_makefile_reload_message.png)

> **Tip:**
> 此设置适用于每个项目。 应为每个 Makefile、 [编译数据库](compilation-database.html)或 [Gradle](gradle-support.html) 项目单独配置自动重新加载选项。

## 手动重新加载

除了自动选项，您还可以手动重新加载项目：

* 从主菜单中的 `工具 | Makefile` 调用 `重新加载 Makefile 项目` 或 `清理并重新加载 Makefile 项目` 。

* 或者，在构建工具窗口中点击 ![重新加载图标](https://resources.jetbrains.com/help/img/idea/2026.3/app-client.expui.general.refresh.svg) 或 ![清理并重新加载图标](https://resources.jetbrains.com/help/img/idea/2026.3/app.actions.forceRefresh.svg)： ![构建工具窗口中的项目重新加载图标](https://resources.jetbrains.com/help/img/idea/2026.3/cl_makefile_reload_icon.png)

> **Note:**
> 您的项目可能还需要在修改后执行 [./configure](https://en.wikipedia.org/wiki/Configure_script) 步骤，以获取更新的 Makefile。

## 调整项目设置

使用  `设置 | 构建、执行、部署 | Makefile`  对话框控制您的项目设置。

![Makefile 设置](https://resources.jetbrains.com/help/img/idea/2026.3/cl_makefile_settings.png)

* 工具链 在这里，您可以选择用于加载 Makefile 项目的工具链。 请注意，NMake [当前不受支持](#issues-limitations)，因此您无法直接使用 [Visual Studio 工具链](quick-tutorial-on-configuring-clion-on-windows.html#MSVC)。 要使用它，您需要使用 GNU Make 单独构建项目。 如果您选择的工具链包含非默认编译器（在 C 编译器 和 C++ 编译器 字段中显式配置），它们也会传递到 `make` 。 > **Note:** > Windows 的特定详细信息： > > > > * 您的 Makefile 可能包含工具的完整路径。 在这种情况下，请确保选择具有相同路径的相应工具链。 > > * 使用 [MinGW](quick-tutorial-on-configuring-clion-on-windows.html#MinGW) 工具链时，请检查路径中是否不包含空格。 如有必要，请使用 `~` 表示法，例如 `C:\PROGRA~1\mingw-w64\...` 。

* 构建选项 在此字段中，您可以为项目构建提供额外的 [make 选项](https://www.gnu.org/software/make/manual/html_node/Options-Summary.html)。 这些选项不会影响项目重新加载。

* 命令 在此字段中，您可以调整预配置参数。 请参阅 [预配置（GNU Autoconf）](gnu-autotools.html#autoconf)。

* 参数 这些参数由 CLion 在调用 `make` 命令时使用，用于提取项目信息、清理项目或搜索构建目标。

* 构建目标 和 清理目标 这些目标与 `make` 命令一起使用，以提取项目信息。 如果您将 构建目标 字段留空，CLion 将采用项目顶层 Makefile 中指定的第一个目标。 此外，这里指定的目标在您从 [构建操作](build-actions.html#buildactions-makefiles) 菜单调用 构建项目 或 重新构建项目 时也会使用。

您可以从   构建   工具窗口快速访问 Makefile 设置对话框。 从上下文菜单中选择   Makefile 设置   或点击 !["设置"图标](https://resources.jetbrains.com/help/img/idea/2026.3/app.expui.general.settings.svg)：

![从构建工具窗口访问 Makefile 设置](https://resources.jetbrains.com/help/img/idea/2026.3/cl_makefile_settings_fromtw.png)

### 高级设置

更多 Makefile 项目的设置可在  `设置 | 高级设置`  中找到：

![Makefile 项目的高级设置](https://resources.jetbrains.com/help/img/idea/2026.3/cl_makefile_advancedsettings.png)

> **Tip:**
> 请参阅 [高级设置](advanced-settings.html) 了解更多信息。

## 运行/调试 Makefile 应用程序

CLion 会为顶层 Makefile 中的每个目标自动创建一个 [Native Application](run-debug-configuration-makefile-application.html) 配置：

![自动创建的 Native Application 配置](https://resources.jetbrains.com/help/img/idea/2026.3/cl_makefile_targetconfigs_autocreated.png)

在创建配置时，CLion 会过滤掉以下目标：

* `clean` 目标。

* 与对象文件 ( `.o` ) 对应的目标。

* 以未知文件扩展名结尾的目标（例如， `.d` ）。

您可以自定义自动创建的配置，或在  `编辑配置`  对话框中创建新的配置（见下文）。

Procedure: 创建一个 Native Application 配置

1. 在主菜单中，转到  `运行 | 编辑配置` ，点击 ![](https://resources.jetbrains.com/help/img/idea/2026.3/app.expui.general.add.svg)，然后从模板列表中选择   原生应用程序  ：

![添加一个 Native Application 配置](https://resources.jetbrains.com/help/img/idea/2026.3/cl_makefile_addconfig.png)

2. 在   目标   字段中，您可以选择一个检测到的目标：

![为 Native Application 配置选择目标](https://resources.jetbrains.com/help/img/idea/2026.3/cl_makefiles_rdconfig_targets.png)

另一种选择是设置一个类型为   生成   的自定义构建目标。 点击 ![](https://resources.jetbrains.com/help/img/idea/2026.3/app.actions.inlayGear.svg)，位于   目标   字段旁边，添加 ( ![](https://resources.jetbrains.com/help/img/idea/2026.3/app.expui.general.add.svg)) 一个新的   生成   目标，并填写参数：

![为 Native Application 配置自定义目标](https://resources.jetbrains.com/help/img/idea/2026.3/cl_makefile_customtargets.png)

![为 Native Application 配置自定义目标](https://resources.jetbrains.com/help/img/idea/2026.3/cl_makefile_customtargets_2.png)

3. 在   可执行文件   字段中，提供二进制文件的完整路径。

> **Note:**
> 如果您计划调试应用程序，请确保二进制文件包含调试符号。 例如，您可以在 Makefile 中将  `-g`  添加到  `CXXFLAGS` 。

要 [远程](remote-projects-support.html) 运行/调试，请提供  远程  机器上二进制文件的路径。 请注意，远程路径需要手动设置。

4. 原生应用程序   模板的其他设置在 [参考页面](run-debug-configuration-makefile-application.html) 中有描述。

Procedure: 运行一个 Native Application 配置

在切换器中选择所需的配置，然后使用以下选项之一：

* 点击 ![运行 按钮](https://resources.jetbrains.com/help/img/idea/2026.3/app.actions.execute.svg) 。

* 按下 `Shift+F10` (Windows), `⌃ R` (macOS), `⇧ F10` (IntelliJ IDEA Classic (macOS)), `⌥ ⇧ R` (macOS System Shortcuts), `Shift+F10` (XWin), `Shift+F10` (GNOME), `Shift+F10` (KDE), `Shift+F10` (Emacs), `Shift+F10` (Sublime Text), `Shift+F10` (Sublime Text (macOS)), `⌘ ⌥ ⇧ R` (Xcode), `Ctrl+F5` (Visual Studio), `⌃ F5` (Visual Studio (macOS)), `Ctrl+F5` (ReSharper), `⌃ F5` (ReSharper (macOS)), `Ctrl+R` (QtCreator), `⌘ R` (QtCreator (macOS)), `F6` (NetBeans), `Alt+Shift+X` (Eclipse), `⌘ ⇧ F11` (Eclipse (macOS))。

* 从主菜单中选择  `运行 | 运行“选定配置”` 。

Procedure: 调试一个 Native Application 配置

在开始调试会话之前，请确保在 [配置](#create-makefile-config) 中指定的二进制文件包含调试符号。

在切换器中选择所需的配置，然后使用以下选项之一：

* 点击 ![“运行”按钮](https://resources.jetbrains.com/help/img/idea/2026.3/app.actions.startDebugger.svg) 工具栏。

* 按下 `Shift+F9` (Windows), `⌃ D` (macOS), `⇧ F9` (IntelliJ IDEA Classic (macOS)), `⌥ ⇧ D` (macOS System Shortcuts), `Shift+F9` (XWin), `Shift+F9` (GNOME), `Shift+F9` (KDE), `Shift+F9` (Emacs), `Shift+F9` (Sublime Text), `⌃ D` (Sublime Text (macOS)), `⌘ R` (Xcode), `Alt+F5` (Visual Studio), `⌥ F5` (Visual Studio (macOS)), `Alt+F5` (ReSharper), `⌥ F5` (ReSharper (macOS)), `F5` (QtCreator), `⌘ Y` (QtCreator (macOS)), `Ctrl+F5` (NetBeans), `Alt+Shift+D` (Eclipse), `⌘ F11` (Eclipse (macOS))。

* 从主菜单中选择  `运行 | 调试“选定的配置”` 。

## 运行 Makefile 目标

您可以使用边栏菜单快速为特定目标调用  `make` ：

![运行目标的边栏菜单](https://resources.jetbrains.com/help/img/idea/2026.3/cl_makefiles_gutter.png)

或者，您可以从   生成   工具窗口 (  `视图 | 工具窗口 | make` ) 运行目标。 双击一个目标或选择它，然后点击 ![](https://resources.jetbrains.com/help/img/idea/2026.3/app.actions.execute.svg)：

![从 make 工具窗口运行目标](https://resources.jetbrains.com/help/img/idea/2026.3/cl_make_tool_window.png)

执行任何这些操作后，CLion 会创建一个 [临时配置](run-debug-configuration.html)，类型为 [Makefile Target](makefile-target-configuration.html)。 您可以自定义它，或在  `编辑配置`  对话框中基于相同模板创建新的配置（见下文）。

Procedure: 创建一个 Makefile Target 配置

* 在主菜单中，转到  `运行 | 编辑配置` ，点击 ![](https://resources.jetbrains.com/help/img/idea/2026.3/app.expui.general.add.svg)，然后从模板列表中选择   Makefile 目标  ：

![添加一个 Makefile Target 配置](https://resources.jetbrains.com/help/img/idea/2026.3/cl_makefile_target_config_template.png)

* 在设置中，您可以设置多个目标以运行，提供额外的参数，并根据需要调整其他参数。 有关更多信息，请参阅 [参考页面](makefile-target-configuration.html)。

![一个 Makefile Target 配置](https://resources.jetbrains.com/help/img/idea/2026.3/cl_makefile_target_config.png)

* 请点击   Apply   以保存更改。

> **Note:**
> * 当您从边栏或通过 Makefile Target 配置运行目标时，CLion 使用来自 `设置 | 构建、执行、部署 | 构建工具 | Make` 的 `make` 路径，而不考虑当前选择的工具链。 ![Make 构建工具设置](https://resources.jetbrains.com/help/img/idea/2026.3/cl_make_buildtools_settings.png)
>
> * Makefile Target 配置无法与 [远程](remote-projects-support.html) 或 [Docker](clion-toolchains-in-docker.html) 工具链一起使用。 有关 WSL 情况的更多信息，请参阅 [下文](#wsl-notes)。

## WSL 特性

### 同步设置

在使用 [WSL](how-to-use-wsl-development-environment-in-product.html) 时，请确保同步每个项目的工具链设置和全局   生成   设置：

Procedure:

1. 转到  `设置 | 构建、执行、部署 | 构建工具 | Make` 。

2. 点击   Make 可执行文件的路径   旁边的选择器，并设置 WSL 的  `make`  路径：

![在 WSL 中选择 make 的路径](https://resources.jetbrains.com/help/img/idea/2026.3/cl_makefile_wsl.png)

### 非 root WSL 用户

如果您在非 root WSL 用户下工作，则应将此用户设置为默认用户，以便拥有  `make`  进程及其可能创建的所有文件的所有权。

Procedure:

1. 在您的 WSL 客户端中创建一个  `/etc/wsl.conf`  文件，并添加以下行：

```CONSOLE
[user]
default=username

```

这里，  `username`  是 WSL 客户端用户名（可能与 Windows 用户名不同）。

在 [WSL 文档](https://docs.microsoft.com/en-us/windows/wsl/wsl-config#user) 中了解更多信息。

2. 重启 WSL 机器。

## 故障排查

确保启用了   Makefile   和   Makefile 语言   插件。 请检查  `设置 | 插件` 。

![Makefile 支持插件](https://resources.jetbrains.com/help/img/idea/2026.3/cl_makefile_plugins.png)

如果您的项目未正确加载，请尝试以下提示：

* 检查 [Makefile 设置](#makefile-settings)： 1. 请确保选择适当的工具链。 您的项目应在所选环境中成功构建。 2. 参数 和 构建目标 可能需要根据您的项目进行调整。

* 从主菜单中调用 `工具 | Makefile | 清理并重新加载 Makefile 项目` 或在构建工具窗口中点击 ![清理并重新加载图标](https://resources.jetbrains.com/help/img/idea/2026.3/app.actions.forceRefresh.svg)。

* 如果您的项目的 Makefile 是由 [Premake](https://premake.github.io/) 生成的，请尝试从根 Makefile 中移除 `--no-print-directory` 参数。

* 如果上述方法均无效，请尝试从系统目录中的 `/makefiles` 清理项目缓存（例如， `~/Library/Caches/JetBrains/CLion2020.2/makefiles/postgrtipes.dc29ef09` ），然后 [重新加载](#manual-reload) 项目。

## 当前限制和未来计划

* CLion 支持使用诸如 [ccache](https://ccache.dev/) 和 [libtool](https://www.gnu.org/software/libtool/)（以及其替代实现，如 [Dolt](https://dolt.freedesktop.org/)、 [slibtool](https://dev.midipix.org/cross/slibtool) 和 [jlibtool](https://github.com/alandekok/jlibtool)）等包装器的 Makefile 项目，但尚不支持 [distcc](https://github.com/distcc/distcc)（ [CPP-19305](https://youtrack.jetbrains.com/issue/CPP-19305)）。

* 目前不支持非 GNU Make，如 [NMake](https://docs.microsoft.com/cpp/build/reference/nmake-reference?view=vs-2019) 或 BSD Make（ [CPP-18723](https://youtrack.jetbrains.com/issue/CPP-18723)）。

* [单元测试配置](unit-testing-tutorial.html#test-configurations) 尚未适用于 Makefile 项目（ [CPP-20718](https://youtrack.jetbrains.com/issue/CPP-20718)）。

## See also

### 外部链接

[Dealing with Makefile Projects in CLion: Status Update](https://blog.jetbrains.com/clion/2020/02/dealing-with-makefiles/)

### 流程

[Autotools](gnu-autotools.html)

