Godot协程等待机制：从裸await到可取消超时等待库

上周帮一位朋友看他那个小型横版项目，翻到关卡流程脚本时我愣了一下：一个 400 行的文件里塞了三十七处await get_tree().create_timer(...).timeout，还有十几处裸await各种信号，中间夹着两三个queue_free()。我问他这套跑起来稳不稳，他说“偶尔会报错，但重开一局就好了”。这基本就是 Godot 引擎里异步编程的典型状态——协程太好用，好用到大家直接在业务代码里随手撒，等到项目规模上来，暂停失效、节点释放后协程还在跑、超时等待没有统一出口这些问题会一起爆发。这篇就聊我怎么给项目做一套基于协程的等待机制库：把seconds、frames、until、race、取消令牌这些东西收进一个自动加载单例里，让业务层的异步写法从“随手撒 await”变成“有约定、可取消、能超时、停得下来”。适合已经写过await但被坑过的人，也适合刚接触协程、想一次性把姿势摆正的人。

1. 先把问题摆上桌：原生 await 到底卡在哪里

1.1 一行 await 背后的三笔隐性成本

很多人对await get_tree().create_timer(0.5).timeout的理解是“等半秒”，但从引擎角度看，这一行至少做了三件事：创建一个SceneTreeTimer对象、把它挂到 SceneTree 的计时器链表上、把当前协程挂起并在信号触发时恢复。三件事本身都不贵，问题出在它们都不受你控制。

第一笔成本是生命周期脱钩。协程挂起之后，它和发起它的节点之间就没有强绑定了。你在一个子弹节点里await了一秒，一秒内子弹撞墙被queue_free()，一秒后协程照样恢复执行，然后访问self.position就直接抛 “Attempt to call function on a previously freed instance”。这个报错堆栈往往指向 await 之后的第一行，很容易误判成那一行写错了。

第二笔成本是时钟语义模糊。create_timer的签名有四个参数，默认值决定了它“暂停时照样走、不受 time_scale 影响、跑在 idle 帧上”。也就是说，你在暂停菜单打开时写的等待，默认是会继续推进的；你把Engine.time_scale调到 0.1 做子弹时间，默认计时器还是按真实秒数跑。等发现“慢动作里技能前摇没变慢”时，你已经在十几个文件里写死了默认值。

第三笔成本是没有统一出口。超时怎么办？玩家中途取消施法怎么办？节点被回收怎么办？原生写法里这三个问题的答案分散在每个调用点，有人用if not is_instance_valid(self): return补，有人靠await一个额外的取消信号补，补法各不相同。等到要排查一个“偶发卡死”的 bug，你得把整个调用链的 await 全看一遍。

1.2 我需要的等待能力清单

在动手之前我列了张表，把项目里出现过的等待需求全部归类，这张表后来直接变成了库的 API 设计依据。

注意：这张表里最容易被忽略的是最后一行。取消能力不是“锦上添花”，它是把异步代码从“能跑”提升到“可控”的分水岭。后面所有 API 都会带一个可选的token参数，原因就在这里。

1.3 为什么选择自己写而不是拼凑

市面上当然有现成的异步工具思路，比如基于 Task/Promise 风格封装的第三方方案。我没选它们，原因有三个，都是踩过之后的判断。

一是风格冲突。Promise 风格需要业务代码改成Task.new(func(): ...)的层层嵌套，和 GDScript 原生的await语法打架。团队里新人看到两套写法会本能地挑简单的用，最后库没人用，代码风格还更乱。而基于await的薄封装，学习成本几乎为零——它就是原生写法的语法糖。

二是依赖风险。小项目引入第三方库，版本升级、引擎大版本迁移时都要跟着改。核心机制其实只有两三百行，自己维护反而更省心，出问题能直接断点进去看。

三是可裁剪。我要的是“刚好够用”，不是完整的异步运行时。不需要调度器、不需要线程池、不需要任务树，只要把信号和计时器包一层，加上取消和超时。这个体量自己写一天就能落地，剩下全是收益。

