写Python脚本，最大的欣慰就是程序能自己把身后事安排好。但现实往往是：一个脚本跑着跑着，数据库连接还挂着，临时文件写到一半，日志缓存没刷，这时候有人按下Ctrl+C，进程直接死了，留下一地烂摊子。这个问题我刚开始写爬虫和后台例行任务时真没当回事，直到有一次某个采集任务在收尾阶段被中断，几万条记录的状态全部错乱，才痛下决心把“Ctrl+C怎么优雅处理”这件事彻底搞清楚。这篇文章从信号产生的底层链路开始，一步步拆解Python3里捕获和优雅处理Ctrl+C的各种方案，包括try/except KeyboardInterrupt的边界、signal模块的注册机制、多线程与asyncio场景下的正确姿势，以及我实测下来最容易踩的坑。
1. 按下Ctrl+C时，进程到底经历了什么
1.1 终端按键到信号送达的完整链路
在Linux或macOS的终端里按下Ctrl+C，本质不是给程序塞了一个“^C”字符，而是终端驱动把组合键解释为中断指令，然后向当前终端的前台进程组发送一个SIGINT信号。内核收到这个信号后，会异步通知目标进程。所以哪怕你的程序正在读文件、正在sleep、正在等待网络数据，SIGINT也能随时到达。这一点非常关键，很多人以为Ctrl+C只是往标准输入里写东西，导致在程序阻塞读取stdin时处理错了方向。
Python程序被SIGINT打断后，事件并不会立刻在Python层面“显形”，而是由解释器内部的信号处理机制接收，再择机在字节码执行的间隙触发Python层回调。CPython的signal模块就是干这件事的：你用signal.signal注册一个函数，解释器就把这个SIGINT对应到你注册的回调上；你没注册，就套用默认行为。
1.2 Python默认处理：直接抛出KeyboardInterrupt
没有人为干预时，Python3对SIGINT的默认处理是把KeyboardInterrupt抛出来，通常是在主线程执行到某一条字节码之前或之后。如果程序里没有捕获这个异常，解释器会打印一段traceback，然后以码值130退出。130这个数字有点讲究，它是128加上信号编号2（因为SIGINT的信号编号正好是2），shell和父进程可以通过退出码判断这个进程是被Ctrl+C杀掉的。
所以即便你什么都不写，Python也不是“毫无反应就消失”，它至少会给你留下一段堆栈。但对一个跑在别人电脑上的工具来说，这段堆栈基本等于把内部实现细节直接糊到用户脸上。更重要的是，进程在退出前没有任何机会执行清理逻辑，数据库可能还锁着记录，文件可能只写了一截，这就不只是难看的问题了。
1.3 为什么默认行为在生产环境里不够用
我见过不少线上脚本出过这类问题：程序里维护了一批工作线程，主线程收到KeyboardInterrupt后直接打印异常退出，可那些工作线程还在跑，结果进程没有真正退出，卡在那里半死不活。还有更糟的，临时文件写到一半，突然中断，下次启动时程序不认得这个残缺文件，直接把整个目录清掉，数据丢得干干净净。
如果再加一道工序想“在except里补一点收尾”，又会发现收尾代码没跑完就又被打断，或者根本不知道从哪里开始收拾。这是因为默认处理的粒度是“当场中断”，而不是“给出善后时间”。要让程序在收到Ctrl+C之后还有机会把状态收好、线程停掉、文件关掉，就得主动接管SIGINT，这就涉及到Python的信号注册机制了。
2. 第一层防线：try/except KeyboardInterrupt 能兜住哪些场景
2.1 单线程轮询循环里的标准捕获写法
最简单、也最容易被忽略的方案，是用try/except把主循环包起来。对单线程的小脚本来说，这已经能解决一大半问题。
import time import json def fetch_next(): return {"timestamp": time.time(), "value": 1} def main(): output_file = open("output.jsonl", "a") try: while True: line = fetch_next() output_file.write(json.dumps(line) + "\n") output_file.flush() time.sleep(1) except KeyboardInterrupt: print("收到 Ctrl+C，开始收尾") finally: output_file.close() print("文件已关闭，程序退出") if __name__ == "__main__": main()这段代码好在哪？异常被捕获后，finally里的文件关闭一定会执行，数据缓冲区至少能先落盘。实际中很多人的错误是只在except里print一句，忘了把资源清理放进finally。要记住：KeyboardInterrupt随时可能在你处理业务逻辑的过程中冒出来，只有finally能保证清理动作无论如何都会走一遍。
2.2 它兜不住的两类情况
第一类是工作线程。KeyboardInterrupt只会在主线程抛出，工作线程里跑的循环完全感知不到。你要是开了十个线程各自下载文件，主线程一异常退出，Python会进入解释器关闭流程，那些非守护线程还会继续运行，但如果它们卡在某个网络请求上，整个进程就可能悬在退出状态，看着像退出了其实没退干净，或者反过来直接杀掉导致任务半途而废。
第二类是当你已经用signal模块注册了自定义SIGINT处理器之后，KeyboardInterrupt就不会再被抛出了。signal.signal一旦接管，默认行为就被替换掉。如果代码里既有signal.signal注册的处理器，又指望except KeyboardInterrupt能触发，等于白等。这两种写法不要混用，否则你会看到信号处理器执行了一段，然后主线程继续跑，怎么也等不到那个你预期的异常。
3. 用signal模块接管SIGINT：注册处理函数的原理与限制
3.1 注册一个符合规范的信号处理器
手动接管信号后，你可以决定收到SIGINT时程序具体做什么。最常见的写法是设置一个退出标志让主循环自己停下来。
import signal import time running = True def handle_sigint(signum, frame): global running print(f"收到信号 {signum}，准备优雅退出") running = False signal.signal(signal.SIGINT, handle_sigint) print("程序启动，按 Ctrl+C 试试看") while running: print("处理中...") time.sleep(0.5) print("主循环已退出，程序结束")handle_sigint接受两个参数：signum是接收到的信号编号，frame是当前执行栈帧。第二个参数大多数时候用不上，但函数签名必须保留。这段代码的关键是把“收到信号”和“真正退出”解耦：处理器只做标记，主循环检查标记后自然退出。这样清理逻辑还在正常流程里，不会在信号到达的瞬间被割裂。
3.2 Python信号处理器与C语言信号语义的差异
在C语言里写信号处理器要非常小心，因为处理器是在中断上下文中执行的，能调用的函数极其有限，printf都不一定安全。Python则完全不同，解释器会等当前字节码执行完毕后，在安全点才真正调用你的Python回调。这意味着你可以放心的用普通Python代码写处理器逻辑，不用担心大多数可重入问题。
但这不代表可以随便在处理器里干重活。Python处理器执行期间，主线程的其他Python代码完全暂停，所有信号处理都会排队。如果你在处理器里做耗时操作，比如写几十万行日志，程序会显得像卡死一样，用户再按一次Ctrl+C也无济于事。我的经验是：处理器里只做三件事——打印一句话、设置标志、最多往线程安全的数据结构里丢一个事件。其余动作交给正常的业务循环处理。
还有一个现代Python3的特性值得知道：从PEP 475开始，系统调用被信号打断后，Python会自动重试，而不是直接抛出一个神秘的EINTR错误。所以在time.sleep、socket接收、文件读写中收到SIGINT，大多数情况下程序都能在处理器跑完后顺利恢复。这也让“设置标志等主循环退出”这种模式变得更可靠。
3.3 只能注册在主线程：ValueError背后的机制
signal.signal有一个限制让不少人踩过：不能在子线程里调用，否则会抛ValueError，提示“signal only works in main thread”。原理其实不难理解：操作系统把SIGINT这种同步信号投递给进程时，最终是要在主线程上下文中处理的。CPython解释器内部会把收到的信号先记到一个待处理队列，然后在主线程执行字节码的间隙去调用Python层的处理器。如果你在子线程里注册了一个handler，主线程里没有对应的注册信息，这个handler就永远不会被正确触发。
所以如果你想多线程程序优雅退出，不要试图在子线程里注册信号处理器，而应该在主线程注册，然后把“退出”这个意图通过线程安全的事件对象广播出去。这个思路正好引出下一节的完整模式。
4. 优雅退出三段式：通知、停止、清理的完整实践
4.1 以threading.Event作为全局停止信号
线程之间传递“该停了”这个状态，最省心的载体是threading.Event。它本身线程安全，set之后所有等待或检查它的线程立刻能看到，不需要额外加锁。配合signal处理器，就能把一次按下Ctrl+C的事件变成全程序范围内的退出指令。
import signal import threading import time stop_event = threading.Event() def request_stop(signum, frame): print("收到退出信号，正在通知各工作线程停止...") stop_event.set() def register_signal_handlers(): signal.signal(signal.SIGINT, request_stop) def worker(name): while not stop_event.is_set(): print(f"线程 {name} 处理任务中") time.sleep(1) print(f"线程 {name} 已安全停止") def main(): register_signal_handlers() threads = [threading.Thread(target=worker, args=(i,)) for i in range(3)] for t in threads: t.start() for t in threads: t.join() print("所有线程已结束，程序正常退出") if __name__ == "__main__": main()这段代码的运行逻辑是：主线程注册处理器，启动三个工作线程，然后join等待。用户按下Ctrl+C，request_stop被调用，stop_event被置位，三个线程在各自的循环检查中看到标志，处理完当前一轮活后退出，主线程的join也就随之返回。整个过程不会出现线程被强杀的情况，数据一致性有保障。
4.2 资源清理顺序：先停新任务，再等存量，最后关连接
很多人有一个误区，觉得收到信号后第一件事应该是关数据库、关文件。实际上如果还有线程正在读写数据库，你先关连接只会让他们接着报错。我习惯用的顺序是：先停止接收新任务，再等存量任务跑完，最后关闭文件和连接。
def main(): register_signal_handlers() threads = [threading.Thread(target=worker, args=(i,)) for i in range(3)] for t in threads: t.start() # 等所有工作线程退出，给一个超时兜底，避免个别线程卡死导致整个进程挂住 for t in threads: t.join(timeout=10) if any(t.is_alive() for t in threads): print("有线程未能及时退出，请检查") else: print("所有线程已退出，开始关闭资源") # 到这里才安全地关闭数据库连接和临时文件 session.close() temp_file.cleanup()join带上超时是实战中很重要的习惯。因为线程里如果有阻塞操作，光靠Event不一定能让它马上苏醒。超时之后程序可以决定是继续等待、打印警告，还是给出更强烈的退出手段。我不会一上来就调用os._exit，那样又回到了“不给人善后机会”的老路。正确做法是先礼后兵。
4.3 连按两次Ctrl+C强制退出的设计
优雅退出最怕遇到一种情况：线程卡死在某个第三方库的调用里，Event也救不出来，用户等了几秒急了，又按一次Ctrl+C。如果第二次还是走同一个信号处理器，还是置位同一个Event，程序继续挂在那，体验非常差。所以很多常驻服务会做成“第一次优雅停，第二次强制停”。
import os import signal import threading import time stop_event = threading.Event() last_sigint_time = 0 FORCE_EXIT_INTERVAL = 2 def request_stop(signum, frame): global last_sigint_time now = time.time() if now - last_sigint_time < FORCE_EXIT_INTERVAL: print("收到第二次 Ctrl+C，强制执行退出") os._exit(1) last_sigint_time = now print("收到 Ctrl+C，正在优雅退出，再按一次将强制退出") stop_event.set()这里用两次信号的间隔时间作为判断依据。第一次按下后2秒内再按，就认定用户已经等不及了，os._exit会绕过一切Python层面的清理直接终止进程。之所以不在这里用sys.exit，是因为sys.exit会抛SystemExit异常，如果它恰好赶上某些try/finally的清理逻辑，可能反而触发一些依赖已经中断的资源清理代码，导致新的异常。os._exit是原子级别的立刻终止，语义上最干净。
5. asyncio场景的捕获方式：loop.add_signal_handler才是正解
5.1 asyncio程序里直接signal.signal会踩什么坑
写asyncio异步程序时，很多人顺手就用signal.signal注册一个处理器，然后在这个处理器里调用loop.stop()或者设置asyncio.Event。这种做法在简单Demo里能跑，一旦任务多起来就很容易出问题：asyncio的事件循环本身也是跑在主线程里的，signal.signal注册的Python处理器会在字节码间隙执行，这相当于在事件循环一个“任意时刻”插入了一段普通同步代码。你在这段代码里操作asyncio对象，比如set一个Event，虽然Event的set本身不是特别危险，但如果操作时机不当，可能打断事件循环正在进行的调度，导致某些任务状态不一致。
更麻烦的是，常见写法里如果处理器捕获信号后立刻调用某个正在await的协程方法，很可能遇到“Future attached to a different loop”或者任务取消时机错乱。这类问题排查起来非常头疼，因为它是偶发的、跟调度时序強相关的。既然asyncio提供了专门的信号注册接口，就没必要用signal.signal硬凑。
5.2 用add_signal_handler注册并优雅收尾
asyncio事件循环的add_signal_handler会把信号处理逻辑注册成事件循环内的回调，这样信号的到来相当于事件循环收到了一个普通任务，调度时机完全由事件循环掌控，就不会出现同步代码插队的问题。基本用法如下。
import asyncio import signal async def worker(stop_event): while not stop_event.is_set(): await asyncio.sleep(1) print("处理中...") async def main(): loop = asyncio.get_running_loop() stop_event = asyncio.Event() for sig in (signal.SIGINT, signal.SIGTERM): loop.add_signal_handler(sig, stop_event.set) task = asyncio.create_task(worker(stop_event)) await stop_event.wait() print("收到退出信号，正在取消后台任务") task.cancel() try: await task except asyncio.CancelledError: pass print("任务已收尾，退出") if __name__ == "__main__": asyncio.run(main())收到Ctrl+C后，stop_event被置位，main函数继续往下走，取消正在运行的任务，然后等任务真正结束。这里的await task会等待worker处理完当前那一次循环并响应取消，比直接调用os._exit优雅得多。要注意add_signal_handler在官方文档里标注为Unix环境可用，Windows上大多数信号并不支持，所以跨平台脚本还得保留一套基于signal.signal或try/except KeyboardInterrupt的兜底逻辑。
6. 容易翻车的几个现实问题：子进程、Windows与信号来源
6.1 终端发给整个进程组：子进程也会收到Ctrl+C
在一个交互式终端里运行程序时，Ctrl+C触发的SIGINT并不是只发给你的Python进程，而是发给整个前台进程组。如果你的Python脚本通过subprocess.Popen启动了子进程，子进程会同样收到SIGINT。这个行为在很多时候是好事，因为用户希望整个命令一起停；但它也会带来困惑，比如父进程已经写好了一套优雅退出逻辑，子进程却直接死了，最终状态还是乱。
我个人的做法是：如果子进程需要归父进程统一调度，就用start_new_session=True让它脱离当前进程组，这样终端的SIGINT只会打到父进程身上，父进程收到后再按需向子进程发送自己的退出指令。反过来，如果希望子进程和父进程一起被Ctrl+C终止，那就保持默认的进程组设置，不要额外处理信号，免得造成两套退出逻辑互相打架。
6.2 Windows平台的行为差异
Windows上Ctrl+C同样能触发SIGINT，但signal.signal支持的信号范围比Unix小很多，只覆盖SIGABRT、SIGFPE、SIGILL、SIGINT、SIGSEGV、SIGTERM、SIGBREAK这几个。而且Windows对信号的处理细节跟POSIX差别不小，比如SIGTERM的行为并不完全等同于Unix里杀进程的语义，asyncio的add_signal_handler在Windows上也不是全部信号都可用。
所以写跨平台脚本时，我会把主策略定成“try/except KeyboardInterrupt + signal.signal(SIGINT)”，这两者在Windows上基本一致。至于SIGTERM和第三方自定义信号，只作为Unix环境的增强功能，Windows分支直接跳过注册。这样既不会报NotImplementedError，也能让两种平台都有最基本的优雅退出能力。
6.3 不管来源是键盘还是kill：统一收口
最后提醒一个容易忽略的点：SIGINT不一定只来自键盘，执行kill -2 或者通过os.kill发送SIGINT，也会走同一个处理器。这意味着你写得好的信号处理逻辑，不只是服务了按Ctrl+C的用户，也服务了用kill命令关进程的管理员。我建议常驻脚本同时处理SIGINT和SIGTERM，因为运维人员通常习惯用默认的kill（发SIGTERM）来关服务，如果你的脚本只处理SIGINT，SIGTERM一到就直接默认退出了，根本没有善后机会。
def register_signal_handlers(): signal.signal(signal.SIGINT, request_stop) signal.signal(signal.SIGTERM, request_stop)测试的时候，别光靠手按键盘。你可以开两个终端，一个跑脚本，另一个用kill -INT 发信号，这样能验证handler是否正常触发，也方便机器化回归。我每次写完这类逻辑都会做一遍“信号触发、线程退出、资源释放、退出码正确”四步检查，路径一多就不容易漏了。
这几年攒下来的经验里，我最受用的是“信号处理器只做标记”这个铁律，以及“第一次优雅、第二次强制”的设计。现在我再写常驻型脚本，几乎都会把这套模式带进去，哪怕一开始觉得只有几行代码不需要，最后也都会庆幸当初写了——你永远不知道程序会在什么样的现场被人按下Ctrl+C。
