godot-debugging-profiling

绝对不要做

• 绝对不要在没有说明性上下文的情况下使用 print()——print(value) 毫无用处。请使用带标签的 print("Player health:", health)。
• 绝对不要在发布版本中留下调试打印——请用 if OS.is_debug_build() 包裹，或使用自定义 DEBUG 常量。打印会拖慢发布版本。
• 绝对不要忽略 push_warning() 消息——警告表示可能存在错误（空引用、已弃用的 API）。请在它们变成错误之前修复。
• 绝对不要在发布版本中使用 assert() 进行运行时验证——断言在发布版本中会被禁用。运行时检查请使用 if not condition: push_error()。
• 绝对不要在调试模式下进行性能分析——调试版本的速度会慢 5-10 倍。请始终使用发布导出版本或 --release 标志进行性能分析。
• 绝对不要认为 Engine.capture_script_backtraces(true) 开销很小——捕获局部变量会分配大量内存，还可能阻止对象释放，从而造成虚假的内存泄漏 [19]。
• 绝对不要在自定义的 Logger._log_message 覆盖方法中调用 push_error() 或 print()——这会导致无限递归并造成崩溃，因为日志记录器会拦截自身的输出 [20]。
• 绝对不要在游戏测试期间让 Visual Profiler 持续运行——持续轮询会显著降低帧率，使实际性能指标失真 [21]。
• 绝对不要依赖 OS.get_ticks_msec() 进行微基准测试——毫秒级精度不足以测量逻辑耗时；请务必使用 Time.get_ticks_usec()，以获得微秒级精度 [22]。
• 绝对不要认为 OBJECT_ORPHAN_NODE_COUNT 在生产环境中有效——此监视器仅供调试使用；在发布版本中会安全地返回 0，可能导致内存泄漏被隐藏 [23]。
• 绝对不要在启用 V-Sync 时进行基准测试——V-Sync 会将指标限制在显示器刷新率，掩盖实际的 CPU/GPU 处理开销 [24]。
• 绝对不要在发布版本中留下 print_stack() 或 print_debug()——这些内容通常会被剥离，或在调试器之外毫无用处。生产环境请使用结构化日志记录 [25]。
• 如果使用外部 C++ 性能分析器，绝对不要剥离调试符号——剥离会破坏 Perfetto 或 VerySleepy 等外部工具的调用栈可读性 [26]。
• 绝对不要忘记在 _exit_tree() 中注销 EditorDebuggerPlugin——未能清理会在引擎的调试循环中留下“幽灵”连接 [27]。
• 在 macOS 上使用 Compatibility 渲染器时，绝对不要轻信 Visual Profiler——平台特定的驱动限制会严重影响 macOS 上 OpenGL 性能分析的准确性 [28]。

症状 → 监视器 → 脚本

对应行 必须 使用。针对一个 bug，不要加载所有调试脚本。

症状	监视器 / API	脚本
节点已移除，但 RAM 持续增长	OBJECT_ORPHAN_NODE_COUNT（调试）	必须 orphan_node_detector.gd
ObjectDB / 实例数量增长	自定义监视器 + 转储	memory_usage_threshold_alert.gd、scene_tree_dump.gd
GPU / 过度绘制原因不明	短暂使用 Visual Profiler	搭配性能技能使用；使用 performance_plotter.gd 查看趋势 — 不要让 Visual Profiler 一直开启
无头模式 / CI 退出不稳定	退出代码 + 断言	必须 automated_qa_suite.gd、push_error_safe_exit.gd
微基准测试结果不准	Time.get_ticks_usec	必须 high_precision_benchmarker.gd
崩溃时需要局部变量	回溯（仅调试模式）	advanced_backtrace_recorder.gd、stack_trace_logger.gd
将引擎错误发送到后端	Logger 拦截	engine_error_interceptor.gd — 切勿在 Logger 内打印
自定义调试器指标	Monitors 选项卡	custom_editor_monitor.gd、debugger_tab_plugin.gd
移动端 / 主机没有标准输出	游戏内控制台	remote_debug_console.gd、debug_overlay.gd（仅限调试版本）
线程竞争 / 日志损坏	互斥锁日志记录器 / 断言	thread_safe_logger.gd、thread_safety_assert.gd
不可见逻辑（AI/物理）	调试绘制 / Gizmo	custom_debug_draw.gd、property_watcher_gizmo.gd
条件暂停	硬编码断点	break_on_condition.gd
编辑器与运行时路径	Engine.is_editor_hint	engine_editor_hint_logic.gd

可用脚本（完整目录）

泄漏与内存

• orphan_node_detector.gd
• memory_usage_threshold_alert.gd
• scene_tree_dump.gd

计时与 QA

• high_precision_benchmarker.gd
• automated_qa_suite.gd
• push_error_safe_exit.gd
• performance_plotter.gd