选型的核心判断是：这套东西必须能贴着原生写法长出来，让业务层写await Wait.seconds(0.3)和写await get_tree().create_timer(0.3).timeout的肌肉记忆完全一致，只是前者多了取消、超时和正确的暂停语义。

2. 协程运行机制拆解：await 挂起之后发生了什么

2.1 GDScript 协程不是线程，是带状态的函数

这一节必须先讲清楚，否则后面所有细节都是背口诀。GDScript 的函数只要体内出现await关键字，它就会被编译器标记成协程。调用它的时候不会一路执行到底，而是执行到第一个await就挂起，把当前的局部变量、执行位置打包成一个状态对象存起来，然后把控制权还给调用者。

这带来一个非常反直觉的后果：调用一个协程函数时如果不写await，它照样会执行，只是执行到第一个await就停了，后面的代码永远不会跑。项目里最典型的事故是这样的：

func _ready() -> void: play_intro() # 忘了写 await print("开场结束") # 这行会立刻打印，而不是等开场播完 func play_intro() -> void: await Wait.seconds(1.0) print("真正开场")

打印顺序会把人看懵。更坑的是如果play_intro()体内没有await，那await play_intro()又会报 “Trying to await on a value that is not a signal or a coroutine”。所以整个库的第一条约定就是：凡是内部带 await 的函数，命名上要能让人一眼看出它是异步的。我的习惯是动词开头加_async后缀，或者干脆放在seq_前缀的流程函数里，靠命名区分。

还有一点要明确：协程全部跑在主线程，它不解决并行计算问题。await期间主线程该干嘛干嘛，只是这个函数的执行被拆成了若干片。所以不要指望用协程去做大计算量的解耦，那需要真正的线程。

2.2 await 能等的两种东西

GDScript 的await只认两类右值：信号和协程。信号好理解，timeout、finished、pressed都是。协程指的是“调用一个体内含 await 的函数所返回的状态”，你可以await Wait.seconds(1.0)，因为seconds本身是协程。

这两类右值的语义差别在于恢复时机。等信号，是信号emit的那一刻同步恢复——注意是同步，也就是恢复代码就跑在emit的调用栈里面。这一点后面会专门讲坑，因为很多“在信号回调里 free 节点导致崩溃”的问题都来源于此。等协程，则是那个协程彻底 return 之后才恢复，如果它内部还有 await，恢复时机自然被推后。

还有个细节：等信号时如果信号带参数，await的返回值就是那个参数（单参数时）。这功能挺好用，比如自定义的data_ready(data)信号，var d = await some_node.data_ready直接拿到数据。但多参数信号只会返回第一个参数，这个限制要知道。

2.3 生命周期失控的三种典型死法

我把项目里遇到过的崩溃归了三类，每一类都对应后面的一个设计决策。

死在节点释放上。协程恢复时访问已释放的节点，这是最高频的一类。判断方法很简单：所有await之后的第一行，如果碰了self或者别的节点引用，就必须有有效性检查。库的解法是让等待本身可以绑定作用域，作用域失效时自动取消等待，协程直接返回，不会走到危险代码。

死在场景切换上。change_scene_to_file或reload_current_scene之后，旧场景整棵树被释放，挂在旧节点上的协程全部变成孤儿。如果这些协程还在等一个永远不会再来的信号（比如旧 UI 的按钮），那就是永久泄漏。库的解法是超时 + 令牌，让每一次等待都有上限。

死在暂停与时间缩放上。Engine.time_scale = 0配合默认参数的计时器，会让等待永远不会结束；反过来，暂停菜单打开时用默认计时器做倒计时，倒计时会继续走。这两个问题都不报错，只是行为不对，排查起来纯粹靠经验。解法是把时钟语义显式化，默认跟随游戏时间，需要真实时间的地方用专门的变体。

3. 从零搭一个 Wait 单例：核心 API 与实现

