自动化脚本的超时设计：为什么你的等待总是不够

引子

“本地跑得好好的脚本，到 CI 上就超时失败。”这是自动化最常见的抱怨之一。多数时候不是机器慢，而是超时层次没设计：所有等待挤在一个总超时里，页面一慢就全部崩塌。把超时拆开、分级、并配合状态判断，才能既快又稳。

一、超时不是越大越好

把超时统一调大是最省事的做法，但代价是失败发现得晚、流水线被长时间占用。更合理的目标是：

• 正常路径快：成功时用轮询尽早返回；
• 异常路径可控：失败时在有限时间内给出明确错误；
• 总时长有上限：单步慢不能拖垮整个任务。

二、四层超时模型

1. 导航超时：页面跳转/加载的时限，例如 30 秒；
2. 元素等待超时：等待某个元素可见/可点击，例如 15 秒；
3. 断言超时：等待业务状态满足条件，例如 60 秒；
4. 任务总超时：整条流程的上限，例如 10 分钟。

四个值要满足：元素 ≤ 断言 ≤ 导航×次数 ≤ 总超时。否则局部超时永远等不到，总超时先触发。

page.set_default_timeout(15000)
page.set_default_navigation_timeout(30000)

三、轮询优于一次性长等

一次性等待“状态出现”很脆弱，因为条件可能在任何时刻满足。轮询式断言更稳：

def wait_until(fn, timeout=60, interval=2):
    end = time.time() + timeout
    while time.time() < end:
        if fn():
            return True
        time.sleep(interval)
    return False

Playwright 的 expect 本身就是轮询实现，优先用它；自定义轮询只在跨页面/跨接口的复合条件时使用。

四、区分“慢”和“坏”

超时失败不都该重试。建议在捕获异常时记录：耗时、当前 URL、页面关键状态、最近一次接口响应。然后判断：

• 超时但状态其实已完成 → 误报，修正等待条件；
• 超时且状态停在中间 → 可能是下游慢，可重试；
• 超时且状态异常（报错页/登录页） → 不可重试，需修前置条件。

没有这些信息，重试只是把问题放大。

五、退避与熔断

对可重试的超时，使用指数退避并加入随机抖动，避免同一时刻大量请求打满下游：

delay = min(cap, base * 2 ** attempt)
sleep(delay + random.random())

当连续失败达到阈值时，应停止重试并快速失败（熔断），把资源留给其他任务，同时输出明确结论，而不是让流水线一直空转。

六、把超时写进日志

每个关键步骤都记录开始/结束时间与耗时，形成可分析的样本：

t0 = time.time()
do_step()
log(f"step=submit cost={time.time()-t0:.2f}s")

积累一段时间后，就能用真实分布设定超时（例如 P99 的 1.5 倍），而不是拍脑袋。

七、小结

• 超时要分层：导航、元素、断言、总时长各有界限；
• 等待要轮询：条件满足即返回，避免无谓长时间阻塞；
• 失败要分类：误报修条件，可重试才重试，异常快速失败；
• 参数要数据驱动：用耗时分布校准，而不是凭感觉调大。

好的超时设计不是“等得更久”，而是“在该等的地方等，在该停的地方停”。