错误、堆栈与线程

• advanced_backtrace_recorder.gd
• stack_trace_logger.gd
• engine_error_interceptor.gd
• thread_safe_logger.gd
• thread_safety_assert.gd

编辑器 / 远程 / 可视化

• custom_editor_monitor.gd
• debugger_tab_plugin.gd — 在 _exit_tree() 中注销
• remote_debug_console.gd
• debug_overlay.gd — 仅限调试版本
• custom_debug_draw.gd
• property_watcher_gizmo.gd
• break_on_condition.gd
• engine_editor_hint_logic.gd

专家提示

• 关闭 V-Sync 后，对 release/--release 版本进行性能分析；切勿相信 Debug 构建的计时数据。
• 对于任何可能发布的内容，优先使用结构化日志，而不是 print_stack()。
• 如果症状树识别出瓶颈类型后，FPS 问题仍持续存在，请升级至 godot-performance-optimization。

MANDATORY：关于 print/断点工作流的深度内容、性能分析器解读，以及专家级 CI/GPU/线程模式，请参阅 debug-workflows.md。如果上方的症状 → 脚本表已为你指明方向，则不要加载。

参考

渐进式披露：只有在研究特定 API 时才打开官方文档链接；只有在需要转至相关领域时才加载相关技能——不要预加载整个知识体系。

官方文档

• 调试工具概览 — 在选择更深入的文档页面前，了解远程场景树、断点、Output 和性能分析器的入口。
• 调试器面板 — 实时远程调试会话中使用的堆栈、变量、断点、错误和监视器。
• 性能分析器 — 时间和可视化性能分析器：为何要分析接近发布版本的构建，以及帧图表如何定位 CPU/GPU 峰值。
• Output 面板 — print / push_warning / push_error 如何显示在编辑器中，以及为何嘈杂的发布日志会掩盖真正的问题。
• ObjectDB 性能分析器 — RefCounted 循环和泄漏实例的前后 ObjectDB 快照，这些问题可能无法被孤立的监视器发现。
• 自定义性能监视器 — 使用 Performance.add_custom_monitor，让游戏专属指标与引擎监视器并列显示。
• 日志记录 — 自定义 Logger 注册、文件接收器，以及在日志处理程序内部记录日志时的递归风险。
• 命令行教程 — 用于自动化 QA 和 CI 退出码运行器的无头 --script / 导出标志。
• CPU 优化 — 测量后，如何将性能分析器热点转化为 GDScript/服务器/线程方面的修复。
• 使用多个线程 — 工作线程规则，为线程安全断言和互斥锁保护的日志记录器提供依据。
• 线程安全 API — 哪些服务器/API 可以在非主线程中调用而不会破坏 SceneTree。
• 性能 — 用于覆盖层和泄漏检测器的内置监视器（OBJECT_ORPHAN_NODE_COUNT、内存、渲染）。

相关技能

前置条件

• godot-project-foundations — 在使用调试器插件或全局监视器前，必须先配置调试/发布功能标签、项目设置和 Autoload 布局。
• godot-gdscript-mastery — 类型化 Callables、assert/push_error 和 Time API 是基准测试、断点和堆栈辅助工具的基础。

补充技能

• godot-performance-optimization — 分析器指出热点后，使用该技能中的对象池、剔除和 MultiMesh 修复方案。
• godot-testing-patterns — GUT/assert/CI 模式可与无头 QA 测试套件和确定性的 quit 退出代码配合使用。
• godot-export-builds — 使用真实导出模板进行性能分析和远程调试；调试符号和 strip 设置会影响外部分析器。
• godot-scene-management — 场景切换的生命周期错误会表现为孤立节点不断增加；加载器未能释放节点时，请使用树转储。
• godot-signal-architecture — 幽灵监听器和延迟连接常常能解释“为什么它还在运行？”这类堆栈跟踪。
• godot-autoload-architecture — 全局日志记录器、监视器和错误拦截器应放在 Autoload 中，并明确启动顺序。
• godot-server-architecture — 调试绘制或指标涉及 Rendering/Physics 服务时，请将服务所有权与节点分开。

下游／使用方

• godot-auditor — 在执行禁用列表和架构完整性审查时，使用调试器／分析器提供的证据。
• godot-platform-mobile — 桌面端 Output 不可用时，必须使用设备远程调试和屏幕控制台。
• godot-monte-carlo-balancer — 无头微基准测试和 CI QA 为平衡模拟提供数据；此类模拟需要稳定的计时和退出代码。
• godot-multiplayer-networking — 网络游戏需要在各个对等端使用远程检查器和结构化日志，同时避免 Output 面板被刷屏。

主技能

• godot-master — 技能库路由器和镜像模块入口；发现哪个领域技能负责跨领域调试或性能问题时，请打开此项。