文档/调试工作台

调试工作台

作品卡顿、脚本没有按预想运行、想知道哪块积木最费时，都可以在「调试」面板里查。它把运行中的作品拆开来看：每一帧花了多少毫秒、哪条脚本在占时间、哪块积木被执行了多少次，还能在积木上下断点，停下来查看变量。

录完一段之后的样子：上面是每帧耗时、帧率这几个数，下面是「这次慢在哪」的结论，每条都能点「跳到积木」跳转过去。

打开方式#

顶栏中间那排图标最右边的田字格按钮是抽屉，点开，里面有「调试」。

它以悬浮窗的形式打开，默认落在编辑器右下角，620 × 560。可以拖标题栏移动、拖边缘改大小。调试要边运行边观察，浮窗形式便于同时看到工作区和舞台。

常用时可以把抽屉里的「调试」图标拖到顶栏那一排上，以后一步就能打开。

刚打开时面板是空的：

面板结构#

最上面一条是运行控制工具条，在任何一页都显示。

控件	作用
「录制」	开始记录，一直录到点「停止」为止
「5 秒」	录 5 秒自动停
「轻」/「完整」	记录的详细程度，见下面「两个档位」
「暂停」/「继续」	`F8`。命中断点时这颗按钮变绿，写着「继续」
「单步」	`F9`，执行一块积木
「跳过」	`F10`，自制积木整段跳过
「跳出」	`Shift` + `F9`，执行完当前过程再停

右边是状态胶囊：「已暂停」/「单步中」、「录制中」、「编译」或「解释」（开了加速会写成「解释 · 加速」），以及有录制数据时的每帧毫秒。录制期间把鼠标停在毫秒那颗胶囊上，会显示探针自身占了多少。

面板窄到一定程度时这排按钮会收起内容：窄于 700px 隐藏 F8 这类角标，窄于 640px 连按钮上的文字也隐藏，只留图标。

工具条下面是页签，一共十一页：

页	讲什么	文档
概览	每帧几毫秒、卡在哪，加导出 / 导入 / 基线	本篇
帧	每一帧的柱状图，点一根查看那一帧	本篇
线程	每段脚本的耗时，以及当前存活的线程	本篇
积木	最费时的积木排行	本篇
监视	当前角色和舞台的变量、列表，可直接修改	监视 / 渲染 / 内存
断点	断点表、暂停现场、调用栈	断点与单步
事件	广播、帽子、克隆各发生了多少次	本篇
渲染	画面为什么慢：大造型、特效、克隆体	监视 / 渲染 / 内存
内存	堆内存走势、对象数、最大的列表	监视 / 渲染 / 内存
日志	绿旗、说话、克隆、日志点、变量变化	诊断与日志
外观	工作区上各种描边与标记的颜色和开关	监视 / 渲染 / 内存

「断点」和「日志」页签上带数字角标，是当前断点数和日志条数。

数据来源#

面板里的数字由 VM 在运行时逐条记录。由此有两个结果：不录制时探针不执行任何代码，平时不必担心它拖慢作品；探针只能测到 VM 内的时间，编辑器界面占用的主线程时间要靠帧间隔倒推（见「界面开销」那条结论）。

性能录制#

两个档位#

档位	记什么	什么时候用
轻	每帧的耗时、绘制耗时、线程数；每条线程每一轮的耗时和块数；广播 / 帽子 / 克隆	判断卡不卡、哪段脚本重
完整	上面全都记，外加每一块积木的自耗时和执行次数	定位到具体是哪块积木

默认是「完整」。「积木」页、结论里的「最费时的积木」，还有工作区上的热度描边，都只有「完整」档才有。轻档录完切到「积木」页会是这样：

代价是「完整」档要给每块积木计时，本身有开销，占用多少可以在工具条右边那颗毫秒胶囊的悬停提示里看到。作品特别重时，先用「轻」档定位到脚本，再切「完整」档确认是哪一块。

录制一段#

点「录制」（或「5 秒」）。
点绿旗让作品运行，把卡顿的那一段操作一遍。
点「停止」。

录制期间工具条上有红色的「录制中」，「录制」按钮变成「停止」：

录制中概览页已经在出结论，界面每 500 毫秒刷新一次。录完停下来，数字才是这一整段的平均值。

缓冲有上限：最多留最近 3600 帧（30fps 下约两分钟）、20 万条积木记录。超出后从最早的开始丢弃，所以录得太久只会剩下末尾那一段。

概览页怎么读#

顶上一句话是这段录制的概况：录了几秒、几帧、平均每帧几毫秒。下面五个数：

数	意思	什么时候变红
每帧	一帧里 VM 花掉的总时间（脚本 + 渲染）	超过一帧的预算
帧率	这段录制里实测的帧率	低于 24
最长一帧	这段里最卡的那一帧	超过两帧的预算
超预算的帧	超过预算的帧占多少	超过 20%
绘制	每帧里画面渲染占了多少	超过 6 ms 转橙

一帧的预算跟着作品的帧率走：默认 30 帧每秒，一帧就是 33.3 ms；作品自己设成 60 帧，一帧就是 16.7 ms。面板上写出来的那个数就是当前的预算，后面跟着帧率，例如「超过了 33.3 ms 的预算（30 帧）」。

再下面是结论卡片，那是这个面板最主要的输出。怎么读、有哪些规则，见诊断规则与日志。

帧#

