tqsdk 退出卡死？一文搞懂 close() 与线程清理的排查方法

用 tqsdk 跑量化策略，如果你以前只写过普通脚本，大概率会在“退出”这个环节卡上几分钟甚至半天。策略逻辑走完了，print("done") 也打印了，但命令行就是不回到提示符，最后只能强行关终端。这篇文章就专门聊 tqsdk 的线程退出问题，重点就是怎么把 close() 用对，以及遇到“程序像个钉子户一样赖着不走”的时候，从哪几个方向排查。

这个问题的覆盖面比想象中大：单线程策略有人遇到，多线程策略有人遇到，连在 Jupyter 里跑个演示脚本也会遇到。很多人第一反应是“是不是代码死循环了”，但其实大多数情况根本不是逻辑问题，而是 tqsdk 的线程模型和普通 Python 脚本不一样，退出方式没跟上。下面我从现象讲起，拆清楚原因，再给几套可以直接抄的退出写法。

1. 问题现象：程序卡住不出来，比你想的更隐蔽

1.1 “脚本走完但进程不消失”的诡异现场

先说最常见的现象。你写一个简单的行情订阅脚本，订阅一个合约，循环里打印最新价，循环条件满足了、退出循环了，代码最后一行也执行完了，可是整个进程就是挂在那里不结束。理论上 Python 脚本执行完最后一个语句，解释器就会清理资源然后退出，但你发现终端里没有回到 shell 提示符，只能 Ctrl+C 去中断。

这背后的机制其实不复杂。Python 解释器有一个重要规则：当主线程执行完所有代码后，并不立刻退出进程，而是要等待所有非守护线程结束后才退出。所谓非守护线程，就是没有设置 daemon=True 的线程。可以打个比方：主线程是收拾好行李准备锁门离开的住客，非 daemon 线程是房子里另一个不肯走的室友，只要这个室友还在，房东就不允许退房，门就一直锁不上。而 daemon 线程是“随时可以被房东赶走”的室友，主线程一撤，这些后台线程会被直接终止，不需要等待它们收拾东西。tqsdk 内部启动的推送线程、通信线程默认并不是 daemon 线程，所以主线程跑完了，进程依然被这些“室友”拖住，看起来就像程序卡死了。

1.2 Ctrl+C 也救不了场的时候

有些朋友会尝试用 Ctrl+C 来中断，以为强行结束总能退出。但在 tqsdk 的场景里，Ctrl+C 经常表现得“失灵”。如果你没在代码里做信号处理，Ctrl+C 默认会抛出 KeyboardInterrupt。抛出来之后，如果主线程正好阻塞在 wait_update() 里，这个异常不一定能马上打断当前的阻塞流程，因为 wait_update() 内部可能正在等待一个事件，或者正处于内部请求的过程中，中断信号会被延迟处理。

更麻烦的是，就算 KeyboardInterrupt 抛出来了，如果你没有在 except 或 finally 中调用 api.close()，那些非 daemon 后台线程依然存活。于是你看到的现象就是：按了几下 Ctrl+C，Python 答应了中断，但进程还是不退出，或者退出得很慢，过好几秒才死掉。这种“半死不死”的状态比完全不响应更让人头大，因为你不知道程序到底有没有清理干净。

1.3 重启策略时提示连接失败或端口占用

这个现象通常在二次运行的时候出现。第一次运行程序，你实在受不了就强制结束了终端，或者直接 kill 掉进程，感觉已经清理了。等你再改一下代码重新运行，创建 TqApi() 的时候却报连接失败、端口被占用之类的错误。这说明上一次运行的后台资源根本没有清理干净。

tqsdk 并不是一个纯 Python 库，它创建 API 实例时，会在本机拉起后台服务进程，并和它通过本地通信端口交换数据。你强行杀掉 Python 进程，这个后台服务可能还残留在系统里。旧连接没释放，新的 TqApi() 自然没法正常绑定端口和通信通道。所以线程退出问题不只是“看起来卡”，它还会直接影响你后续的开发调试节奏。

2. 先搞清楚 tqsdk 背后是怎么跑的，再来谈“退出”

2.1 一个 TqApi() 背后不止一个 Python 线程

很多人把 TqApi() 当成普通的 Python 对象，创建完就只关心引用它的变量。实际上，TqApi() 一旦创建，背后会做几件关键的事情：启动事件循环、建立本地通信通道、连接远程行情服务器，并根据需要拉起交易网关。在 Python 进程内部，会有至少一两个工作线程在轮询和处理网络事件，这些线程就是你退出时的主要障碍。

