简介libcurl 是成熟的跨平台网络传输库支持 HTTP、FTP、SMTP 等常见协议广泛用于桌面、服务端与移动端应用。这份 zip 压缩包面向需要在 Linux、macOS、iOS、Android、Windows 等平台编译并集成 libcurl 的开发者共 3 个文件包含 md 格式的编译说明、gz 格式的源码包和 sh 格式的构建脚本整体仅 3.82MB。已有 409 人学习下载。说明文档梳理了 configure、Makefile 与交叉编译等关键环节构建脚本针对 iOS 环境可简化多架构编译配合源码包开发者能快速复现从源码生成 libcurl 库的过程。适合有一定编译基础、希望节省环境配置时间的网络客户端开发者既有助于理解 libcurl 结构与编译参数也能借助脚本提升构建效率。1. libcurl跨平台编译为什么一个网络库要折腾出zip包当你的产品需要在 Windows、Linux、macOS 三端同时发布 SDK 或工具链时最让人头疼的不一定是业务代码而是像 libcurl 这种基础库怎么在三个平台产出完全一致的二进制。libcurl 是当前几乎所有语言和框架都在用的网络传输底层它的源码用 autotools 和 CMake 两套构建体系管理不同平台的依赖、链接方式、运行库又各不相同——直接./configure make出来的产物拿到另一台机器上经常跑不起来。这个标题背后的真实需求是把 curl 源码含 libcurl 库和 curl 可执行文件在三个平台上分别编译、验证、整理最终打成一个规范的 zip 包让其他人拿到手就能用不用自己也装一套编译环境。这篇文章会把从源码到 zip 包的完整路径、每个平台的参数选择和所有我能想到的坑都讲清楚。2. 先搞清楚 libcurl 的构建体系autotools、CMake 与依赖关系2.1 libcurl 源码里到底有哪些东西可执行文件、库与头文件的关系libcurl 的源码包解压后真正需要关注的是三个部分lib/目录编译出 libcurl 本体静态库或动态库src/目录编译出 curl 命令行工具它依赖 libcurlinclude/目录提供curl/curl.h头文件。源码包里还有docs/、tests/、scripts/等辅助目录做发布时不需要也不该塞进最终产物。值得强调的是curl 命令行工具src/curl并不是发布 libcurl 库的必要内容——很多嵌入式或 SDK 场景只需要库和头文件但既然标题写的是编译 curl.zip我倾向于把命令行工具一并编出来因为它本身就是 libcurl 最直接的验证工具。依赖关系上libcurl 默认会尝试启用尽可能多的协议和特性这意味着它在编译时会去探测系统里有没有 zlib、OpenSSL、libssh2、nghttp2 等库。这些探测逻辑在 configure 脚本里非常活跃产物包里一旦引用了系统里的共享库又没有把对应的 .so/.dll/.dylib 一起发布用户机器就会在运行时直接报找不到共享库错误。所以跨平台编译的第一个思维转变是不要只盯 curl 自身的编译要盯住它的依赖闭包。2.2 为什么我建议用 CMake 而不是 autotools 做三端统一autotools./configuremake是 Linux 上最经典的构建方式在 macOS 上也能用到了 Windows 上就非常尴尬——需要额外安装 MSYS2 或 Cygwin 模拟环境。而 CMake 在三个平台都是原生的Windows 下可以直接生成 Visual Studio 工程Linux/macOS 下生成 Makefile 或 Ninja 工程还天然支持交叉编译。libcurl 官方从 7.44 版本左右开始把 CMake 作为一等公民支持当前主流版本用 CMake 构建已经非常成熟。用 CMake 统一还有一个更实际的好处参数体系是一致的。不管在哪个平台控制静态/动态库的开关都是BUILD_SHARED_LIBS控制 SSL 后端的开关都是CURL_USE_OPENSSL。如果每个平台各写一套 autotools 参数维护成本和出错概率都会明显上升。下面是我习惯的三端统一配置基准配置项LinuxWindowsmacOS构建系统生成器Unix MakefilesVisual Studio 17 2022Unix Makefiles架构指定方式默认或 -m64-A x64CMAKE_OSX_ARCHITECTURESSSL 后端OpenSSLOpenSSL静态Secure Transport 或 OpenSSL关键开关CURL_USE_OPENSSLONCURL_USE_OPENSSLONCURL_USE_SECTRANSPONCMake 构建的核心是CMakeLists.txt顶层文件里对BUILD_SHARED_LIBS、CMAKE_INSTALL_PREFIX等全局变量的处理逻辑理解它就能解释为什么某些命令行参数在 libcurl 里会生效、某些会被忽略。配置阶段做成什么样直接决定后面每个平台能不能顺利进入编译阶段。3. 三个平台编译实操从源码到可发布的二进制3.1 Linux 下用 CMake 编出 libcurl.so 与 curl 命令Linux 的编译环境最干净依赖也最容易通过包管理器补齐。常见做法是先安装开发包再走 CMake 流程。这里我以 OpenSSL 为 SSL 后端为例先说明前置依赖# Ubuntu/Debian 系 sudo apt-get install build-essential cmake libssl-dev zlib1g-dev平台工具就绪后进入 curl 源码根目录配置并编译cmake -B build-linux \ -DCMAKE_BUILD_TYPERelease \ -DCMAKE_INSTALL_PREFIX/usr/local/curl-linux \ -DBUILD_SHARED_LIBSON \ -DCURL_USE_OPENSSLON \ -DCURL_ZLIBON \ -DCURL_DISABLE_LDAPON \ -DCURL_DISABLE_LDAPSON cmake --build build-linux -j$(nproc) cmake --install build-linux这段命令的核心逻辑是-B build-linux指定构建目录让源码目录保持干净BUILD_SHARED_LIBSON产出动态库libcurl.soCURL_USE_OPENSSLON启用 OpenSSL 后端使 HTTPS 等加密协议可用。CURL_DISABLE_LDAP和CURL_DISABLE_LDAPS属于裁剪项如果产品不需要企业内网常见的 LDAP 目录服务建议关掉能少两个依赖。CMAKE_INSTALL_PREFIX决定make install的落盘位置。编译完成后/usr/local/curl-linux下会有bin/curl、lib/libcurl.so、include/curl/curl.h三个核心产物。此时用ldd /usr/local/curl-linux/bin/curl检查依赖你会看到它链接了libssl.so、libcrypto.so、libz.so等系统库——这些库在目标用户的机器上未必存在后面第 5 章专门处理。3.2 Windows 上用 CMake Visual Studio 编出 curl.exe 与 libcurl.dllWindows 的编译有两个常见路线一是直接用 Visual Studio 打开 CMake 工程界面化操作二是在开发者命令行里用cmake -G指定生成器走命令行自动化。后者更适合做成脚本进入发布流程我以它为例。首先需要安装 Visual Studio含 C 桌面开发组件和 CMake然后在开始菜单 → Visual Studio Installer → 修改里确认安装了 Windows SDK。cmake -B build-win -G Visual Studio 17 2022 -A x64 ^ -DCMAKE_BUILD_TYPERelease ^ -DCMAKE_INSTALL_PREFIXC:\curl-win ^ -DBUILD_SHARED_LIBSON ^ -DCURL_USE_OPENSSLON ^ -DUSE_OPENSSLON cmake --build build-win --config Release cmake --install build-win --config Release这里的-G Visual Studio 17 2022指定生成 Visual Studio 2022 工程-A x64指定 64 位架构。如果本机是 VS2019把生成器名改成Visual Studio 16 2019。Windows 下CMAKE_BUILD_TYPE在 VS 多配置生成器下不直接生效所以--build和--install阶段都要追加--config Release指定具体配置。编译产物在build-win/src/Release/curl.exe和build-win/lib/Release/libcurl.dll等位置。cmake --install会把它们收集到C:\curl-win下。Windows 上最容易翻车的点有两个一是 OpenSSL 的 DLL 不会自动被复制到安装目录需要手动从 OpenSSL 安装目录拷贝libssl-3-x64.dll和libcrypto-3-x64.dll二是如果本机没装 OpenSSL 开发库CMake 探测不到会静默退回非 SSL 版本——编译能过但curl.exe不支持 HTTPS。3.3 macOS 上编译Universal Binary 与 Secure Transport 的取舍macOS 的编译流程和 Linux 相似但它有两个额外维度架构和 SSL 后端。架构方面Apple Siliconarm64和 Intelx86_64共存的现状迫使发布者考虑是否做 Universal BinarySSL 后端方面macOS 自带 Secure Transport也可以选择自带 OpenSSL。前者编译参数最省事cmake -B build-mac \ -DCMAKE_BUILD_TYPERelease \ -DCMAKE_INSTALL_PREFIX/opt/curl-mac \ -DBUILD_SHARED_LIBSON \ -DCURL_USE_SECTRANSPON \ -DCMAKE_OSX_ARCHITECTURESarm64;x86_64 cmake --build build-mac -j$(sysctl -n hw.ncpu) cmake --install build-macCMAKE_OSX_ARCHITECTURES同时传入 arm64 和 x86_64CMake 会用lipo工具把两个架构的产物合并成一个 fat 二进制在两种 Mac 上都能运行。CURL_USE_SECTRANSPON让 libcurl 使用系统自带的 TLS 实现好处是不用额外发布 OpenSSL 的 dylib坏处是如果产品里其他地方用了 OpenSSL会同时存在两套 TLS 库。如果选择CURL_USE_OPENSSLON需要先用 Homebrew 安装 OpenSSL 并指定-DOPENSSL_ROOT_DIR/opt/homebrew/opt/opensslApple Silicon 的 Homebrew 路径。macOS 的坑集中在签名和权限上本地编译出来的 curl 没有签名在别的 Mac 上运行时 Gatekeeper 可能会拦截如果目标是做工具链而非商店应用常见做法是xattr -dr com.apple.quarantine curl-mac去掉隔离属性或者在 CI 里做 ad-hoc 签名。4. 三端编译必踩的坑现象、原因与解决4.1 Windows 上编出的 libcurl.dll 加载即崩溃或模块找不到现象把编译好的 zip 包拷到一台干净的 Windows 测试机运行 curl.exe 直接提示找不到 libssl-3-x64.dll或代码 0xc000007b。原因有两层一是 OpenSSL 的 DLL 没有随包发布二是架构不匹配——把 64 位版本放到了 32 位系统上或者反之。解决发布前在开发机上用dumpbin /dependents curl.exe查看它的导入表把所有依赖 DLL 一并收集进 zip 的同一目录或bin目录架构问题则要回到构建命令确认-A x64与目标机器的位数一致。4.2 编出来的 curl 不支持 HTTPS访问 https:// 报错现象Linux 上用 CMake 编译的 curl 执行curl -I https://example.com直接报SSL certificate problem或Protocol https not supported。前者是证书链问题后者是压根没编进 SSL 后端。原因CMake 探测 OpenSSL 时系统没有安装libssl-dev于是静默地以不带 SSL 的方式完成了配置。解决编译前先确认 CMake 输出里SSL support: enabled (OpenSSL)的字样用curl -V查看Features一栏是否含SSL和HTTPS。如果libssl-dev装了但 CMake 还是没探测到用-DOPENSSL_ROOT_DIR/usr/lib/ssl手动指定路径。4.3 Linux 下编译时引用了高版本 GLIBC换台机器就崩现象在一台 Ubuntu 24.04 上编译的 curl.zip 放到 CentOS 7 上运行报version GLIBC_2.34 not found。原因动态链接的glibc是向下兼容的编译机上版本太新产物的符号版本旧系统里没有。这是 Linux 发布二进制最经典的坑。解决办法有两条路一是降低编译机系统版本在 CentOS 7 或 Ubuntu 18.04 上编译让符号版本足够老二是尽可能把依赖库OpenSSL、zlib一起静态编进 libcurl减少对系统库的引用但 glibc 本身无法静态化。如果只是发布给内网机器记录最低系统版本并在发布说明里标注更实际。4.4 静态库与动态库混用导致链接期符号冲突现象Windows 下集成方把libcurl.lib静态库编进自己的 DLL运行时发现自己的curl_easy_init调用走到了另一个模块的旧版 libcurl行为不可控。原因libcurl 提供了大量全局符号静态库被多个模块引用时符号表就会互相抢占。解决发布阶段只提供动态库版本或者明确告知集成方 libcurl 只能被一个模块加载。另外一个常见操作是把静态库的导出符号加上前缀或用libcurl.dll.a这类导入库做隔离但工程上最省心的还是统一采用动态库。4.5 依赖路径写死换一台机器构建就失败现象用 Homebrew 的 OpenSSL 在 macOS 上编译通过后构建产物只能在本机运行拷给别人后otool -L显示的 dylib 路径还是/opt/homebrew/opt/openssl/lib/libssl.dylib目标机器上不存在。原因CMake 的find_package找到动态库后直接把绝对路径写进了产物。解决发布时用install_name_tool -change把 dylib 路径改成相对路径loader_path/libssl.dylib并把对应的 dylib 一起打进包或者直接改用CURL_USE_SECTRANSP避开第三方 dylib。Windows 上同样的道理用/DEPENDENTLOADFIXER或直接在构建机复制 DLL 到产物目录。5. 把产物收成 curl.zip目录组织、动态库依赖与验证手段5.1 一个可用的跨平台 zip 包最小目录结构三个平台的产物收集到同一套目录规则里能显著降低集成方的使用成本。我常用的结构如下目录内容说明bin/curl.exe 或 curl 可执行文件命令行工具平台标识可选include/curl/curl.h等头文件所有头文件保持原目录结构lib/库文件.dll/.so/.dylib/.lib/.a动态库与导入库放一起doc/版本说明、LICENSE、编译参数记录方便集成方确认特性开关Windows 下还会额外把 OpenSSL 的 DLLlibssl、libcrypto放进bin/或单独建deps/目录因为 Windows 的可执行文件优先从自身所在目录加载 DLL。Linux 和 macOS 则用RPATH或install_name处理。这个结构不是官方标准但它是 SDK 发布最常见的组织方式使用者只需要把include/加进编译头文件路径、lib/加进链接路径、bin/加进系统 PATH。头文件的收集不能手动复制直接用 CMake 的安装规则cmake --install build-linux --prefix /tmp/curl-package--prefix会在指定目录下按照CMakeLists.txt里的install()规则生成include/、lib/、bin/结构比手动拷贝可靠得多。Windows 和 macOS 同理。装完之后用 zip 命令打包时会保留权限位这在使用者的 Linux 和 macOS 上很重要。5.2 发布前必须做的三件事依赖扫描、特性确认、最小连接验证逐个平台验证是一套流水线动作。Linux 用ldd查动态库依赖macOS 用otool -LWindows 用dumpbin /dependents。这一步的目的是建立依赖清单清单里每一项要么属于系统基础库、要么需要随包发布# Linux 查看可执行文件的动态依赖 ldd /tmp/curl-package/bin/curl # macOS 查看 dylib 依赖与路径 otool -L /tmp/curl-package/bin/curl # Windows需在 Visual Studio 开发者命令行中执行 dumpbin /dependents C:\curl-package\bin\curl.exe依赖扫描完成后用curl -V确认特性列表里有值得记录的项SSL、HTTP2、IDN 等这份输出直接写进doc/BUILD_INFO.txt让集成方一眼看清这个库支持什么协议、用了什么后端。最后做一个最小连接验证脚本内容如下curl -I https://curl.se --connect-timeout 5 || exit 1这一步通过说明这个包在当前的系统上能完成 TLS 握手和 HTTP 请求。发布动作本身很简单zip -r curl-linux-x64.zip /tmp/curl-package随后把关键构建参数写进一个build.json归档以免三个月后自己都忘了当时编了哪些特性。6. 进阶用交叉编译与 CI 矩阵把三端产物一次跑出来6.1 Linux 上交叉编译 Windows 版本MinGW 方案如果开发机是 Linux又需要产出 Windows 的 curl.zip不必非得准备一台 Windows 机器。用 MinGW-w64 工具链可以直接在 Linux 上编出 Windows 可执行文件适合快速出包或做 CI。前提是系统里安装了mingw-w64和针对 Windows 的 OpenSSL 库一般用x86_64-w64-mingw32-openssl包cmake -B build-win-cross \ -DCMAKE_SYSTEM_NAMEWindows \ -DCMAKE_C_COMPILERx86_64-w64-mingw32-gcc \ -DCMAKE_INSTALL_PREFIX/tmp/curl-win64 \ -DBUILD_SHARED_LIBSON \ -DCURL_USE_OPENSSLON \ -DOPENSSL_ROOT_DIR/usr/x86_64-w64-mingw32 cmake --build build-win-cross -j$(nproc) cmake --install build-win-crossCMAKE_SYSTEM_NAMEWindows会触发 CMake 的交叉编译模式自动调整搜索路径到 MinGW 的 sysrootCMAKE_C_COMPILER指定编译器。这个方案能省去专门的 Windows 构建机但要注意MinGW 产物对 Windows 系统的依赖较温和不依赖 VC 运行库却需要把 mingw 的运行时库libgcc_s_seh-1.dll、libwinpthread-1.dll一并打进包里。这一步容易漏漏了就是目标机器上经典的0xc000007b 应用程序无法正常启动。6.2 CI 矩阵构建一套 YAML 产出三平台 zip当项目进入稳定发布期手动在一台 Linux、一台 Windows、一台 macOS 上分别执行编译命令仍容易出错。更可靠的是把第 3 章的三个平台命令写进 CI 的矩阵任务里每个平台一个 job产物各自上传最后汇总。这里以通用 CI 配置的写法示例重点在三个平台的差异化参数matrix: include: - os: ubuntu-latest arch: x64 configure: cmake -B build -DCMAKE_BUILD_TYPERelease -DCURL_USE_OPENSSLON - os: windows-latest arch: x64 configure: cmake -B build -G Visual Studio 17 2022 -A x64 -DCURL_USE_OPENSSLON - os: macos-latest arch: arm64 configure: cmake -B build -DCMAKE_BUILD_TYPERelease -DCURL_USE_SECTRANSPON -DCMAKE_OSX_ARCHITECTURESarm64;x86_64每个平台的 job 里后续统一执行cmake --build build --config Release、cmake --install build --prefix /tmp/pkg、zip -r curl.zip /tmp/pkg最后把curl.zip作为构建产物上传。这套矩阵的最大价值是让三端编译变成每次发版自动进行的动作而不是依赖某位开发者的个人电脑。执行过程中如果某个平台失败日志里能直接定位到 CMake 配置或依赖安装步骤修起来比在黑匣子里猜快得多。我踩过的最深刻的一个坑是把 Windows 的 OpenSSL 依赖想当然地认为会自动带进包结果交付给测试同学时对方的机器上缺 DLL整条链路被卡了两天。从那以后我养成一个习惯任何平台的 curl.zip发布前必须做一次干净虚拟机验证——用一台没有编译环境的机器解压 zip、运行 curl、执行一次 HTTPS 请求全通过才能算这个包真的可用。这个验证步骤会消耗一点时间但相比用户在集成阶段发现缺依赖再返工它便宜太多了。希望这篇笔记能帮你把 libcurl 的跨平台编译从玄学变成一套可以稳定复现的流水线。本文还有配套的精品资源点击获取