# File Watchers

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

> **TL;DR**
> 必需插件  :
>
>
>
> `[文件观察器](https://plugins.jetbrains.com/plugin/7177-file-watchers)`  -  在   设置 | 插件   页面上安装插件。

文件监视器 允许您在 IDE 中更改或保存文件时自动运行命令行工具，例如编译器、格式化工具或代码检查工具。

文件监视器有两个专用的  代码检查 ：

* 每个预定义的 File Watcher 适用的文件中都会运行 可用的 File Watcher 检查。 如果项目没有配置相关的文件观察器，CLion 建议添加一个。

* 由正在运行的 File Watcher 调用的 File Watcher problems 检查会突出显示特定于它的错误。

您可以使用现有的模板之一或从头开始配置 File Watcher。 配置好的 File Watcher 可以保存在您的项目设置或 IDE 设置中，并在不同的项目中使用。

有关特定工具的文件监视器的更多信息，请参阅相应页面：

* [压缩 CSS（CSSO 优化器）](compressing-css.html)

* [Sass、Less 和 SCSS](transpiling-sass-less-and-scss-to-css.html#less_sass_scss_compiling_to_css)

* [Compass 应用程序中的 Sass 和 SCSS](transpiling-compass-to-css.html#compass_compiling_sass_scss)

* [Stylus](transpiling-stylus-to-css.html#stylus_compilation)

* [CoffeeScript](coffeescript.html#ws_coffee_compilation)

请注意，在 CLion 中使用其中的一些工具需要您在   设置 | 插件   页面上安装插件，如 [从 JetBrains Marketplace 安装插件](managing-plugins.html#install_plugin_from_repo)中所述。

## 在开始之前

安装并启用  File Watchers  插件（在   设置 | 插件   页面上），如 [从 JetBrains Marketplace 安装插件](managing-plugins.html#install_plugin_from_repo)中所述。

## 创建文件观察器

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)), `⌘ Comma` (Xcode), `Ctrl+Alt+S` (Visual Studio), `⌘ Comma` (Visual Studio (macOS)), `Ctrl+Alt+S` (ReSharper), `⌘ Comma` (ReSharper (macOS)), `Ctrl+Alt+S` (QtCreator), `⌘ Comma` (QtCreator (macOS)), `Ctrl+Alt+S` (NetBeans), `Ctrl+Alt+S` (Eclipse), `⌘ Comma` (Eclipse (macOS))）中，点击   File Watchers   下的   工具  。 “ [文件监视器页面](settings-tools-file-watchers.html)”打开，显示了该项目和 IDE 中已配置的文件监视器列表。

2. 点击 ![添加按钮](https://resources.jetbrains.com/help/img/idea/2026.3/app.expui.general.add.svg)并选择您要从中创建File Watcher的预定义模板。 选择取决于您将要使用的工具。 若要使用不在列表中的工具，请选择   自定义  。

![将 SCSS 编译为 CSS：创建一个 File Watcher](https://resources.jetbrains.com/help/img/idea/2026.3/ws_scss_example_create_file_watcher.png)

[新建 Watcher](new-watcher-dialog.html) 对话框打开。

3. 在   名称   字段中，输入文件监视器的名称。 默认情况下，CLion 会建议选定的预定义模板名称。

## 配置输入文件的预期类型和位置

请使用   要监视的文件   区域的控件定义您想要应用文件监视器的文件作用域。

Procedure:

1. 从   文件类型  列表中选择预期类型的输入文件。 文件监视器将只考虑这种类型的文件作为分析和处理的对象。 文件类型基于 [文件类型与文件扩展名之间的关联](creating-and-registering-file-types.html#register-new-association)进行识别。

默认情况下，该字段根据所选的预定义模板显示文件类型。

2. 请选择适用文件监视器的   作用域  。

![SCSS 文件监视器：更改默认作用域](https://resources.jetbrains.com/help/img/idea/2026.3/ws_scss_example_file_watcher_settings_change_scope.png)

这些文件的更改将立即或在保存或窗口失去焦点时引发 File Watcher，这取决于   自动保存已编辑的文件以触发监视器  复选框的状态。

从列表中选择一个预定义作用域。 对于项目级文件监视器，您也可以点击 ![“浏览”按钮](https://resources.jetbrains.com/help/img/idea/2026.3/app.general.ellipsis.svg)，在打开的   作用域  对话框中配置自定义作用域。

* 所有位置： 下述所有作用域。

* 项目文件： 项目根目录内的所有文件。

* 临时文件和控制台： 位于 临时文件与控制台 目录中的所有文件位于 项目 工具窗口。

* 打开文件： 当前在编辑器中打开的所有文件。

* 当前文件: 在活动编辑器选项卡中打开的文件。

或者，点击 ![“浏览”按钮](https://resources.jetbrains.com/help/img/idea/2026.3/app.general.ellipsis.svg) 并在打开的  自定义作用域  对话框中配置  作用域 。

欲了解更多信息，请参阅 [文件作用域与文件颜色](configuring-scopes-and-file-colors.html)。

3. 可选地 ：指定您希望 File Watcher 如何处理依赖项。 一个  root file  是一个未包括在（例如，通过  `import` ） [指定作用域内](new-watcher-dialog.html#scope)的任何其他文件中的文件。

* 要仅针对根文件运行 File Watcher，请选择 仅跟踪根文件 复选框。

* 清除该复选框以对调用它的文件以及在指定作用域内递归包含此文件的所有文件运行 File Watcher。

请注意，   作用域   设置会覆盖   仅跟踪根文件   复选框设置：如果某个依赖超出了指定作用域，文件监视器将不会应用于其。

> **Note:**
> 此选项仅适用于  Babel 、  Closure 编译器 、  Jade 、  Less 、  Sass /  SCSS 、  Stylus  和  UglifyJS (terser) 。

## 配置与外部工具的交互

在   更改时运行的工具  区域，指定要使用的工具、传递给它的参数、预期的输出文件类型等。

Procedure:

1. 在   程序   字段中，指定工具的可执行文件的路径（  `.exe` 、  `.cmd` 、  `.bat`  或其他，具体取决于具体的工具）。

> **Tip:**
> * 要使用程序文件名而不是其完整路径，请将其文件夹的路径添加到 `PATH` 环境变量中。
>
> * 在 Windows 上，您可以跳过 `.com` 、 `.exe` 、 `.cmd` 或 `.bat` 扩展名。
>
> * 要使用 `jar` 归档文件，请指定其绝对路径。 或者，要使用相对路径，请将其父文件夹添加到 [CLion 路径变量](absolute-path-variables.html)中，在 外观与行为 | 路径变量 设置页面 `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)), `⌘ Comma` (Xcode), `Ctrl+Alt+S` (Visual Studio), `⌘ Comma` (Visual Studio (macOS)), `Ctrl+Alt+S` (ReSharper), `⌘ Comma` (ReSharper (macOS)), `Ctrl+Alt+S` (QtCreator), `⌘ Comma` (QtCreator (macOS)), `Ctrl+Alt+S` (NetBeans), `Ctrl+Alt+S` (Eclipse), `⌘ Comma` (Eclipse (macOS))。

2. 在   参数  字段中，定义传递给工具的参数。

参数通常使用 [宏](built-in-macros.html)指定，例如，  `$FileName$` 或  `$FileNameWithoutExtension$` ，这些将被替换为实际的文件名。

手动键入宏或点击 ![插入宏图标](https://resources.jetbrains.com/help/img/idea/2026.3/app.general.inlineAddHover.svg)，然后在打开的   宏  对话框中从列表中选择相关模式。

> **Tip:**
> 在指定参数时，请遵循以下规则：
>
> * 使用空格作为分隔符。
>
> * 如果参数包含空格，请用双引号将它们或整个参数括起来： `some" "arg` 或 `"some arg"` 。
>
> * 如果参数包含双引号，请使用反斜杠进行转义： `-Dmy.prop=\"quoted_value"\` 。

3. 在   要刷新的输出路径   字段中，指定工具存储其输出结果的文件：生成的源代码、源地图和依赖项。 基于这些设置，CLion 识别通过编译生成的文件。

通常使用 [宏](built-in-macros.html) 指定输出路径。 您可以手动输入它们或点击 ![插入宏图标](https://resources.jetbrains.com/help/img/idea/2026.3/app.general.inlineAddHover.svg)并在打开的对话框中从列表中选择相关项。

要指定多个宏，请使用冒号  `:` 作为分隔符，例如，  `$FileNameWithoutExtension$.css:$FileNameWithoutExtension$.css.map` 。

> **Note:**
> 更改   要刷新的输出路径   字段中的值不会使工具将其输出存储在其他位置。 如果您仍然需要这样做，请在   参数   字段中指定所需的自定义输出位置：输入以冒号分隔的输出路径并使用宏。

4. 展开   工作目录和环境变量  隐藏区域。

5. 定义环境变量。 例如，为 您 正在配置但路径中未引用的工具指定  `PATH`  变量，其中包含启动该工具所需的工具。 在大多数情况下，它是  Node.js  或  ruby.exe 。 这种情况可能是由于使用自定义手动安装而非通过 Node Package Manager (npm) 或  gem manager  进行安装导致的。

6. 在   工作目录  字段中，指定工具将应用到的目录。

因为该工具总是在文件的上下文中调用，所以默认工作目录是当前文件所在的目录。 所有预定义模板中都用  `$FileDir$`  宏指定了默认工作目录。 若要指定自定义工作目录，请在字段中键入路径，或点击 ![浏览图标](https://resources.jetbrains.com/help/img/idea/2026.3/app.general.openDiskHover.svg)并在   选择路径  对话框中选择目录，或点击 ![插入宏图标](https://resources.jetbrains.com/help/img/idea/2026.3/app.general.inlineAddHover.svg)并从   宏  对话框的列表中选择所需的 [宏](built-in-macros.html)。

> **Tip:**
> 如果您将   工作目录   字段留空，CLion 将使用调用 File Watcher 的文件目录。

## 配置高级选项

在   高级选项   区域，定制 File Watcher 的默认行为。

Procedure:

1. 指定将触发 File Watcher 的事件：

* 若要在对源代码进行任何更改后立即调用 File Watcher，请选中 自动保存已编辑的文件以触发监视器 复选框。 清除复选框后，File Watcher 会在保存时启动（ `文件 | 全部保存` ）或当您从 CLion 移开焦点（在窗口失去焦点时）。 ![自动保存已编辑文件关闭](https://resources.jetbrains.com/help/img/idea/2026.3/ws_scss_example_file_watcher_autosave_on_edit_off.png)

* 文件监视器默认在任何已保存的更改时唤醒，包括当您从版本控制系统收到更新时，例如检出分支。 要忽略此类更改并仅在您更新 CLion 中的代码时调用 Watcher，请取消选中 在外部更改时触发监视器 复选框。

2. 指定是否希望 File Watcher 与 CLion 语法解析器进行交互：

* 当选中 触发监视器，即使存在语法错误 复选框时，文件监视器会在文件语法正确与否的情况下启动。 文件监视器将根据 自动保存已编辑的文件以触发监视器 复选框的状态在更新、保存或框架停用时启动。

* 当清除 触发监视器，即使存在语法错误 复选框时，文件监视器会忽略语法无效文件中的所有触发器，仅在无错误的文件中启动。

3. 使用   从 stdout 创建输出文件   复选框来指定您希望如何生成输出文件。

* 当选中复选框时，CLion 会读取本机工具的输出 `standard output stream (stdout)` 并生成结果文件。

* 选中复选框时，该工具会将其输出直接写入 要刷新的输出路径 字段中指定的文件。

4. 在   显示控制台  列表中，选择您希望 File Watcher 何时打开控制台。

* 始终: 启用此选项后，工具执行完成后控制台总会打开。

* 出错时： 使用此选项，仅当 `Exit code` 不同于 `0` 时，控制台才会在工具执行后打开。

* Never: 选择此选项可完全禁止打开控制台。

## 在编辑器中显示由 File Watcher 报告的信息

如果 File Watcher 中配置的工具报告了包含文件和特定行链接的代码错误或警告，您可以在编辑器中直接查看此信息：

* 在 `设置 | 编辑器 | 检查` 中，启用检查 文件监视器问题 。

* 在 输出过滤器 字段中， [编辑观察器](new-watcher-dialog.html) 对话框描述您想匹配的输出格式。 请使用宏 `$FILE_PATH$` 、 `$LINE$` 和 `$MESSAGE$` 。 您需要避免使用像大括号和点这样的特殊符号 `\` 。 与 `$MESSAGE$` 宏匹配的文本将显示在编辑器中。

## 保存、启用与禁用 File Watchers

> **Warning:**
> 在  安全模式 中打开项目时，文件监听程序不会启动。 如需了解更多信息，请参阅 [项目安全性](project-security.html)。

保存新的文件监视器后，您可以决定它是仅在当前项目中可用（从   级别  列表中选择   项目  ）还是对所有项目可用（选择   全局  ）。

![启用文件监视器](https://resources.jetbrains.com/help/img/idea/2026.3/cl_enable_global_watcher.png)

Procedure:

* 要启用或禁用文件监视器，请打开   设置  对话框（ `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)), `⌘ Comma` (Xcode), `Ctrl+Alt+S` (Visual Studio), `⌘ Comma` (Visual Studio (macOS)), `Ctrl+Alt+S` (ReSharper), `⌘ Comma` (ReSharper (macOS)), `Ctrl+Alt+S` (QtCreator), `⌘ Comma` (QtCreator (macOS)), `Ctrl+Alt+S` (NetBeans), `Ctrl+Alt+S` (Eclipse), `⌘ Comma` (Eclipse (macOS))），转到  `工具 | 文件监视器` ，并选中或清除其旁边的复选框。

* 当您打开一个适用于预定义文件监视器的文件时，CLion 会建议启用文件监视器：

![将 Less 编译为 CSS：从编辑器窗格中创建一个 File Watcher](https://resources.jetbrains.com/help/img/idea/2026.3/ws_less_example_create_file_watcher_from_pane.png)

* 启用 File Watcher 后，只要选定作用域内的选定类型文件被更改或保存，它就会自动启动，详见 [配置高级选项](#ws_filewatcher_advanced_options)。

* 如果在 File Watcher 运行时发生错误，File Watcher 会自动停用。 若要恢复状态，请手动启用 File Watcher。

Procedure: 为新项目启用全局文件监视器

Global  文件监视器可以在您将来创建的所有新项目中自动启用。

* 打开   新项目设置   对话框 (  `文件 | 新项目设置` ) ，转到  `工具 | 文件监视器` ，并选中所需 File Watchers 旁边的复选框。

* 或者，在 [欢迎界面](welcome-screen.html) 上，从   配置   列表中选择   设置  。 在打开的对话框中，选中相关 File Watchers 旁边的复选框。

## 文件监视器故障排除

可能会显示一个弹出窗口，带有错误消息，同时通知您文件监视器已被禁用。

这里是可能出现的错误列表：

|  已报告的问题  |  问题描述  |  解决方法  |
| --- | --- | --- |
|   `Unknown Scope error`   |  文件监视器使用在此项目中未定义的作用域。  |  双击观察器并选择可用的作用域或创建一个新的。  |
|   `Invalid executable`   |  该项目使用了一个已被删除的全局 File Watcher。  |  使用   移除  按钮 ![移除](https://resources.jetbrains.com/help/img/idea/2026.3/app.expui.general.remove.svg)从列表中删除观察者，或编辑它以创建一个具有相同名称的新全局观察者。  |
|     CLion 运行多个相同的 File Watcher 任务     |     在进行批量更新之后，例如来自您的 VCS，CLion 会为每个保存的文件运行一个单独的 File Watcher 任务。     |  在   参数   字段中添加文件特定的宏（如  `&FileNameWithoutExtension&`  ）, 请参阅 [配置与外部工具的交互](#transpilerBehaviour)。  |

## See also

### 标记语言与样式表

[压缩 CSS](compressing-css.html) [Sass、SCSS、Less 和 PostCSS](transpiling-sass-less-and-scss-to-css.html) [在 Compass 应用程序中的 Sass 和 SCSS](transpiling-compass-to-css.html)

### 语言和框架特定指南

[CoffeeScript](coffeescript.html)

### 参考

[File Watchers](settings-tools-file-watchers.html) [新建监视器对话框](new-watcher-dialog.html) [内置 IDE 宏](built-in-macros.html)

### 外部链接

[Working with Makefiles in CLion using Compilation DB and File Watchers](https://blog.jetbrains.com/clion/2018/08/working-with-makefiles-in-clion-using-compilation-db/)

