一句话定位libuv 是 Node.js 底层的跨平台异步 I/O 库用 C 实现「单线程事件循环 线程池」模型统一封装了网络、文件系统、定时器、信号、子进程等异步能力。1. 背景1.1 为什么需要 libuv2009 年 Ryan Dahl 开发 Node.js 时遇到的核心痛点不同操作系统对异步 I/O 的支持差异巨大。能力LinuxmacOS/BSDWindows高性能网络 I/OepollkqueueIOCP非阻塞文件 I/O原生支持原生支持内核不支持需线程池模拟异步 DNSgetaddrinfo_a不成熟无无文件系统事件inotifykqueueReadDirectoryChangesW如果为每个平台各写一套事件循环代码将无法维护。libuv 的答案是一套统一 API内部按平台分派到 epoll / kqueue / IOCP / 线程池。Node.js 全面转向 libuv 后它独立发展成通用 C 异步库被 Julia、Luvit、pyuv 等众多项目采用。1.2 设计哲学句柄Handle 请求Request双对象模型句柄长期存在的资源定时器、TCP 连接、信号监听、文件监视器结构体以 uv_xxx_t 命名首字段必然是 uv_handle_t实现 OOP 式继承。请求一次性的异步操作一次写、一次读、一次文件打开结构体以 uv_xxx_t 命名但首字段是 uv_req_t回调完成后通常需要手动释放或复用。单线程事件循环 线程池网络 I/O、定时器、信号等在主线程事件循环中由内核事件驱动文件系统、DNS、用户 CPU 密集型任务uv_queue_work被丢进固定大小线程池默认 4 个线程可用 UV_THREADPOOL_SIZE 调整。回调驱动、绝不阻塞所有耗时操作都返回错误码并安排回调事件循环空闲时自动退出。1.3 事件循环的五个阶段uv_run() 每次迭代按固定顺序处理┌─────────────┐ │ timers │ 到期定时器回调uv_timer_t / 超时处理 ├─────────────┤ │ pending │ 上一轮未完成的 I/O 回调 ├─────────────┤ │ idle │ uv_idle_t 回调每轮都跑 ├─────────────┤ │ prepare │ 轮询前的准备钩子uv_prepare_t ├─────────────┤ │ poll │ 真正阻塞在 epoll/kqueue/IOCP 等内核事件上无句柄时直接跳过 ├─────────────┤ │ check │ 轮询后的收尾钩子uv_check_t ├─────────────┤ │ close │ 关闭回调uv_close 触发的 close_cb └─────────────┘理解这个顺序对排查「回调执行时机」类问题至关重要。2. 核心 API 说明2.1 事件循环API说明uv_default_loop()获取进程默认事件循环懒创建全局唯一uv_loop_new() / uv_loop_init()创建独立事件循环多实例场景uv_run(loop, mode)运行事件循环mode 见下表uv_stop(loop)让 uv_run 在下一次迭代开始前返回uv_loop_close(loop)关闭循环所有句柄必须已 close否则返回 UV_EBUSYuv_walk(loop, cb, arg)遍历循环上所有存活句柄常用于统一关闭uv_loop_alive(loop)判断循环是否还有存活句柄或活动请求uv_run 三种模式模式行为UV_RUN_DEFAULT一直运行直到没有存活句柄/请求服务端主循环UV_RUN_ONCE至少处理一个事件后返回若无 pending 事件则阻塞等待一个可当「步进」用UV_RUN_NOWAIT处理当前立即可处理的事件后立即返回不阻塞2.2 定时器uv_timer_t timer; uv_timer_init(loop, timer); // 回调、首次延迟(ms)、重复间隔(ms)repeat0 表示只触发一次 uv_timer_start(timer, on_timer, 1000, 500); uv_timer_stop(timer); // 停止 uv_timer_again(timer); // 用当前 repeat 重新启动需先设置 repeat uv_timer_set_repeat(timer, 2000); // 修改 repeat2.3 网络TCP / UDPTCP 服务端核心调用链uv_tcp_init(loop, server); uv_tcp_bind(server, (const struct sockaddr*)addr, 0); // 第二参数 flags 常用 0 uv_listen(server, 128, on_connection); // backlog128 // on_connection 中 uv_tcp_t* client malloc(sizeof(uv_tcp_t)); uv_tcp_init(loop, client); uv_accept(server, client); // 接受连接必须在回调内调用 uv_read_start(client, alloc_cb, on_read); // 开始读alloc_cb 负责给缓冲区TCP 客户端uv_tcp_connect(connect_req, client, (const struct sockaddr*)addr, on_connect); // on_connect 里检查 connect_req-status 是否 0UDPuv_udp_init(loop, socket); uv_udp_bind(socket, (const struct sockaddr*)addr, UV_UDP_REUSEADDR); uv_udp_recv_start(socket, alloc_cb, on_recv); // 收 uv_udp_send(send_req, socket, bufs, 1, (const struct sockaddr*)dest, on_send); // 发写数据统一走 uv_write(req, handle, bufs, nbufs, cb)uv_buf_t 结构为 { char* base; size_t len; }。2.4 异步通知 uv_async_t线程安全的跨线程唤醒uv_async_init(loop, async, on_async); // on_async 在主线程事件循环中执行 // 任意线程包括线程池 worker中调用 uv_async_send(async); // 线程安全、非阻塞、可合并多次 send 可能只触发一次回调这是把数据从工作线程安全送回事件循环的官方通道配合互斥锁保护共享数据。2.5 文件系统全部为异步版本请求对象需 uv_fs_tuv_fs_t req; uv_fs_open(loop, req, data.bin, O_RDONLY, 0, on_open); // 回调里 req-result 是 fd uv_fs_read(loop, req, fd, bufs, nbufs, offset, on_read); // offset-1 表示当前位置 uv_fs_write(loop, req, fd, bufs, nbufs, offset, on_write); uv_fs_close(loop, req, fd, on_close); uv_fs_unlink(loop, req, tmp.txt, on_unlink); uv_fs_scandir(loop, req, dir, 0, on_scandir); // 读目录回调里用 uv_fs_scandir_next 遍历每个 fs 请求使用完毕后必须调用 uv_fs_req_cleanup(req) 释放内部内存这是 libuv 里最容易漏的一步。同步变体在函数名后加 _syncuv_fs_open_sync(...) 直接返回 fd。2.6 线程池任务uv_work_t req; uv_queue_work(loop, req, work_cb, after_work_cb); // work_cb 在线程池 worker 线程执行after_work_cb 回到主线程事件循环 // 可通过 req.data 传递上下文工作完成后检查 req.result2.7 信号 / 子进程 / 文件监视uv_signal_t sig; uv_signal_init(loop, sig); uv_signal_start(sig, on_sigint, SIGINT); // 注意信号回调不是异步信号安全避免做重活 uv_process_t child; uv_process_options_t opts {0}; opts.file /bin/ls; opts.args (char*[]){ls, -l, NULL}; opts.exit_cb on_exit; // 子进程退出回调 uv_spawn(loop, child, opts); uv_fs_event_t fse; uv_fs_event_init(loop, fse); uv_fs_event_start(fse, on_fs_event, /path/to/watch, UV_FS_EVENT_RECURSIVE);2.8 线程与同步原语libuv 自带的跨平台封装uv_thread_create / uv_thread_join / uv_mutex_init / uv_mutex_lock / uv_mutex_unlock / uv_cond_init / uv_cond_wait / uv_cond_signal / uv_once / uv_sem_init / uv_barrier_init签名与 pthread 高度相似用于在需要时自建线程。2.9 工具与错误处理const char* uv_strerror(int err); // unknown error 风格描述 const char* uv_err_name(int err); // UV_EADDRINUSE 风格名称 uv_ip4_addr(127.0.0.1, 8080, addr); // 地址解析同步 uv_ip6_addr(...) / uv_ip4_name(addr, buf, len) / uv_ip6_name(...) uv_uptime(sec) / uv_getrusage(usage) / uv_os_getpid()2.10 编译集成find_package(libuv REQUIRED) target_link_libraries(app PRIVATE uv)或手动编译# Linux 动态链接 gcc main.c -luv -lpthread -ldl -lrt -o app # Windows (MinGW) 需附加 ws2_32 iphlpapi userenv psapi3. 详细使用说明可编译示例3.1 最小事件循环定时器#include stdio.h #include uv.h static void on_timer(uv_timer_t* handle) { static int count 0; printf(tick %d\n, count); if (count 3) { uv_timer_stop(handle); // 停止后事件循环无存活句柄uv_run 返回 } } int main(void) { uv_loop_t* loop uv_default_loop(); uv_timer_t timer; uv_timer_init(loop, timer); uv_timer_start(timer, on_timer, 1000, 1000); // 1s 后开始每秒一次 uv_run(loop, UV_RUN_DEFAULT); uv_loop_close(loop); printf(loop exited\n); return 0; }编译运行gcc timer.c -luv ./a.out预期每行间隔 1s 输出 3 个 tick。3.2 TCP Echo 服务器#include stdio.h #include stdlib.h #include string.h #include uv.h static void on_close(uv_handle_t* handle) { free(handle); // 客户端是 malloc 出来的close 回调里释放 } static void on_write(uv_write_t* req, int status) { if (status 0) fprintf(stderr, write error: %s\n, uv_strerror(status)); free(req); } static void alloc_cb(uv_handle_t* handle, size_t suggested_size, uv_buf_t* buf) { buf-base malloc(suggested_size); buf-len suggested_size; } static void on_read(uv_stream_t* client, ssize_t nread, const uv_buf_t* buf) { if (nread 0) { // 0 或负值EOF 或错误 if (nread ! UV_EOF) fprintf(stderr, read error: %s\n, uv_strerror(nread)); free(buf-base); uv_close((uv_handle_t*)client, on_close); return; } uv_write_t* wreq malloc(sizeof(uv_write_t)); uv_buf_t wbuf { buf-base, (size_t)nread }; uv_write(wreq, client, wbuf, 1, on_write); // 原样回写 free(buf-base); // uv_write 是异步的这里 free 安全吗 // 注意上面的 free 放在此处是安全的因为 wbuf.base 已被 uv_write 拷贝引用 // 真相libuv 不会拷贝数据回调触发前 base 必须有效。 // 因此正确做法把 buf-base 的所有权转移给写请求在 on_write 里统一 free。 } static void on_connection(uv_stream_t* server, int status) { if (status 0) { fprintf(stderr, accept error: %s\n, uv_strerror(status)); return; } uv_tcp_t* client malloc(sizeof(uv_tcp_t)); uv_tcp_init(server-loop, client); if (uv_accept(server, (uv_stream_t*)client) 0) { uv_read_start((uv_stream_t*)client, alloc_cb, on_read); } else { uv_close((uv_handle_t*)client, on_close); } } int main(void) { uv_loop_t* loop uv_default_loop(); uv_tcp_t server; uv_tcp_init(loop, server); struct sockaddr_in addr; uv_ip4_addr(127.0.0.1, 7000, addr); uv_tcp_bind(server, (const struct sockaddr*)addr, 0); uv_listen((uv_stream_t*)server, 128, on_connection); printf(echo server on 127.0.0.1:7000\n); uv_run(loop, UV_RUN_DEFAULT); return 0; }上例 on_read 中「先 free(buf-base) 再异步回写」是一个典型的待修正反例请参考第 4 章「坑 5」改为所有权转移模式后再运行。3.3 异步文件读取 线程池#include stdio.h #include stdlib.h #include string.h #include uv.h static uv_fs_t open_req, read_req, close_req; static char* content NULL; static size_t content_len 0; static void on_close(uv_fs_t* req) { uv_fs_req_cleanup(req); printf(file closed\n); uv_stop(req-loop); } static void on_read(uv_fs_t* req) { ssize_t nread req-result; uv_fs_req_cleanup(req); if (nread 0) { fprintf(stderr, read error: %s\n, uv_strerror(nread)); return; } if (nread 0) { content_len (size_t)nread; content realloc(content, content_len 1); content[content_len] \0; // 此处简化把本次读到的数据追加到 content真实场景要小心 offset 管理 } uv_fs_close(req-loop, close_req, open_req.result, on_close); } static void on_open(uv_fs_t* req) { int fd req-result; uv_fs_req_cleanup(req); if (fd 0) { fprintf(stderr, open error: %s\n, uv_strerror(fd)); return; } uv_buf_t buf { malloc(4096), 4096 }; uv_fs_read(req-loop, read_req, fd, buf, 1, 0, on_read); } int main(void) { uv_loop_t* loop uv_default_loop(); uv_fs_open(loop, open_req, data.txt, O_RDONLY, 0, on_open); uv_run(loop, UV_RUN_DEFAULT); if (content) { printf(content: %s\n, content); free(content); } return 0; }3.4 用 uv_queue_work 把阻塞任务丢进线程池#include stdio.h #include stdlib.h #include unistd.h // sleep仅示例 #include uv.h typedef struct { int input; long result; } job_t; static void work_cb(uv_work_t* req) { // worker 线程执行 job_t* job (job_t*)req-data; sleep(2); // 模拟耗时阻塞任务 job-result (long)job-input * job-input; } static void after_work_cb(uv_work_t* req, int status) { // 回到主线程 job_t* job (job_t*)req-data; printf(result %ld (status%d)\n, job-result, status); free(job); free(req); } int main(void) { uv_loop_t* loop uv_default_loop(); uv_work_t* req malloc(sizeof(uv_work_t)); job_t* job malloc(sizeof(job_t)); job-input 21; req-data job; uv_queue_work(loop, req, work_cb, after_work_cb); uv_run(loop, UV_RUN_DEFAULT); return 0; }3.5 信号 优雅退出#include stdio.h #include uv.h static uv_loop_t* g_loop; static void on_sigint(uv_signal_t* handle, int signum) { printf(Caught SIGINT, shutting down...\n); uv_signal_stop(handle); // 停止信号监听 uv_close((uv_handle_t*)handle, NULL); uv_stop(g_loop); // 通知循环退出 } int main(void) { g_loop uv_default_loop(); uv_signal_t sig; uv_signal_init(g_loop, sig); uv_signal_start(sig, on_sigint, SIGINT); printf(press CtrlC to quit\n); uv_run(g_loop, UV_RUN_DEFAULT); printf(bye\n); return 0; }4. 常错点 / 坑15 条实战踩坑清单坑后果正确姿势1回调里直接 free(handle)use-after-freelibuv 内部还在引用句柄必须 uv_close(handle, close_cb)在 close_cb 中释放2只 uv_timer_stop/uv_signal_stop 却不 uv_closeuv_loop_close 返回 UV_EBUSY事件循环不退出句柄泄漏所有句柄最终都要 uv_close3忘记 uv_fs_req_cleanup(req)每次 fs 操作泄漏内部结构体内存异步与 _sync 变体都要在结束后 cleanup4在回调里直接释放 uv_buf_t.base 后异步写写回调触发时数据已被释放 → 未定义行为/崩溃把 base 所有权转移给写请求在 write_cb 里统一 free5每次 read 回调都 malloc 新缓冲从不 free内存无限增长明确「谁分配谁释放」alloc_cb 分配、read_cb 里根据路径决定释放或转移6在非主线程直接操作 handle如 uv_tcp_write数据竞争/崩溃事件循环不是线程安全的跨线程一律通过 uv_async_send 互斥锁传递数据7一个 uv_async_t 多次 send 期待多次回调回调可能被合并为一次libuv 语义保证至少一次不要把业务逻辑建立在「每次 send 必回调一次」上8复用 uv_work_t 请求对象发起新任务而未等上次完成覆盖正在使用的请求 → 未定义行为每任务一个 req或用队列管理生命周期9信号回调里做重活如 malloc、printf 大量输出信号处理限制回调运行在中断上下文回调内只置标志/发送 async主流程处理10uv_read_start 后未处理 nread UV_EOF 分支反复触发 EOF 回调、资源不释放nread 0 时先 read_stop 再 closeclose 会隐式 stop11在 UV_RUN_ONCE / UV_RUN_NOWAIT 语义上理解错误循环提前返回或意外阻塞服务端用 UV_RUN_DEFAULT嵌入式/测试用 ONCE/NOWAIT 步进12多线程同时调用 uv_queue_work 的 after_cb 里直接操作非线程安全资源after_cb 虽在主线程但 work_cb 在 worker 线程work_cb 与 after_cb 之间共享数据要加锁或仅通过 req 传递13忘记设置 uv_timer_set_repeat 就调用 uv_timer_again定时器行为不符合预期repeat 为 0先设 repeat 再 again14静态链接顺序错误链接期大量未定义符号-luv 后追加 -lpthread -ldl -lrtLinuxWindows 加 -lws2_32 -liphlpapi -luserenv -lpsapi15默认线程池只有 4 个线程却排大量阻塞任务任务排队、I/O 被拖慢fs 也走线程池启动前设置环境变量 UV_THREADPOOL_SIZE8或避免用线程池跑长任务5. 总结5.1 适用场景场景推荐度说明高性能网络服务器TCP/UDP★★★★★成熟的 handle/request 模型跨 Linux/macOS/Windows 行为一致在 C 程序中嵌入事件循环★★★★★纯 C、无模板、上手快Node.js 同款给其他语言做运行时底层★★★★★Julia/Lua/Luvit 等已验证C 大型异步框架★★★☆☆需要 RAII 封装否则手动管理生命周期容易出错对类型安全/泛型要求高的 C 项目★★☆☆☆优先考虑 Asio / Boost.Asio 模板体系5.2 FAQ 速查Qlibuv 的回调一定在主线程执行吗除 work_cbworker 线程外绝大多数回调网络、定时器、fs 完成、after_work_cb、async都在运行 uv_run 的线程执行。Q如何优雅关闭服务停止监听 → 遍历 uv_walk 统一 uv_close → uv_run 自动退出 → uv_loop_close。Quv_async_send 会丢事件吗不会丢但可能合并它只保证「唤醒 至少回调一次」不保证每次 send 都回调。Q文件系统操作会阻塞事件循环吗不会fs 默认走线程池UV_THREADPOOL_SIZE 默认 4。Qlibuv 支持协程/异步/await 吗不直接支持但可配合 C 协程或第三方如 uvw、libuv 协程封装使用。QWindows 上文件系统事件inotify 不存在可靠吗支持 ReadDirectoryChangesW但目录内大文件移动等场景有已知边界生产需加轮询兜底。