libuv:一个跨平台的C++异步 I/O 库

haokan123456789

79人浏览 · 2026-03-17 22:04:03

haokan123456789 · 2026-03-17 22:04:03 发布

1.简介

2.安装与集成

2.1.包管理器安装（Linux/macOS，推荐）

2.2.源码编译安装（通用，适合所有系统）

2.3.Windows 源码编译（MSVC）

1.简介

libuv 是一个跨平台的异步 I/O 库，最初为 Node.js 开发（作为其底层事件循环和异步 I/O 核心），现在已成为独立的开源项目。它的核心设计是事件驱动、非阻塞 I/O，能让你在 Windows、Linux、macOS 等不同系统上，用统一的接口实现高效的异步操作，无需关心底层操作系统的 I/O 模型差异（比如 Linux 的 epoll、Windows 的 IOCP、macOS 的 kqueue）。

libuv 提供了丰富的异步能力，核心特性可通俗理解为：

事件循环（Event Loop）：libuv 的 “心脏”，会不断轮询各类事件（I/O 完成、定时器到期、信号触发等），并调用对应的回调函数处理，是所有异步操作的调度核心。
异步 I/O 支持：
- 网络 I/O：TCP/UDP 套接字的异步读写（网络服务端的核心能力）；
- 文件 I/O：文件读写、目录操作等（底层依赖线程池实现，因为文件 I/O 无法完全 “真正异步”）。
基础工具能力：定时器、信号处理（捕获 SIGINT 等系统信号）、线程池（默认 4 线程，可配置）、进程管理（创建子进程、进程通信）等。

下载地址：https://github.com/libuv/libuv.git

2.安装与集成

2.1.包管理器安装（Linux/macOS，推荐）

这种方式最快捷，无需手动编译，适合快速开发。

1.Ubuntu/Debian 系 Linux

# 安装 libuv 开发库（包含头文件+编译好的库文件）
sudo apt update && sudo apt install -y libuv1-dev

2.CentOS/RHEL 系 Linux

# 先安装 EPEL 源（CentOS 默认源没有 libuv）
sudo yum install -y epel-release
# 安装 libuv 开发库
sudo yum install -y libuv-devel

3.macOS（需先安装 Homebrew）

# 安装 Homebrew（若未安装）
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
# 安装 libuv
brew install libuv

2.2.源码编译安装（通用，适合所有系统）

若包管理器版本过旧，或需要自定义编译（如 Windows），推荐源码编译。

1.下载源码

# 克隆官方仓库（或直接下载 Release 包）
git clone https://github.com/libuv/libuv.git
cd libuv
# 切换到稳定版本（推荐，避免开发版bug）
git checkout v1.48.0  # 可替换为最新稳定版，如 v1.49.0

2.编译安装（Linux/macOS）

libuv 用 autotools 或 cmake 编译，这里用 cmake（跨平台更友好）：

# 创建编译目录（规范做法，避免污染源码）
mkdir build && cd build
# 配置编译（指定安装路径，默认 /usr/local）
cmake .. -DCMAKE_INSTALL_PREFIX=/usr/local
# 编译（-j 后接CPU核心数，加速编译）
make -j$(nproc)
# 安装（需 sudo，将头文件/库文件拷贝到系统目录）
sudo make install

2.3.Windows 源码编译（MSVC）

Windows 推荐用 vcpkg 或 Visual Studio 编译：

1.vcpkg 安装（推荐）

# 安装 vcpkg（若未安装）
git clone https://github.com/microsoft/vcpkg.git
cd vcpkg
.\bootstrap-vcpkg.bat
# 安装 libuv（x64 版本）
.\vcpkg install libuv:x64-windows

2.手动编译（Visual Studio）

# 进入 libuv 源码目录，创建 build 文件夹
mkdir build && cd build
# 用 cmake 生成 Visual Studio 工程文件
cmake .. -G "Visual Studio 17 2022" -A x64  # 适配自己的 VS 版本
# 打开生成的 uv.sln，选择 "Release" 模式，编译 INSTALL 项目
# 编译完成后，头文件和库文件会安装到 C:\Program Files\libuv

