# 步进筛选器设置

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

步进筛选器允许在用调试器逐步执行 C 和 C++ 代码时跳过选定的函数。 当   单步进入   通常会输入匹配筛选器的函数时，CLion 会步过它。 仍可通过 [强制步入](stepping-through-the-program.html#force-step-into) 输入该函数。

步进筛选器可与 LLDB 和 GDB 调试器后端一起使用，并且仅适用于   单步进入  。   单步跳过   和   单步退出   不受影响。

步进筛选器的规则来源有三种，按如下顺序检查：

1.  属于已打开项目的  `.natstepfilter`  和  `.natjmc`  文件。

2.  系统范围和每个用户的 Visual Studio 可视化器目录中的  `.natstepfilter`  和  `.natjmc`  文件（仅限 Windows）。

3.  您在 IDE 设置中维护的正则表达式模式，包括适用于 C++ 标准库的内置模式集。

每个来源中，第一个匹配的规则生效。 因此，  `StepInto`  规则在  `.natstepfilter`  文件中会重写同一文件中后面的  `NoStepInto`  规则，项目文件总是优先于 IDE 设置中的正则表达式模式。

在匹配规则前，CLion 会规范化调试器报告的函数名称：会移除 cv 限定符和引用限定符，移除返回值类型，隐藏匿名命名空间，并移除参数列表。 因此，模式应当匹配裸限定名称，例如  `std::vector<.*>::push_back` ，而不是参数签名。

CLion 自带一组内置正则表达式设置，可跳过常见的 C++ 标准库帮助程序、智能指针访问器、libstdc++ 内部代码和其他内容。 您可以为每个项目扩展或替换此列表。

## 在 IDE 中配置步进筛选器

打开  `设置 | 构建、执行、部署 | 调试器 | 步进 | C/C++` 。

![步进筛选器设置页面](https://resources.jetbrains.com/help/img/idea/2026.3/cl_step_filter_settings.png)

本页面包含以下选项：

|  选项  |  描述  |
| --- | --- |
|  从配置文件加载步进规则  |     启用后，调试器会读取属于已打开项目的每个  `.natstepfilter`  和  `.natjmc`  文件，并在 Windows 上读取 Visual Studio 可视化器目录内的文件。 禁用复选框后，将在下次调试会话中忽略项目随附文件和 Visual Studio 提供的文件。     |
|  不步入函数  |     启用时，调试器会应用复选框下方列出的正则表达式模式。 每一行通过其完全限定名称匹配函数。 在匹配前会移除参数列表和返回值类型，因此像  `std::vector<.*>::push_back`  这样的模式就足够——无需写出实参列表。 使用工具栏按钮添加、编辑、复制或移除模式；清除某一行的复选框可在不应用的情况下保留该模式。       来自  `.natstepfilter`  文件的模式优先于此处配置的模式，因此若同一函数也被文件规则覆盖，则在此页更改设置可能无效。     |
|  步进诊断  |     控制步进筛选器活动在调试器控制台的报告方式：        * 已禁用 — 无诊断输出。    * 仅限错误 （默认）— 报告配置文件格式错误或正则表达式无效等问题。    * 详细 — 还会记录每个加载的文件和所有根据规则匹配的函数名称。 当某个模式表现异常时很有用。    |

点击   Apply   以保存更改。 新设置会影响下一个调试会话。 正在运行的会话会保留其启动时的规则。

## 使用项目文件配置步进筛选器

可以通过将  `.natstepfilter`  或  `.natjmc`  文件添加到项目，将步进筛选器规则纳入版本控制。 只要启用   从配置文件加载步进规则  ，CLion 会自动识别这些文件。

### .natstepfilter

`.natstepfilter`  文件使用 Visual Studio 步进筛选器 XML 架构。 每个  `<Function>`  元素包含一个  `<Name>`  正则表达式、一个  `<Action>` ，还可以包含一个用于限定规则到特定库的可选  `<Module>`  正则表达式。 CLion 支持两种操作：

* `NoStepInto` — 在 单步进入 上跳过该函数。

* `StepInto` — 即使有其他规则会跳过，也会强制 单步进入 输入该函数。 当早前的 `NoStepInto` 规则用宽泛模式覆盖代码时，用于开放异常很有用。

Visual Studio  `NonUserCode`  操作在调试器中将被错误拒绝。 请使用  `.natjmc`  文件将代码标记为非用户。

```XML
                <?xml version="1.0" encoding="utf-8"?>
<StepFilter xmlns="http://schemas.microsoft.com/vstudio/debugger/natstepfilter/2010">
    <Function>
        <Name>std::.*</Name>
        <Action>NoStepInto</Action>
    </Function>
    <Function>
        <Name>my::lib::detail::important_callback</Name>
        <Action>StepInto</Action>
    </Function>
    <Function>
        <Name>my::lib::detail::.*</Name>
        <Module>libmy\.so</Module>
        <Action>NoStepInto</Action>
    </Function>
</StepFilter>
            
```

请将该文件放置在项目内，以便 IDE 索引。 项目作用域之外的文件不会被自动加载。

### .natjmc

`.natjmc`  文件使用 Visual Studio Just My Code 架构。 CLion 将其作为额外步进筛选器来源，并将其中的模块、文件与函数视为外部代码：

```XML
                <?xml version="1.0" encoding="utf-8"?>
<NonUserCode xmlns="http://schemas.microsoft.com/vstudio/debugger/jmc/2015">
    <Module Name="UnrealEditor-Core*"/>
    <File Name="*/ThirdParty/*"/>
    <Function Name="boost::.*" Module="libboost_system.so.1.83.0"/>
</NonUserCode>
            
```

特性的匹配方式如下：

* `<Module Name="...">` 和 `<File Name="...">` 支持 glob 模式。 在 Visual Studio 中可用 `*` 和 `?` 。

* `<Function Name="...">` 是针对规范化函数名称进行匹配的正则表达式。

* `<Function Module="...">` 是大小写不敏感的文字模块名称——既不是 glob，也不是正则表达式。 请指定加载模块的确切名称（例如 `libboost_system.so.1.83.0` 或 `MyApp.exe` ）。

* `<Module Company="...">` 当前仅作为筛选器生效：带有 `Company` 特性的 `<Module>` 规则将被忽略，因为 CLion 不读取嵌入于二进制中的公司元数据。 如需启用规则，请省略该特性。

### Visual Studio 可视化器目录（Windows）

在 Windows 上，CLion 还会扫描 Visual Studio 用于  `.natvis` 、  `.natstepfilter`  和  `.natjmc`  文件的同一目录：

* `%VSINSTALLDIR%\Common7\Packages\Debugger\Visualizers` — 系统可视化器，包括第三方 SDK，如 Unreal Engine 集成提供的可视化器。

* `%USERPROFILE%\Documents\Visual Studio <version>\Visualizers` — 用户可视化器。

只有在检测到本机已安装 Visual Studio 时，这些文件夹才会被扫描。

## 诊断异常的步进行为

如果步入操作未跳过你希望被筛选器筛选的函数，请将   步进诊断   切换为   详细   并重新运行调试会话。 调试器控制台随后会打印加载了哪些配置文件、哪些模式被匹配、以及哪些函数名称被规范化用于匹配。 意外行为的常见原因有：

* 正则表达式中有拼写错误。 在表格中编辑模式时，IDE 会高亮显示正则表达式错误。

* `.natstepfilter` 文件中前面的 `StepInto` 规则重写了后面的 `NoStepInto` 规则。 请调整规则顺序，使更具体的规则优先。

* 项目中的 `.natstepfilter` 文件重写了 IDE 设置中的某个模式。 详细日志会显示提供匹配规则的文件路径。

* 函数名称在不同调试器间存在差异。 CLion 在匹配前会规范化大多数差异（限定符、返回值类型、参数列表、匿名命名空间），但旧版 Linux 和 macOS 上的 LLDB 构建有时仍会带有返回值类型——编写模式时，请匹配裸限定名称，例如 `std::max<.*` ，而不是 `int std::max<.*>` 。

## See also

### 流程

[逐步执行](stepping-through-the-program.html)

### 参考

[调试工具窗口](debug-tool-window.html)