理解这一点很重要，因为很多退出问题并不是你的策略循环写错了，而是这些内部线程还活着。你写的代码只是主线程里的业务逻辑，真正让进程“赖着不走”的是那些你看不见的后台线程。所以在设计退出方案时，目标不是“结束自己的逻辑”，而是“让这些后台线程都能安全收尾”，而让它们收尾的唯一正规途径，就是调用 close()。

2.2 wait_update() 为什么能让线程挂死

wait_update() 是 tqsdk 里最核心的阻塞函数，它会等待数据事件，比如行情 tick、K 线更新、委托回报、成交回报等。文档里的描述很简单，但实际用它的时候有两个新手容易忽略的特点。

第一，如果没有事件发生，wait_update() 会一直等待，不返回。比如你订阅了一个成交不活跃的合约，或者市场休市，它可能好几分钟都没有新事件，你的线程就静悄悄地停在那里。第二，即使你设了 deadline 参数，也不能指望它像 time.sleep 那样精确到毫秒地返回，它更多是提供一个“最晚阻塞到某个时间点”的保障。因此，如果你的退出条件建立在“循环在某次 wait_update() 返回之后检查”，但没有给 wait_update() 设 deadline，那么退出条件可能一直没机会被检查到，程序就表现成卡死。这就好比你在电话客服等待队列里，系统说“请稍后”，但没告诉你要等多久，你只能一直举着电话。

正确做法是让每个 wait_update() 都有最长阻塞时间。给一个简单对比：

# 错误示范：被动等待事件，没有超时出口 while True: api.wait_update() # 正确示范：每 0.5 秒醒一次，检查退出条件 import time while not some_stop_condition: api.wait_update(deadline=time.time() + 0.5)

第二种写法里，就算一直没有任何行情事件，循环也会每隔 0.5 秒醒来一次，有机会检查停止标志。这是解决“卡在 wait_update 里出不来”的核心思路。

2.3 close() 到底做了什么

close() 是 TqApi 提供的资源清理方法。调用它会关闭与天勤服务端的网络连接，释放本地通信通道，停止内部的后台线程，并尝试终止相关子进程。简单讲，它是“正式退房”的动作，会通知所有后台资源：服务到此为止，可以歇了。

如果你不调用 close()，这些后台资源不会自动释放，只能等 Python 进程整个被强杀。问题是很多人用 Ctrl+C 中断后，主线程结束了，但子线程还在，进程没有被强杀，于是所有资源继续挂在那里。等你想再次创建 TqApi() 时，就撞上了残留资源的问题。所以可以把它当作一条铁律：你的代码里必须有一条路径能确保调用 close()，无论正常退出、异常退出、还是被信号打断退出。

3. 核心实操：几种场景下的正确关闭姿势

3.1 单线程策略按条件正常退出

这是最简单也最常见的场景。你有一个策略循环，希望运行到某个条件后自己退出。关键是退出之后立刻调用 close()，并且用 try/finally 兜底，避免策略中间抛异常时漏掉清理。

from tqsdk import TqApi, TqAuth import datetime api = TqApi(auth=TqAuth("your_account", "your_password")) # 计划运行 30 秒后自动退出 end_time = datetime.datetime.now() + datetime.timedelta(seconds=30) try: while datetime.datetime.now() < end_time: api.wait_update(deadline=end_time) # 在这里写下你的策略逻辑，比如读取行情、下单、风控 finally: api.close() print("api closed")

有几个细节值得说明。wait_update(deadline=end_time) 里的 deadline 参数，让每次等待最多阻塞到 end_time，如果行情事件来得早，它会提前返回处理事件；如果一直没事件，到 end_time 它也会返回，然后循环条件判断为 False，走出循环。这里的 try/finally 保证不管循环体里是正常结束还是抛出异常，close() 都会被调用。我见过很多人不写 finally，直接在循环结束后写 api.close()，这其实不够稳，因为如果循环体里有一个未捕获的异常，close 那行就不会执行到。养成 finally 的习惯，能省掉后面很多麻烦。

3.2 多线程策略中，用事件通知优雅关闭

多线程场景更考验退出设计。很多人的模式是：主线程负责整体调度，子线程负责行情更新或交易逻辑。子线程里如果写 while True: api.wait_update()，主线程想退出时，会发现子线程根本阻塞在 wait_update 内部，你设置任何标志位都没用，因为它要等下一次事件到达才能醒来检查。解决思路就是给 wait_update 加一个短暂的 deadline，再配合 threading.Event 作为停止信号。