3.1 目录结构与自动加载配置

库只有一个文件，放在res://addons/wait/wait.gd，然后在项目设置里注册为自动加载。自动加载有两点必须确认：一是节点名就叫Wait，业务层才能写Wait.seconds()；二是在自动加载列表里的顺序不敏感，因为它不依赖其他全局单例。

# res://addons/wait/wait.gd extends Node ## 协程等待工具。所有方法返回 bool 时，true 表示正常完成， ## false 表示被取消或超时。 const DEFAULT_POLL := 0.0

结构上我把内部工具类写成内嵌类，因为它们只服务于这个单例，没必要暴露成独立文件。Token会被业务层直接 new，所以要class_name之外的方式暴露——用Wait.Token.new()就够了，内嵌类可以通过外部类名访问。

提示：不要让这个单例持有任何游戏状态。它应该是个纯工具，谁调用谁负责传参数。一旦单例里塞了缓存或者上下文，它就会变成新的全局状态沼泽。

3.2 时间等待：seconds 的四个语义维度

seconds是使用频率最高的方法，它需要覆盖四种组合：跟随/忽略暂停、跟随/忽略时间缩放。我用两个方法覆盖，主方法跟随游戏时间，变体覆盖真实时间。

func seconds(t: float, token: Token = null) -> bool: if t <= 0.0: await get_tree().process_frame return token == null or not token.is_canceled() # 参数依次为：时长、暂停时是否继续、是否在物理帧计时、是否忽略时间缩放 var timer := get_tree().create_timer(t, false, false, false) if token == null: await timer.timeout return true var idx := await _race([timer.timeout, token.canceled]) return idx == 0

三个参数的选择理由值得逐条说。process_always传false，意思是暂停时计时器也停下，这符合“暂停就是一切都停”的直觉；如果想做“暂停时界面动效继续”，用下面那个真实时间变体。process_in_physics传false，因为绝大多数等待是表现层的，跑在 idle 帧足够；只有在物理逻辑里做严格步进的等待时才需要打开。ignore_time_scale传false，让等待跟着游戏节奏走，做慢动作时前摇自然变长。

func seconds_realtime(t: float) -> void: # 无视暂停与时间缩放，用于 UI 动效、日志节流等场景 await get_tree().create_timer(t, true, false, true).timeout

t <= 0的边界处理单独说一句。create_timer(0)在实测中会在当前帧的计时器处理阶段触发，而不是“下一帧”，这会让“延迟到下一帧”的意图失效。所以零和负数统一走process_frame，行为可预测。

再强调一个数值上的注意点：如果游戏里Engine.time_scale可能被设成 0（比如做冻结效果），那么走游戏时间的seconds会永久挂起。这不是 bug 是特性，但业务代码里最好配超时或者改用 realtime，否则冻结结束时你会看到一堆等待同时解冻。

3.3 帧等待：别小看这一帧的差别

frames和physics_frames的实现只有几行，但用错场景会出很隐蔽的问题。

func frames(n: int = 1) -> void: for i in n: await get_tree().process_frame func physics_frames(n: int = 1) -> void: for i in n: await get_tree().physics_frame

关键认知是：process_frame信号在暂停状态下依然会发射。暂停只是让节点的_process和_physics_process不再被调用，SceneTree 的帧信号不受影响。这意味着在暂停菜单里await Wait.frames(1)不会卡死，而await Wait.seconds(0.1)会卡死。这个差异非常有用——想做“等一帧让 UI 布局刷新完再取尺寸”，就用frames，它在任何状态下都安全。

physics_frames的使用场景窄一些，主要用于“等下一次物理步进之后再做判定”。比如刚给刚体设置了linear_velocity，想读它被物理引擎处理后的位置，就必须等一个物理帧，否则读到的还是旧值。在_physics_process里 awaitprocess_frame是大忌，会导致协程的恢复时机和物理步进错位，节奏类玩法里能直接看出抖动。

3.4 信号等待与取消令牌