验证安装是否成功

# 检查头文件是否存在
ls /usr/local/include/uv.h  # Linux/macOS
# 检查库文件是否存在
ls /usr/local/lib/libuv.so  # Linux
ls /usr/local/lib/libuv.dylib  # macOS

3.使用示例

1.实现一个 2 秒定时器

下面用最基础的定时器示例，帮你理解 libuv 的核心使用方式（新手友好，代码可直接运行）。

#include <uv.h>
#include <stdio.h>

// 定时器回调函数：定时器到期时被事件循环调用
void on_timer_trigger(uv_timer_t* handle) {
    printf("定时器触发！\n");
    
    // 关闭定时器句柄，释放资源
    uv_timer_stop(handle);
    uv_close((uv_handle_t*)handle, NULL);
    
    // 停止事件循环（否则事件循环会一直运行）
    uv_stop(uv_default_loop());
}

int main() {
    // 1. 定义定时器句柄
    uv_timer_t timer;
    
    // 2. 初始化定时器（绑定到默认事件循环）
    int ret = uv_timer_init(uv_default_loop(), &timer);
    if (ret != 0) {
        fprintf(stderr, "定时器初始化失败：%s\n", uv_strerror(ret));
        return 1;
    }
    
    // 3. 启动定时器：延迟 2000ms（2 秒）触发，仅触发 1 次
    // 参数说明：句柄 → 回调函数 → 延迟时间(ms) → 重复间隔(ms，0=仅一次)
    uv_timer_start(&timer, on_timer_trigger, 2000, 0);
    
    printf("等待 2 秒...\n");
    
    // 4. 启动事件循环（阻塞调用，直到 uv_stop 被触发）
    uv_run(uv_default_loop(), UV_RUN_DEFAULT);
    
    // 5. 清理事件循环资源
    uv_loop_close(uv_default_loop());
    
    printf("事件循环退出\n");
    return 0;
}

2.CMake 集成（工程化项目，跨平台）

适合多文件、跨平台项目，CMake 能自动处理头文件和库的路径，更易维护。

示例项目结构

my_uv_project/
├── CMakeLists.txt  # CMake 配置文件
└── src/
    └── main.c      # 业务代码

编写 CMakeLists.txt

# 指定 CMake 最低版本
cmake_minimum_required(VERSION 3.10)

# 项目名称和语言
project(my_uv_app C)

# 设置 C 标准
set(CMAKE_C_STANDARD 99)

# 查找 libuv 库（CMake 会自动找头文件和库文件）
find_package(libuv REQUIRED)

# 添加可执行文件（指定源码文件）
add_executable(my_uv_app src/main.c)

# 链接 libuv 库到可执行文件
target_link_libraries(my_uv_app PRIVATE uv)

编译运行步骤

# 1. 创建编译目录
mkdir build && cd build

# 2. 生成编译文件（Linux/macOS）
cmake ..

# Windows（vcpkg 集成）
cmake .. -DCMAKE_TOOLCHAIN_FILE=C:\vcpkg\scripts\buildsystems\vcpkg.cmake

# 3. 编译项目
make -j$(nproc)  # Linux/macOS
# Windows（Visual Studio）：打开 build 里的 my_uv_app.sln 编译，或用：
cmake --build . --config Release

# 4. 运行程序
./my_uv_app  # Linux/macOS
Release\my_uv_app.exe  # Windows

4.使用场景

Node.js 底层：Node.js 的事件循环、异步 I/O 完全基于 libuv 实现，这是其最核心的应用；
高性能网络服务：用 C/C++ 开发跨平台的非阻塞 TCP/UDP 服务器（如 Web 服务器、游戏服务器）；
开源项目依赖：libcurl（异步 HTTP 请求）、MongoDB C 驱动、Rust tokio 库（部分参考）等都基于 libuv 实现跨平台异步。