import threading import time from tqsdk import TqApi, TqAuth stop_event = threading.Event() def worker(): api = TqApi(auth=TqAuth("your_account", "your_password")) try: while not stop_event.is_set(): api.wait_update(deadline=time.time() + 0.5) # 在这里做行情处理或交易逻辑 finally: api.close() print("worker closed") def main(): t = threading.Thread(target=worker, daemon=True) t.start() try: # 模拟策略运行 10 秒后准备退出 time.sleep(10) except KeyboardInterrupt: pass finally: stop_event.set() t.join(timeout=5) print("main exit") if __name__ == "__main__": main()

这个模式有三个关键点。第一，worker 线程里必须自己负责创建 api 和关闭 api，不要跨线程调用另一个线程的 api.close()，因为 tqsdk 中跨线程操作会有同步风险。第二，wait_update(deadline=time.time() + 0.5) 保证即使市场没有任何新数据，线程也会每 0.5 秒醒一次，及时感知 stop_event 被置位。第三，t.join(timeout=5) 给子线程一个合理的收尾时间，如果子线程内部清理慢，主线程也不会无限等下去。daemon=True 是兜底方案，就算主线程因为某种原因连 join 都没执行到，进程退出时也不会被子线程拖住。但我不建议只依赖 daemon=True，因为它不会给你执行 close() 的机会，后台资源可能还是残留的。

3.3 命令行脚本“跑完即走”的最省心写法

如果你只是写一个临时脚本，比如抓一下某个合约的快照，或者做一次简单的回测数据获取，跑完就退出，最省心的是用上下文管理器。TqApi 实现了 with 语法，退出代码块后会自动调用 close()，省去手动维护 try/finally 的麻烦。

from tqsdk import TqApi, TqAuth with TqApi(auth=TqAuth("your_account", "your_password")) as api: quote = api.get_quote("SHFE.cu2412") while True: api.wait_update() if quote.last_price: print(quote.last_price) break

when 代码块执行到 break 退出之后，会立即走出 with 块，close() 自动被调用。这种写法非常适合“一次性脚本”：代码简洁，不会忘记关闭，也没有线程残留。我在日常工作中写很多数据分析类的辅助脚本，基本都是这个模板。需要注意的是，如果策略逻辑是无限循环且永远不 break，with 块也永远出不去，但这属于策略设计问题，不是退出机制问题。

3.4 异常崩溃和信号中断也要善后

程序不一定总是按预期退出，比如用户按 Ctrl+C、系统关机、策略内部抛异常。要让 close() 在这些情况下也能执行，可以分几层来保护。第一层是 try/finally，前面已经说过。第二层是信号处理，专门应对 Ctrl+C。

import atexit import signal import sys from tqsdk import TqApi, TqAuth api = TqApi(auth=TqAuth("your_account", "your_password")) def cleanup(): print("cleanup...") api.close() atexit.register(cleanup) def on_sigint(signum, frame): print("SIGINT received") sys.exit(0) signal.signal(signal.SIGINT, on_sigint) # 业务逻辑，比如无限循环 while True: api.wait_update()

这里有个值得记住的细节：sys.exit(0) 会触发 Python 的退出清理流程，所以 atexit 注册的 cleanup 函数会被执行，close() 也会被调用。但如果你在某处用了 os._exit(0) 来“秒退”，它不会触发任何清理逻辑，会直接结束进程，等于把所有后台线程和连接都晾在那里。所以除非你特别确定不需要清理，否则别用 os._exit 来解决退出问题。

4. 排查实录：线程残留与卡死的定位方法

4.1 先确定卡在哪个线程哪一行

遇到退出异常，第一件事是定位阻塞位置。最简单有效的方法是日志法：在关键步骤前后打印日志，比如“开始 wait_update”“准备退出”“close 之前”“close 之后”，看最后一条日志落在哪里。如果最后一条日志是“开始 wait_update”，说明线程卡在等待事件上。

如果日志法看不出来，可以直接把 Python 的故障转储打开：

import faulthandler faulthandler.dump_traceback_later(10, repeat=False)

这段代码会让程序在运行 10 秒后自动打印所有线程当前卡住的调用栈，然后退出。打印出来的信息会直接显示每个线程执行到了哪一行，比如你会看到某个线程卡在 API 内部某处，某个线程卡在 socket 等待上。它不依赖调试器，线上临时排查也很管用。

另一个更强大的工具是 py-spy，它可以主动查看运行中进程的 Python 栈：

pip install py-spy py-spy dump --pid <你的进程PID>

