步进筛选器设置

步进筛选器允许在用调试器逐步执行 C 和 C++ 代码时跳过选定的函数。当单步进入通常会输入匹配筛选器的函数时，CLion 会步过它。仍可通过强制步入输入该函数。

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

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

属于已打开项目的 .natstepfilter 和 .natjmc 文件。
系统范围和每个用户的 Visual Studio 可视化器目录中的 .natstepfilter 和 .natjmc 文件（仅限 Windows）。
您在 IDE 设置中维护的正则表达式模式，包括适用于 C++ 标准库的内置模式集。

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

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

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

在 IDE 中配置步进筛选器

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

本页面包含以下选项：

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

选项

描述

从配置文件加载步进规则

启用后，调试器会读取属于已打开项目的每个 .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 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 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 文件的同一目录：

&percnt;VSINSTALLDIR&percnt;\Common7\Packages\Debugger\Visualizers — 系统可视化器，包括第三方 SDK，如 Unreal Engine 集成提供的可视化器。
&percnt;USERPROFILE&percnt;\Documents\Visual Studio <version>\Visualizers — 用户可视化器。

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

诊断异常的步进行为

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

正则表达式中有拼写错误。在表格中编辑模式时，IDE 会高亮显示正则表达式错误。
.natstepfilter 文件中前面的 StepInto 规则重写了后面的 NoStepInto 规则。请调整规则顺序，使更具体的规则优先。
项目中的 .natstepfilter 文件重写了 IDE 设置中的某个模式。详细日志会显示提供匹配规则的文件路径。
函数名称在不同调试器间存在差异。 CLion 在匹配前会规范化大多数差异（限定符、返回值类型、参数列表、匿名命名空间），但旧版 Linux 和 macOS 上的 LLDB 构建有时仍会带有返回值类型——编写模式时，请匹配裸限定名称，例如 std::max<.* ，而不是 int std::max<.*>。

2026年 7月 15日