一根柱子一帧，越高越慢。虚线是一帧的预算，线上标着是多少毫秒；超过预算的柱子是红的，到六成以上是橙的。

上面能选看最近 120 / 300 / 900 帧还是「全部」，默认 300 帧。鼠标停在柱子上显示那一帧的详情，点一下柱子，下面会展开：

第一行是这一帧的概况：多少毫秒、几条线程动过 / 帧末还存活几条、执行了多少块积木，以及这一帧是不是编译模式、是不是加速模式。
「绘制」是渲染占的时间。
「其它」是这一帧里既不属于渲染、也不属于下面列出的那几条线程的部分。
再往下是这一帧里最费时的几条线程，点一行跳到那段脚本。

排查间歇性卡顿看这一页：先在图上找出特别高的柱子，点开看当时在运行什么。

线程#

一条「线程」就是一段正在运行的脚本。同一个角色的同一段脚本，即使有几百个克隆体各自运行，也合并成一行；取消上面的「合并克隆体」就会拆开。

列	意思
角色	谁的脚本；克隆体合并时会写「N 个克隆体」
脚本	帽子积木 › 下一块 › 循环体第一块。仅写「当绿旗被点击」无法区分同一角色的多段脚本
每帧	这段脚本平均每帧花多少毫秒
峰值	最费时的那一帧花了多少
块/帧	平均每帧执行多少块积木。旁边有「无等待」标签表示它在一帧内不会停下
状态	运行中 / 等待 Promise / 让出 / 等下一帧 / 已结束

脚本名底下还可能有小字：「不刷新屏幕」说明这段运行在勾了「运行时不刷新屏幕」的自制积木里，「编译」说明它是编译执行的。

表格下面是泳道图，每段脚本一条，横轴与上面的帧图对齐，可以看出某段脚本是一直在运行，还是隔一阵才动一次。最多画 12 条。

最上面那行「现在 N 条线程，M 条在跑」是实时的，不是录制里的。点「展开」能看到此刻每条线程停在哪一块、是什么状态，还能直接把某条线程停下来（见断点与单步）。

积木#

「完整」档才有。按总耗时排，最多列 40 行。

「每帧」是这块积木平均每帧花的毫秒，「次数」是整段录制里被执行了多少次，「占比」是它占所有积木时间的比例。积木名下面那行灰字是它的 opcode，遇到扩展积木或者名字对不上时有用。

点任意一行跳到工作区里那块积木。

这里统计的是自耗时：C 形积木（重复执行、如果…那么）只算它自己判断条件和安排下一轮的开销，循环体里的积木分别计入自己名下；自制积木的调用块也只算调用本身，过程内部的积木单独统计。

事件#

录制期间的广播、帽子、克隆各发生了多少次。

「启动的脚本」是这些事件一共启动了多少条脚本，底下的小字是平均每次启动几条。广播的问题通常就出在这个数上：一次广播启动一百条脚本，和一帧发一百次广播，开销都很大。

「来源」是发出方，最多列前三个。

工作区上的热度#

录「完整」档时，工作区里的积木会按耗时描边，越费时描得越粗越亮。

只描耗时高的那些：低于最热那块 15% 的不画，避免整段脚本连成一片。最热的十几块另外加一层很薄的柔光。颜色和强度在「外观」页调，也能整个关掉。

停止录制之后描边保留，便于对照。切到「轻」档会清除。

保存与对比#

概览页最下面有三颗按钮。

导出 / 导入#

「导出」把这段录制存成一个 .gtrace 文件（就是 JSON）。里面除了四组原始记录，还存了当时翻译好的积木名和脚本名：读回来时作品可能已经改过，甚至不是同一个作品，文字必须跟着记录走。

文件名是标签页标题加导出时间。眼下标签页标题固定是 Gandi 3.0，所以导出的文件叫 Gandi 3.0-20260909-151735.gtrace 这样；导入之后那条提示里显示的名字也是它。

「导入」读回一份。读回来之后概览页顶上会有一条提示：

查看文件时面板不再从 VM 取数据，帧窗口会自动切到「全部」。点「录制」回到实时数据。

它适合排查本机复现不出来的卡顿：让对方录一段发过来。

记为基线#

「记为基线」把当前这段记下来作为参照。之后再录一段，「线程」和「积木」表会多出一列「比基线」，概览的「每帧」和「绘制」下面也带上差值。

绿色的负数是快了，红色的正数是慢了，差不到 0.05 ms 写「持平」，基线里没有的行写「新」。改一处优化、再录一段、对比数字有没有变化，比凭感觉判断可靠。

基线存在内存里，刷新页面即丢失；.gtrace 是文件，可以长期保留。跨天对比时先导出，下次导入之后再「记为基线」。

细节#

「界面开销」这条结论值得重视。 探针只能测到 VM 内的时间。如果脚本只用了几毫秒、帧率却上不去，多半是工作区里积木太多、监视器太多，或者这个面板本身（「完整」档加热度描边）在占用主线程。作品单独运行时没有这部分开销。
关掉面板会停掉录制，工作区上的描边和标记也会收起。舞台上的帧率仪表是独立的：它开着的时候关闭面板不会关掉探针（仪表自身要用）。
面板里的数据每 250 毫秒取一次，录制中界面每 500 毫秒重画一次：二十万条积木记录刷新过勤会拖慢作品本身。
一次只计算当前这一页需要的数据：切到「积木」页才会汇总积木。因此切页时有短暂延迟。