取消令牌是一个极简的可观察对象。

class Token extends RefCounted: signal canceled var _canceled := false func cancel() -> void: if _canceled: return _canceled = true canceled.emit() func is_canceled() -> bool: return _canceled

为什么用RefCounted而不是Node：令牌要被到处传递，用 Node 就得考虑谁负责free，一旦传给了不该接管生命周期的地方就会泄漏或者被提前释放。RefCounted靠引用计数，谁都不持有时自动回收，语义刚好。

为什么cancel()要幂等：实际使用中很可能出现“玩家按 ESC 取消施法”和“角色死亡强制取消”同时触发的情况，如果不做去重，canceled会发两次，导致下游的重入问题。加上if _canceled: return这一行，成本为零。

基于令牌，信号等待可以带上超时：

func wait_signal(sig: Signal, timeout_sec: float = -1.0, token: Token = null) -> bool: var entries: Array = [sig] if timeout_sec > 0.0: entries.append(get_tree().create_timer(timeout_sec, false).timeout) if token != null: entries.append(token.canceled) var idx := await _race(entries) return idx == 0

返回值true表示信号正常到达，false表示超时或被取消。业务代码里最典型的用法是这样：

func play_hit_async() -> void: var token := Wait.Token.new() var anim := $AnimationPlayer anim.play("hit") var ok := await Wait.wait_signal(anim.animation_finished, 2.0, token) if not ok: push_warning("受击动画未按预期结束") anim.stop()

这里的超时不是为了“优雅”，是为了兜底。动画事件因为状态机切换没触发、因为节点被禁用没触发，这类问题在测试期间经常出现，有超时至少能让流程继续往下走，而不是整个角色卡在受击状态。

4. 进阶能力：超时、竞速、并行与条件等待

4.1 race：谁先到谁赢，这是所有超时的底座

_race是整个库的地基，超时、取消、信号竞速全靠它。

class _Race extends RefCounted: signal _arrived(index: int) var winner := -1 var _slots: Array = [] func run(signals: Array) -> int: for i in signals.size(): var sig: Signal = signals[i] if not sig.is_valid(): continue var cb := _make_cb(i) sig.connect(cb, CONNECT_ONE_SHOT) _slots.append([sig, cb]) if _slots.is_empty(): return -1 await _arrived _clear() return winner func _make_cb(index: int) -> Callable: return func(_a = null, _b = null, _c = null, _d = null) -> void: if winner != -1: return winner = index _arrived.emit(index) func _clear() -> void: for slot in _slots: var sig: Signal = slot[0] var cb: Callable = slot[1] if sig.is_valid() and sig.is_connected(cb): sig.disconnect(cb) _slots.clear()

几个实现选择要解释清楚。CONNECT_ONE_SHOT让赢家信号自动断开，省掉一次手动清理，也避免了信号二次触发重入。_make_cb返回的 lambda 带四个带默认值的参数，这样无论信号本身带零个还是三四个参数，回调签名都能匹配——GDScript 没有可变参数，这是绕开参数数量限制的实用技巧，直接写func(_a = null)会在信号带参数时崩。

winner != -1的短路判断是必须的：如果超时定时器和业务信号在同一帧的极短间隔内先后触发，没有这个判断就会恢复两次，而协程只能恢复一次，第二次会触发引擎警告。

还有一个必须写进注释的细节：_clear()是在await _arrived之后执行的，而 Godot 的信号恢复是同步的，这意味着_clear()实际跑在赢家信号的 emit 调用栈里。在绝大多数情况下这没问题，但如果赢家信号的发射者本身正处在释放流程中，手动disconnect可能撞上边缘情况。稳妥的写法是把清理延后一帧：

await _arrived await get_tree().process_frame # 让 emit 栈退干净再清理 _clear()

代价是竞速结束后多等一帧才返回，对表现层影响可以忽略，但对“必须同帧生效”的逻辑要留意。我最后的取舍是把清理放在call_deferred里，返回值不等清理完成——既避开了 emit 栈，也不影响时序。

