---
title: 向代码中添加性能分析器Markers
product: Unity Editor
version: '6000.0'
latest_version: '7000.0'
status: This page documents version 6000.0. The latest version is 7000.0.
canonical: https://docs.unity.com/zh-cn/engine/6000.0/manual/analysis/profiler/customizing/adding-information-code/add-markers-code
latest_url: https://docs.unity.com/zh-cn/engine/7000.0/manual/analysis/profiler/customizing/adding-information-code/add-markers-code.md
last_updated: 2026-10-30
generated_at: 2026-11-20T21:12:42.993Z
locale: zh-cn
---

# 向代码中添加性能分析器Markers

> Add Profiler分析Markers记来标记代码的区域。

向代码添加[性能分析器 Markers](/engine/6000.0/manual/analysis/profiler/customizing/adding-information-code/intro.md) 可以查看性能[分析器窗口](/engine/6000.0/manual/analysis/profiler/window.md)中 [CPU 使用率模块](/engine/6000.0/manual/analysis/profiler/visualizing-data/cpu/introduction.md)的 **Time轴 View** 和 **Hierarchy 视图**中`ProfilerMarker.Begin`、`ProfilerMarker.End` 或 `ProfilerMarker.Auto` 生成的样本：


**Profiler sample with metadata in Timeline View.:**
![](/api/media?file=/engine/6000.0/media/images/profiler-marker-metadata-timeline.png)


**Profiler sample with metadata in Hierarchy View.:**
![](/api/media?file=/engine/6000.0/media/images/profiler-marker-metadata-hierarchy.png)

## 先决条件##prerequisites