这个命令不需要重启进程，也不会阻塞程序运行，就能把每个 Python 线程的调用栈打出来。我在排查“为什么退出慢”的问题时，用它看到过线程卡在 wait_update 的等待函数内部，一下子就定位了方向。

4.2 查看线程状态和进程残留

如果确认 Python 线程本身没问题，下一步看进程层面的情况。在 Linux 上可以这样看某个进程的所有线程：

ps -T -p PID top -H -p PID

在 Windows 上可以这样查线程数量：

wmic process where processid=PID get threadcount

如果你写的是一个负责的结果返回脚本，也可以在 Python 内部简单枚举一下当前还有哪些线程：

import threading for th in threading.enumerate(): print(th.name, th.daemon)

执行到程序最后、进程还没退出时，你可以在另一个终端用这个枚举来看还有哪些非 daemon 线程存活着，这能帮你确认是不是 tqsdk 内部线程在拖后腿。

4.3 查找并清理残留的后台副进程

如果确认 Python 主进程已经没了，但端口或连接被占用，那就是后台子进程残留了。可以在系统里搜一下带 tq 关键词的进程：

在 Linux 上：

ps aux | grep -i tq | grep -v grep

在 Windows 上：

tasklist | findstr /i tq

确认残留进程后直接结束它。也可以用 Python 脚本批量清理和自己相关但不属于自己的残留进程：

import psutil for proc in psutil.process_iter(["pid", "name", "cmdline"]): cmdline = " ".join(proc.info["cmdline"] or []) if "tq" in cmdline.lower() and proc.pid != psutil.Process().pid: print("杀掉残留进程", proc.pid, proc.info["name"]) proc.terminate()

这个办法我在自己电脑上试过，能精准把上一轮跑崩的后台服务清掉。不过要注意，不要乱杀别的 Python 进程，过滤条件最好精确一些。

4.4 常见问题速查表

5. 避坑清单与个人经验心得

5.1 把 close() 当作每次运行的必要收尾

如果说这篇文章只能让你记住一条，那就是 close() 必须执行。不管你的程序是正常结束、异常结束、还是被 Ctrl+C 打断，都要保证有一行代码能调用 close()。落实到代码习惯上，短脚本用 with TqApi(...) as api，长策略用 try/finally，信号中断场景用 atexit 或信号回调。三层防护不需要全上，但至少要有一层。我见过太多人写了很复杂的策略逻辑，最后却因为少了一个 close() 导致每次重启都要杀进程。

5.2 多线程中不要跨线程操作同一个 api 对象

TqApi 不是一个线程安全对象。如果你在一个线程里创建了 api，另一个线程也去调用它的 wait_update() 或者交易接口，轻则数据错乱，严重时会出现难以排查的卡死和退出失败。我的经验是，要么所有 api 相关操作都放在一个线程里，由该线程全权负责创建、循环和关闭；要么干脆每个线程各自创建独立的 TqApi 实例，互相不干扰。后者虽然会额外增加连接数，但在多策略并行时非常省心。

5.3 用 Event 和 deadline 组合，而不是 sleep 硬等

多线程退出时，有些人会习惯在主线程里 time.sleep(若干秒)，然后直接结束。这在 tqsdk 场景下不太管用，因为子线程可能还阻塞在 wait_update() 内部。正确的做法是先用 threading.Event 发出停止信号，再让子线程里的 wait_update() 带上 deadline，保证它能及时醒过来检查信号。这套组合基本能覆盖所有“多线程无法退出”的情况。

5.4 Jupyter 环境里尤其小心

如果你在 Jupyter 里跑 tqsdk 策略，要格外注意连接残留。每执行一次创建 TqApi()，如果没有 close，这个连接就会一直挂在后台。第二次执行新的创建时，就可能因为端口或通信通道被占而报错。我的建议是，在 Jupyter 里也尽量使用 with 写法，或者每个执行单元跑完后手动调用 api.close()。否则跑几次之后，唯一的解决方式就是重启内核，开发体验会很糟糕。

我现在的个人习惯是：所有涉及 tqsdk 的脚本，一律用 with TqApi() 作为入口；凡是写多线程，就提前定义好 stop_event，并让所有 wait_update() 都带上 deadline；再配合一个兜底的 daemon=True。这套组合打下来，基本再没遇到过“程序结束但进程不死”的怪病。如果你正被退出问题折腾，建议先从 close() 和 deadline 两个点入手，再结合日志和 py-spy 定位具体卡在哪个环节，通常很快就能找到出路。