4.2 until：条件轮询，把标志位从 _process 里救出来

之前项目里判断“角色是否落地”，写法是在_process里每帧检查is_on_floor()，然后置一个布尔让别的地方轮询。这种标志位写法在多个系统里叠加后会变成一团乱麻。until把这种需求变成一行等待。

func until(cond: Callable, timeout_sec: float = -1.0, poll_interval: float = 0.0, token: Token = null) -> bool: var elapsed := 0.0 while true: if cond.call(): return true if token != null and token.is_canceled(): return false if timeout_sec >= 0.0 and elapsed >= timeout_sec: return false if poll_interval > 0.0: if not await seconds(poll_interval, token): return false elapsed += poll_interval else: await get_tree().process_frame elapsed += get_process_delta_time()

poll_interval默认为 0 表示逐帧检查。逐帧检查的好处是响应及时，坏处是条件本身较重时（比如遍历一个列表）会吃 CPU。经验值是：简单条件逐帧，涉及遍历、查找、物理射线的条件用 0.1 到 0.2 秒的轮询间隔，肉眼完全看不出延迟。

用法很直观：

var ok := await Wait.until(func() -> bool: return is_on_floor(), 3.0) if not ok: push_warning("落地超时，强制切换状态")

有个陷阱要注意：cond.call()里如果引用了一个可能被释放的对象，每次调用都会报错。所以条件 lambda 里要么只用self的状态，要么先做is_instance_valid判断。

4.3 all_of：并行等待的计数器写法

等全部完成要维护计数，用一个小对象最干净。

class _Countdown extends RefCounted: signal _done var left := 0 func _init(n: int) -> void: left = n func tick(_a = null, _b = null, _c = null) -> void: left -= 1 if left <= 0: _done.emit()

func all_of(signals: Array) -> void: var valid := 0 for s in signals: if s is Signal and s.is_valid(): valid += 1 if valid == 0: return var c := _Countdown.new(valid) for s in signals: if s is Signal and s.is_valid(): s.connect(c.tick, CONNECT_ONE_SHOT) await c._done

并行等待最容易踩的坑是部分信号永远不会来，导致all_of永久挂起。所以我在实际项目里几乎不用裸all_of，而是套一层wait_signal超时，或者干脆给all_of也加个超时参数。

4.4 与 Tween、AnimationPlayer、资源加载的对接

这几个引擎内置对象都有现成信号，不需要额外封装，但用法上有各自的注意点。

Tween 的finished信号在 Tween 被kill()时不会发射。如果业务里有“中途打断 Tween”的可能，await tween.finished就会永久挂起。正确做法是配合超时：

func tween_async(tw: Tween, timeout_sec: float = 5.0) -> bool: return await Wait.wait_signal(tw.finished, timeout_sec)

AnimationPlayer.animation_finished的坑在于它携带一个动画名参数，而且切换到同名动画时不会触发。如果连续两次播放同一个动画名，第二次结束时这个信号只在第一次结束时发过一次，判断逻辑要写充分。

资源异步加载在 Godot 4 里用ResourceLoader.load_threaded_request加轮询状态，这个轮询非常适合用until包起来：

func load_async(path: String, timeout_sec: float = 10.0) -> Resource: ResourceLoader.load_threaded_request(path) var status := ResourceLoader.load_threaded_get_status(path) var ok := await Wait.until( func() -> bool: status = ResourceLoader.load_threaded_get_status(path) return status != ResourceLoader.THREAD_LOAD_IN_PROGRESS, timeout_sec, 0.05) if not ok or status != ResourceLoader.THREAD_LOAD_LOADED: push_error("资源加载失败: %s" % path) return null return ResourceLoader.load_threaded_get(path)

这里用 0.05 秒轮询而不是逐帧，是为了避免加载大资源时主线程被频繁打断。实测下来 20 次/秒的状态查询开销可以忽略，加载完成到拿到资源的感知延迟也在 50ms 以内，玩家感受不到。

