SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场qt-qml-profiler

qt-qml-profiler

测试与质量

查看项目

更新于 10-15 15:22

技能介绍

用途

Qt QML Profiler 技能用于对 QML 应用进行性能剖析并分析性能瓶颈。它面向 2D QML / Qt Quick 应用，帮助定位界面卡顿、掉帧、加载缓慢等性能问题的来源。

主要能力

  • 采集 QML 应用运行轨迹：通过 qmlprofiler 生成 .qtd 轨迹文件。
  • 解析轨迹：使用随技能提供的解析脚本 parse-qmlprofiler-trace.py 提取事件数据。
  • 热点分析：从解析结果中取前 5 个热点，映射到本地源码文件，读取热点行附近约 15 行代码，结合 qml-performance-anti-patterns.md 中的反模式参考，说明代码做了什么、为何昂贵、以及具体修复建议。
  • 生成报告：输出独立的诊断报告，包含剖析元数据、事件类型汇总、动画/帧时间汇总、内存汇总等。

使用方式

参数遵循 qmlprofiler 约定，-- 用于分隔技能参数与应用可执行文件及其参数。

剖析模式（先运行再分析）：

$ARGUMENTS = [--profile <mode>] -- <executable> [app-args...]

仅分析模式（已有轨迹）：

$ARGUMENTS = <path-to-trace.qtd>

若 $ARGUMENTS 以 .qtd 结尾，则视为已有轨迹文件，直接进入解析与分析步骤。

未指定 --profile 时默认使用 full。各配置对应的 qmlprofiler --include 值：

  • full：省略 --include，记录全部事件
  • rendering：scenegraph,animations,painting,pixmapcache
  • logic：javascript,binding,handlingsignal,compiling,creating
  • memory：memory,creating

执行流程大致为：定位工具（检测操作系统、查找 qmlprofiler 可执行文件与解析脚本）→ 以 QML 调试方式构建（仅剖析模式）→ 运行 qmlprofiler（仅剖析模式）→ 解析轨迹 → 分析热点 → 编写报告。

构建时使用 cmake 命令行标志，不修改 CMakeLists.txt：

cmake -B build -DCMAKE_BUILD_TYPE=RelWithDebInfo \
      -DCMAKE_CXX_FLAGS="-DQT_QML_DEBUG" \
      -DCMAKE_PREFIX_PATH="<qt-path>"
cmake --build build

运行 qmlprofiler 的命令形式：

"<qt-path>/bin/qmlprofiler" [--include <features>] -o "<trace-file>" -- "<executable>" [app-args...]

轨迹文件默认放在 profiler/traces/qmlprofiler-trace-<app>-YYYY-MM-DD-HHMMSS.qtd，报告默认放在 profiler/reports/profile-report-<app>-YYYY-MM-DD-HHMMSS.md。

解析命令：

python3 "<skill-path>/references/scripts/parse-qmlprofiler-trace.py" "<trace-file>"

Windows 上若 python3 不可用，可改用 python。

适用场景

  • 用户反馈界面卡顿、变慢、掉帧等模糊的性能抱怨。
  • 需要定位 QML 应用中耗时较多的组件创建、JavaScript 执行、编译、绑定等事件。
  • 需要查看帧时间分布（p50、p95、p99、max）以及超过 25ms / 33ms / 50ms 的卡顿帧数量。
  • 需要分析 QML 内存分配情况（HeapPage、SmallItem、LargeItem）。

限制

  • 仅支持 2D QML / Qt Quick 应用。Qt Quick 3D（quick3d qmlprofiler 特性，如 Quick3DRenderFrame、Quick3DSync、Quick3DCullInstances 等）不受支持：这些事件不会从轨迹中提取，也不会在报告中汇总，反模式参考也不覆盖 3D 专属优化（网格批处理、材质开销、着色器变体、渲染通道）。
  • 若被剖析应用使用 Qt Quick 3D，2D 结果仍然有效，但 3D 瓶颈在输出中不可见；解析器在轨迹同时包含 2D 和 3D 事件时会发出 quick3d_events_dropped，仅含 3D 事件时报错。
  • 剖析模式需要以 -DQT_QML_DEBUG 构建，否则轨迹可能为空或过小。
  • 若当前会话无法执行 qmlprofiler 二进制（无 shell 执行工具、沙箱阻止、权限被拒等），需转为手动回退，由用户自行运行命令并回传轨迹路径。
  • 报告中的源码位置链接仅对本地解析到的文件生成，Qt 内部文件、未解析或跳过的位置保持纯文本，不虚构路径。
  • 关于收费、价格、平台支持范围等更多信息，资料中暂未提供。