一些示例使用[性能分析核心包](https://docs.unity3d.com/Packages/com.unity.profiling.core@latest)，必须在 Start 之前安装该包。在 Package Manager UI 中找不到 Unity Profiling Core 包，因为它是包。要安装该包，请[添加其 Name](/engine/6000.0/manual/packages-list/managing-packages-window/upm-ui-actions/upm-ui-quick.md)，即 `com.unity.profiling.core`。

## 标记代码##marking-up-your-code

要使用 [`ProfilerMarker` API](/engine/6000.0/script-reference/unity/profiling/profilermarker.md)，请将要进行配置文件的代码放在对 `ProfilerMarker.Begin` 和 `ProfilerMarker.End` 的 Calls 之间。例如：

```lang-cs
using UnityEngine;
using Unity.Profiling;

public class ProfilerMarkerExample
{
    Static readonly ProfilerMarker k_MyCodeMarker = 新建 ProfilerMarker("My 代码");

    void Update() {
        k_MyCodeMarker.Begin();
        Debug.Log("This code is being profiled");
        k_MyCodeMarker.End();
    }
}
```

> **Note:**
>
> 避免在性能分析器标记的 Name 中使用 `/` 角色，因为这会使性能分析器窗口无法在 CPU 性能分析器模块的 charts View 中突出显示该标记。

确保在调用 `End` 之前，`Begin` 和 `End` Calls 之间的代码不会退出作用域。如果在调用 `End` 之前代码退出作用域，则会将报错 message 记录到控制台。为了避免在每次返回之前必须调用 `End`，请使用 `Auto`，以便样本离开作用域时自动结束。有关更多信息，请参阅本文档中的 ON [自动关闭性能分析器标记代码块](#automatically-close)部分。

Unity 将性能分析代码块的执行时间记录并报告给性能分析器，并将其显示在 [CPU 性能分析器模块](/engine/6000.0/manual/analysis/profiler/visualizing-data/cpu/introduction.md)中，而无需使用[深度性能分析](/engine/6000.0/manual/analysis/profiler/deep-profiling.md)。它将在 CPU 性能分析器模块的 **Hierarchy 视图**中显示为新建条目，如下所示：


**Profiler sample in the Profiler Window.:**
![](/api/media?file=/engine/6000.0/media/images/profiler-marker-full-sample.png)

### 自动关闭性能分析器记代代码##automatically-close-profiler-marker-code-blocks

使用 `ProfilerMarker.Auto` 确保在代码块结束时自动调用 `ProfilerMarker.End`。以下 Calls 是等效的：

```lang-cs
using Unity.Profiling;

public class MySystemClass
{
    Static readonly ProfilerMarker k_UpdatePerfMarker = 新建 ProfilerMarker("更新");

    public void Update()
    {
        k_UpdatePerfMarker.Begin();
        // ...
        k_UpdatePerfMarker.End();

        using (k_UpdatePerfMarker.自动())
        {
            // ...
        }
    }
}
```

与 `Begin()` 和 `End()` Calls 不同，Unity 无法在非 Development（发布）版本中编译出 `ProfilerMarker.Auto` 调用。但是，它将返回 null，这只会增加最少的开销。

还可以将`ProfilerMarker.Auto`与`using var`一起使用，并且一旦当前作用域结束，`End`调用将自动发生。此方法可最大限度减少向代码添加`ProfilerMarker`实例时需要更改的代码量：

```lang-cs
using Unity.Profiling;

public class MySystemClass
{
    Static readonly ProfilerMarker k_UpdatePerfMarker = 新建 ProfilerMarker("更新");

    public void Update()
    {
        using var _ = 自动;
        // ...
    }
}
```

> **Note:**
>
> 不支持任何异步`await`和标记为 `ProfilerMarker` 的区域内的 Any `yield` Calls，即使使用 `Auto`，也会在控制台中日志报错 message。

## 向样本添加整数或点Parameters##adding-integer-or-floating-point-parameters-to-samples

有时，您可能希望向代码样本添加上下文，以确定代码长时间运行的指定的条件。

例如，如果System执行对象模拟，可使用性能分析器样本道对象的数量。如果性性能分析器返回异常数量以及较长的样本Duration，这可能意味着必须使用另一个线程进行模拟，将 CPU 工作拆分为多个个帧（时间切片），或者调整应用程序程序的设计以防止帧。

`ProfilerMarker` 最多支持三个数字参数：[`ProfilerMarker<TP1>`](https://docs.unity3d.com/Packages/com.unity.profiling.core@1.0/api/Unity.Profiling.ProfilerMarker-1.html)、[`ProfilerMarker<TP1, TP2>`](https://docs.unity3d.com/Packages/com.unity.profiling.core@1.0/api/Unity.Profiling.ProfilerMarker-2.html) 和 [`ProfilerMarker<TP1, TP2, TP3>`](https://docs.unity3d.com/Packages/com.unity.profiling.core@1.0/api/Unity.Profiling.ProfilerMarker-3.html)：

```lang-cs
using Unity.Profiling;

public class MySystemClass
{
  Static 只读 ProfilerMarker<int> k_PreparePerfMarker = 新建 ProfilerMarker<int>("MySystem.Prepare", "Objects 数量");
  Static 只读 ProfilerMarker<float> k_SimulatePerfMarker = 新建 ProfilerMarker<float>(ProfilerCategory.Scripts, "MySystem.模拟", "Objects Density");

  public void Update(int objectsCount)
  {
    k_PreparePerfMarker.Begin(objectsCount);
    // ...
    k_PreparePerfMarker.End();

    using (k_SimulatePerfMarker.Auto(objectsCount * 1.0f))
    {
      // ...
    }
  }
}
```

## 向样本添加字符串 Parameters##adding-string-parameters-to-samples

`ProfilerMarker` API 支持将字符串 Parameters 添加到性能分析器 Markers。如果要在应用程序加载关卡或数据文件时显示关卡或文件的名称，字符串参数可能很有用。使用 [`ProfilerMarkerExtension`](https://docs.unity3d.com/Packages/com.unity.profiling.core@1.0/api/Unity.Profiling.ProfilerMarkerExtension.html) 方法将字符串参数与性能分析器样本一起通道：

```lang-cs
using Unity.Profiling;

public class MySystemClass
{
  Static 只读 ProfilerMarker k_PreparePerfMarker = 新建 ProfilerMarker("MySystem.Prepare");

  public void Prepare(string path)
  {
    k_PreparePerfMarker.Begin(path);
    // ...
    k_PreparePerfMarker.End();
  }
}
```

## 其他资源##additional-resources

* [在代码简介中添加性能分析信息](/engine/6000.0/manual/analysis/profiler/customizing/adding-information-code/intro.md)
* [向代码中添加性能分析器计数器](/engine/6000.0/manual/analysis/profiler/customizing/adding-information-code/add-counters-code.md)
* [CPU 使用率性能分析器模块简介](/engine/6000.0/manual/analysis/profiler/visualizing-data/cpu/introduction.md)
* API
* [性能分析核心包](https://docs.unity3d.com/Packages/com.unity.profiling.core@latest)