5. 落地实战：三个真实场景的编排

5.1 关卡加载与淡入淡出

加载流程是最能体现协程价值的场景，因为它天然是“顺序 + 并行的混合”。我的写法是把每个阶段拆成独立的异步函数，主流程只负责编排。

func enter_level_async(level_id: String) -> void: var token := Wait.Token.new() $LoadingUI.open() # 阶段一：加载与最小停留时间并行，避免闪一下就过去 var scene_path := "res://levels/%s.tscn" % level_id ResourceLoader.load_threaded_request(scene_path) var min_show := Wait.seconds(0.6) var loaded := false loaded = await Wait.until( func() -> bool: return ResourceLoader.load_threaded_get_status(scene_path) == \ ResourceLoader.THREAD_LOAD_LOADED, 8.0, 0.05, token) await min_show # 保证加载界面至少显示 0.6 秒 if not loaded: push_error("关卡加载失败: %s" % level_id) $LoadingUI.close() return # 阶段二：切换场景并淡入 get_tree().change_scene_to_packed( ResourceLoader.load_threaded_get(scene_path)) await Wait.frames(2) # 等新场景 _ready 与布局完成 await $Fade.fade_in_async() # 淡入本身也是协程 $LoadingUI.close()

三个细节值得说。Wait.frames(2)而不是 1，是因为change_scene_to_packed是延迟生效的，新场景的实际挂载要到当前帧末尾，第二个帧信号才是新场景布局完成的安全点。min_show那个协程是先启动后等待，启动时就开始了计时，这样它和资源加载是真正并行的；如果写成先await 加载再await 0.6 秒，总时长就变成两者相加。token一路透传下去，玩家点“取消”能立刻中断整条流程。

注意：change_scene_to_packed之后旧场景的节点会被释放，但你的协程是在一个独立的对象上跑的（自动加载单例调用方），所以不会跟着死。不过如果这个enter_level_async是挂在旧场景的节点上，就必须在切换前把后续逻辑挪走，否则第二帧恢复时self已经失效了。

5.2 技能时序与打断

动作游戏的技能是协程的经典用法：前摇、判定、后摇、可打断窗口。核心是把打断能力做成信号 + 令牌的组合。

func cast_skill_async(skill: Dictionary) -> void: var token := Wait.Token.new() current_cast_token = token # 前摇，期间可被移动输入打断 var anim := $AnimationPlayer anim.play(skill.anim) var interrupted := await Wait.wait_signal( $InputWatcher.move_pressed, skill.windup, token) if interrupted or token.is_canceled(): anim.stop() _push_cast_failed("windup_broken") return # 判定帧 var hit_ok := await Wait.wait_signal($HitBox.hit_confirmed, 0.2) if not hit_ok: _push_cast_failed("no_target") # 后摇不可打断 await Wait.seconds(skill.recovery) current_cast_token = null

current_cast_token存成成员变量是关键设计：角色死亡、受击硬直、手动取消，任何一个系统想打断施法，只需要if current_cast_token: current_cast_token.cancel()，不用知道施法流程内部等到了哪一步。这就是把“取消”从业务逻辑里抽出来的收益。

用wait_signal等输入而不是每帧轮询Input.is_action_just_pressed，好处是不会丢输入——信号在等待建立之后的事件都能收到，而轮询如果在两帧之间按下就会漏。这个差异在低帧率下手感差别非常明显。

5.3 UI 弹窗队列

UI 弹窗最烦的问题是“两个弹窗同时出来”。用协程队列可以做到天然串行。

var _popup_queue: Array[Callable] = [] var _popup_busy := false func enqueue_popup(show_fn: Callable) -> void: _popup_queue.append(show_fn) if not _popup_busy: _drain_popups() func _drain_popups() -> void: _popup_busy = true while not _popup_queue.is_empty(): var fn: Callable = _popup_queue.pop_front() var done := await _show_popup_async(fn) if not done: break _popup_busy = false func _show_popup_async(fn: Callable) -> bool: var panel: Control = fn.call() panel.modulate.a = 0.0 var tw := create_tween() tw.tween_property(panel, "modulate:a", 1.0, 0.15) await Wait.wait_signal(tw.finished, 1.0) var token := Wait.Token.new() var closed := await Wait.wait_signal(panel.close_requested, 10.0, token) if not closed: token.cancel() var tw2 := create_tween() tw2.tween_property(panel, "modulate:a", 0.0, 0.12) await Wait.wait_signal(tw2.finished, 0.5) panel.queue_free() return true

_popup_busy这个布尔是必须的，因为_drain_popups本身是协程，从第一次await开始就返回了，如果不加标记，第二次enqueue会再开一个 drain 循环，队列就被两个循环同时消费了。这是协程编程里最常见的并发错误——协程函数调用返回了，不代表逻辑执行完了。

6. 踩坑记录与排查速查表

6.1 报错信息与定位路径

几个反复出现的报错，附上我的定位习惯。

Attempt to call function 'x' in base 'previously freed' on a null instance，翻成大白话就是“await 之后碰了已释放对象”。定位方法是把堆栈定位到具体行，看这一行用了哪个对象，然后往前找这个对象的释放点。修法优先用令牌取消，而不是撒is_instance_valid检查——后者是治标，而且检查完到实际使用之间还有窗口期。

Trying to await on a value that is not a signal or a coroutine，九成是 await 了一个没有await关键字的普通函数。少数情况是信号名拼错，而 GDScript 对属性访问比较宽松，拼错可能返回 null 而不是报错。

Signal 'timeout' is already connected，出现在重复连接同一对 signal-callable 时。用_race这种统一封装就不会有这个问题，因为每次都是新的 lambda 引用。

6.2 暂停、时间缩放、帧率的三重叠加

这三个因素叠在一起时，行为最不可预测。我做过一组实测，结论整理如下：

最后一行容易被忽略：frames(1)在 20fps 下等价于 50 毫秒，在 144fps 下等价于 7 毫秒。所以帧数等待只适合表达“逻辑上的下一帧”，绝不能用来表达“大约 10 毫秒”。凡是有时间语义的需求，一律走seconds。

6.3 性能与内存：协程不是免费的

create_timer每次调用都会创建一个SceneTreeTimer。我做过一个粗糙的压测：在_process里每帧创建 5000 个 1 秒计时器，帧时间从 2ms 涨到 9ms 左右。结论是大规模延迟（比如成百上千个特效对象的独立延迟）不适合每个对象一个计时器，应该改用中心化的计时器列表，每帧只遍历一次。

协程本身也有内存开销，每个挂起的协程要保存局部变量栈。之前遇到过一个隐蔽泄漏：某个“等待玩家点击”的协程，玩家一直不点，协程就一直挂着，而它捕获了整棵 UI 节点树的引用，导致切场景后这些节点都没法释放。修法就是加超时——所有等待都应该有上限，哪怕上限设成 600 秒，它也能保证最坏情况下系统能自愈。

6.4 速查表

整理下来我自己最常用的三条经验，写在这里给后面的项目省点时间。第一，默认带超时，除了明确知道必然触发的引擎信号，其它等待全部设置上限，这个习惯能消灭八成“偶发卡死”。第二，取消令牌跟着对象走，把 token 存在发起者身上，谁想取消谁调用，别让取消逻辑散在各处。第三，异步函数命名要暴露异步性质，这比任何注释都有效，因为调用点的人往往只看函数名就决定要不要写 await。

这套库在我们这边跑了大半年，代码量三百行出头，业务层的await从散落各处的裸调用变成了统一的Wait.xxx。真正让我觉得值的是排查问题时的心态变化：以前看到卡死只能一行行翻 await，现在先看有没有超时日志，再看令牌有没有被取消，定位时间从半天缩短到几分钟。