1. 项目概述为什么我们需要手动编译gRPC在微服务架构和云原生技术大行其道的今天gRPC作为一款高性能、跨语言的开源RPC框架几乎成了现代分布式系统通信的标配。你可能已经在很多教程里看到过pip install grpcio或者go get google.golang.org/grpc这样简单的安装命令。那么为什么我们还需要大费周章地讨论在Linux和Windows下手动下载、编译和安装gRPC呢这恰恰是新手和老手之间的一道分水岭。简单来说直接使用包管理器安装的通常是预编译的二进制库或绑定它方便快捷适合绝大多数应用开发场景。但是当你遇到以下情况时手动编译就成了必须掌握的技能首先你需要针对特定平台比如某个定制化的ARM服务器或旧版本操作系统进行优化其次你需要集成gRPC的源码到自己的项目构建体系中进行深度定制例如修改协议、增加拦截器功能再者你可能需要调试gRPC库本身的代码或者使用尚未发布到包管理器的某个前沿特性分支最后在某些严格的离线环境或安全合规要求下从源码构建是唯一被允许的软件引入方式。我经历过不止一次因为系统环境差异导致预编译包无法正常工作的情况尤其是在混合架构的CI/CD流水线里。从源码开始虽然步骤繁琐一些但能让你对gRPC的依赖关系、构建选项有彻底的控制权相当于掌握了“从零搭建”的主动权后续排查问题也会更有底气。本文将带你完整走通在Linux以Ubuntu/CentOS为例和Windows以Visual Studio为例两大主流平台下从获取源码到成功编译安装gRPC的全过程并分享其中最容易踩坑的细节。2. 环境准备与核心依赖解析手动编译gRPC绝非一个孤立的操作它更像是一个“系统工程”成功与否极大程度上取决于你的基础环境是否完备。很多人编译失败第一步就栽在了依赖缺失或版本不对上。2.1 Linux环境依赖清单与安装在Linux环境下我们通常使用CMake作为构建工具。以下是在Ubuntu 20.04/22.04或CentOS 7/8等常见发行版上需要准备的核心工具链和库。1. 编译器与构建工具这是最基础的。你需要一个足够新的GCC或Clang编译器、CMake、构建自动化工具如make或ninja以及git。# 对于基于Debian/Ubuntu的系统 sudo apt-get update sudo apt-get install -y build-essential autoconf libtool pkg-config cmake git # 对于基于RHEL/CentOS的系统 sudo yum groupinstall -y Development Tools sudo yum install -y autoconf libtool pkgconfig cmake3 git # 如果yum仓库的cmake版本过低可能需要从源码安装或使用EPEL仓库的cmake3并创建软链接 # sudo ln -s /usr/bin/cmake3 /usr/local/bin/cmake注意gRPC的C编译对C11标准支持有要求GCC 4.8或Clang 3.4是底线建议使用GCC 7或Clang 5以获得更好的兼容性和性能。使用gcc --version和cmake --version确认版本。2. 第三方库依赖gRPC的核心功能依赖于几个关键的第三方库它们通常不会被默认安装。Protocol Buffers (protobuf):gRPC的消息序列化标准。虽然gRPC源码树作为子模块包含了特定版本的protobuf源码并且编译时会自动构建它但为了使用protoc编译器后续生成代码需要我们通常需要单独安装protobuf的开发包。我建议先通过包管理器安装一个基础版本。# Ubuntu sudo apt-get install -y libprotobuf-dev protobuf-compiler # CentOS sudo yum install -y protobuf-devel protobuf-compiler编译gRPC时它会优先使用自己子模块内的protobuf源码这能确保版本绝对匹配避免ABI不兼容的噩梦。系统安装的protoc编译器只要版本不太旧一般可用于代码生成。c-ares:用于异步DNS解析提升服务发现性能。如果缺失gRPC会回退到较慢的getaddrinfo。# Ubuntu sudo apt-get install -y libc-ares-dev # CentOS sudo yum install -y c-ares-develOpenSSL:提供TLS/SSL加密支持对于安全的gRPC连接如gRPC over TLS至关重要。1.1.1及以上版本是安全的起点。# Ubuntu sudo apt-get install -y libssl-dev # CentOS sudo yum install -y openssl-develzlib:用于支持压缩减少网络传输量。# Ubuntu sudo apt-get install -y zlib1g-dev # CentOS sudo yum install -y zlib-develabseil-cpp (可选但推荐):Google开源的C通用库集合。gRPC现代版本越来越多地依赖Abseil。通过包管理器安装可以加速编译。# Ubuntu (20.04) sudo apt-get install -y libabsl-dev # CentOS可能需要从源码编译或使用第三方仓库3. 获取gRPC源码使用git克隆仓库并务必记得同步子模块。这是最关键的一步漏掉子模块会导致编译根本无法开始。git clone --recurse-submodules -b v1.60.0 https://github.com/grpc/grpc.git # 进入目录 cd grpc # 如果克隆时忘了 --recurse-submodules可以执行以下命令补救 git submodule update --init --recursive这里我指定了v1.60.0标签这是为了确保教程的稳定性和可复现性。在实际操作中你可以克隆master分支获取最新代码但请注意前沿代码可能存在不稳定的风险。对于生产环境强烈建议使用一个稳定的发布版本标签。2.2 Windows环境依赖清单与安装Windows下的编译体验与Linux截然不同核心在于对Visual Studio构建工具链的依赖。我推荐使用Visual Studio 2019或2022的社区版它们完全免费且功能强大。1. 核心工具链安装Visual Studio:安装时在“工作负载”中必须勾选“使用C的桌面开发”确保包含“CMake工具”和“Windows 10 SDK”或Windows 11 SDK。CMake工具是后续编译的指挥棒。Git:从 git-scm.com 下载并安装。安装时建议选择“Git from the command line and also from 3rd-party software”以便在VS或终端中都能使用。Active Perl 和 Go (可选但常见):某些测试脚本或第三方依赖如BoringsSL的构建过程可能需要Perl。Go语言在编译gRPC插件时可能需要。你可以从Strawberry Perl和Go官网下载安装。安装后确保它们所在的目录如C:\Strawberry\perl\bin和C:\Go\bin被添加到系统的PATH环境变量中。2. 获取gRPC源码在Windows上路径中最好不要有空格或中文这能避免很多潜在的脚本错误。我习惯在C:\src或D:\dev这样的目录下操作。 打开“x64 Native Tools Command Prompt for VS 2022”或2019。这个命令行工具已经配置好了VC的编译环境至关重要不要在普通CMD或PowerShell中直接开始。# 在这个VS开发人员命令提示符中操作 cd D:\dev git clone --recurse-submodules -b v1.60.0 https://github.com/grpc/grpc.git cd grpc # 同样如果忘了同步子模块 git submodule update --init --recursive3. 第三方库依赖的Windows之道在Linux上我们用包管理器在Windows上则复杂一些。gRPC的CMake脚本在Windows上编译时对于c-ares、zlib等依赖首选策略是自动从源码下载并编译通过FetchContent或ExternalProject机制。这意味着只要你网络通畅CMake通常会帮你处理好。但为了更可控有时我们也需要手动准备。OpenSSL:Windows上没有系统的OpenSSL开发包。gRPC的CMake脚本支持自动从源码构建BoringSSLGoogle的OpenSSL分支这通常是默认且最省事的方式。你也可以手动安装预编译的OpenSSL例如从Shining Light Production下载然后通过CMake变量-DgRPC_SSL_PROVIDERpackage和-DOPENSSL_ROOT_DIRC:\path\to\openssl来指定。Protobuf:和Linux一样gRPC会编译自己子模块里的protobuf。你也可以单独安装protobuf的Windows版本并将protoc.exe的路径加入PATH。3. Linux平台编译安装实战假设你现在在一个干净的Ubuntu 22.04系统上并且已经按照上一节准备好了所有依赖和源码。我们采用CMake的“out-of-source build”方式进行编译即在源码目录外创建一个独立的构建目录这是保持源码清洁的最佳实践。3.1 使用CMake配置构建参数首先在grpc源码同级目录创建一个构建文件夹并进入。# 假设当前在 /home/user 目录grpc源码在 /home/user/grpc mkdir -p grpc_build cd grpc_build接下来运行CMake进行配置。这里有几个关键参数决定了编译的产物和方式cmake ../grpc \ -DCMAKE_BUILD_TYPERelease \ -DgRPC_INSTALLON \ -DgRPC_BUILD_TESTSOFF \ -DgRPC_PROTOBUF_PROVIDERmodule \ -DgRPC_ZLIB_PROVIDERpackage \ -DgRPC_CARES_PROVIDERpackage \ -DgRPC_SSL_PROVIDERpackage \ -DABSL_PROPAGATE_CXX_STDON参数解析与避坑指南-DCMAKE_BUILD_TYPERelease: 生成优化后的发布版本。如果是调试用Debug但体积会大很多速度慢。-DgRPC_INSTALLON:这个至关重要它告诉CMake生成安装规则。后续才能使用make install将编译好的库和头文件安装到系统目录。-DgRPC_BUILD_TESTSOFF: 除非你需要运行gRPC的单元测试否则关掉它以大幅缩短编译时间。-DgRPC_PROTOBUF_PROVIDERmodule: 指示CMake使用grpc源码树内作为子模块的protobuf进行编译。这是确保兼容性的推荐做法。-DgRPC_ZLIB_PROVIDERpackage-DgRPC_CARES_PROVIDERpackage-DgRPC_SSL_PROVIDERpackage: 告诉CMake使用我们之前通过apt-get安装的系统包package来提供zlib、c-ares和OpenSSL。如果CMake找不到它会退而求其次尝试从源码下载编译但这会增加不确定性。-DABSL_PROPAGATE_CXX_STDON: 一个关于Abseil库和C标准的兼容性选项建议设置。执行完CMake命令后如果一切顺利你会看到大量输出最后以-- Configuring done和-- Generating done结束没有红色错误信息。此时CMake已经在当前grpc_build目录生成了构建系统文件如Makefile。3.2 执行编译与安装配置成功后就可以开始编译了。使用make命令并利用-j参数指定并行编译的作业数这能充分利用多核CPU显著加快速度。作业数通常设置为CPU核心数或核心数1。# 查看CPU核心数 nproc # 假设输出是8则使用-j8或-j9进行编译 make -j8这个过程会持续一段时间取决于你的机器性能。你会看到屏幕上滚动着大量的编译命令。如果遇到错误通常是某个依赖缺失或版本冲突需要根据错误信息回头检查环境准备环节。编译成功后进行安装。安装会将编译生成的库文件如libgrpc.alibgrpc.a、头文件以及重要的工具如grpc_cpp_plugin复制到系统的标准路径下默认通常是/usr/local/lib和/usr/local/include。sudo make install安装完成后系统应该能自动找到这些文件。你可以验证一下# 检查库文件是否安装 ls /usr/local/lib/libgrpc* # 检查插件是否存在这个插件用于protoc生成gRPC服务代码 ls /usr/local/bin/grpc_cpp_plugin3.3 验证安装与配置系统路径最后一步是验证我们的劳动成果。创建一个简单的测试程序来确认gRPC库可以被找到并链接。更新动态链接库缓存因为安装到了/usr/local/lib可能需要更新一下系统的动态链接器缓存。sudo ldconfig编写测试代码创建一个test_grpc.cc文件内容可以是一个最简单的gRPC客户端或服务器示例。这里我们用一个极简的包含头文件的程序来测试编译。// test_grpc.cc #include grpcpp/grpcpp.h #include iostream int main() { std::cout gRPC C library version: grpc::Version() std::endl; // 尝试创建一个ChannelBuilder不实际连接只是为了验证链接 auto channel grpc::CreateChannel(localhost:50051, grpc::InsecureChannelCredentials()); std::cout gRPC library is successfully installed and linked! std::endl; return 0; }编译测试程序使用pkg-config来获取正确的编译和链接标志。确保你已安装pkg-config。# 安装pkg-config sudo apt-get install -y pkg-config # 编译测试程序 g -stdc11 test_grpc.cc -o test_grpc \ $(pkg-config --cflags --libs grpc) \ $(pkg-config --cflags --libs grpc) \ -lprotobuf -lpthread -lssl -lcrypto -lcares -lz如果pkg-config找不到包可能需要指定PKG_CONFIG_PATHexport PKG_CONFIG_PATH/usr/local/lib/pkgconfig:$PKG_CONFIG_PATH然后再运行上面的编译命令。运行测试如果编译成功运行生成的可执行文件。./test_grpc如果输出显示了gRPC的版本号和成功信息那么恭喜你在Linux上的手动编译安装就大功告成了。4. Windows平台编译安装实战Windows下的编译我们主要依托Visual Studio的CMake集成环境或者命令行。这里我介绍更通用、更接近CI流程的命令行方式。4.1 使用CMake与Visual Studio生成器在之前打开的“x64 Native Tools Command Prompt for VS 2022”中我们已经位于D:\dev\grpc目录。同样我们创建一个独立的构建目录。mkdir build_x64 cd build_x64接下来运行CMake进行配置。关键区别在于生成器Generator和平台的选择。cmake .. -G Visual Studio 17 2022 -A x64 ^ -DCMAKE_BUILD_TYPERelease ^ -DgRPC_INSTALLON ^ -DgRPC_BUILD_TESTSOFF ^ -DgRPC_PROTOBUF_PROVIDERmodule ^ -DgRPC_SSL_PROVIDERmodule ^ -DgRPC_ZLIB_PROVIDERmodule ^ -DgRPC_CARES_PROVIDERmoduleWindows参数解析-G Visual Studio 17 2022: 指定使用Visual Studio 2022的生成器。如果是VS2019则使用Visual Studio 16 2019。-A x64: 指定目标架构为64位。这是必须的除非你需要32位库。-DgRPC_SSL_PROVIDERmodule等在Windows上我通常将依赖的provider都设为module让CMake自动下载并编译依赖库的源码。这比在Windows上手动配置每个依赖的开发包要简单可靠得多尤其对于OpenSSL。CMake会通过Git或下载压缩包的方式获取这些依赖的源码。执行这个命令后CMake会开始配置。第一次运行时它会下载一系列第三方依赖如zlib、c-ares、abseil、re2等并编译它们。这个过程需要保持网络畅通时间可能较长请耐心等待。最终会在build_x64目录下生成一个grpc.sln解决方案文件。4.2 使用MSBuild编译与安装配置完成后我们使用MSBuildVisual Studio的构建工具来编译整个解决方案。我们主要需要INSTALL这个项目它会自动编译所有依赖项并执行安装。# 编译INSTALL项目Release配置 cmake --build . --config Release --target INSTALL或者你也可以直接使用MSBuild命令msbuild INSTALL.vcxproj /p:ConfigurationRelease这个命令会执行完整的编译和安装过程。安装的默认路径是C:\Program Files (x86)\grpc。如果你想安装到其他目录可以在CMake配置时添加-DCMAKE_INSTALL_PREFIXD:\my_install_path参数。4.3 验证安装与集成到项目安装完成后我们可以在安装目录下找到头文件include和库文件lib。在Windows上静态库后缀是.lib。验证安装目录检查C:\Program Files (x86)\grpc或你的自定义目录下是否有bin包含grpc_cpp_plugin.exe、include、lib文件夹。创建VS项目测试最直接的验证方式是创建一个新的Visual Studio控制台项目进行测试。打开Visual Studio创建新的“控制台应用”项目。在项目属性中进行以下关键配置C/C - 常规 - 附加包含目录添加gRPC的include目录例如C:\Program Files (x86)\grpc\include。链接器 - 常规 - 附加库目录添加gRPC的lib目录例如C:\Program Files (x86)\grpc\lib。链接器 - 输入 - 附加依赖项添加需要链接的库文件名。通常至少需要grpc.lib grpc.lib gpr.lib address_sorting.lib upb.lib libprotobuf.lib libprotoc.lib ws2_32.lib crypt32.libC/C - 代码生成 - 运行库确保与gRPC编译时使用的运行时一致。如果gRPC是用/MT静态链接运行时编译的你的项目也要设置成/MT或/MTdDebug否则会出现链接错误。更常见的做法是gRPC使用/MD动态链接运行时项目也使用/MD。这取决于你CMake配置时的-DCMAKE_MSVC_RUNTIME_LIBRARY设置默认通常是MultiThreadedDLL对应/MD。将之前Linux验证用的test_grpc.cc代码复制到项目中。编译并运行。如果成功输出版本信息则说明Windows下的编译安装和项目配置成功。5. 高级配置、问题排查与经验分享即使按照上述步骤操作你也可能会遇到各种“坑”。这一节分享一些高级配置选项和常见问题的排查思路。5.1 关键CMake选项深度解析除了基本选项以下选项在特定场景下非常有用-DCMAKE_PREFIX_PATH/path/to/custom/libs: 如果你将某些依赖如Protobuf安装在了非标准路径用这个变量告诉CMake去哪里找。-DCMAKE_INSTALL_PREFIX/usr/local/grpc-1.60.0: 在Linux上如果你不想污染系统目录/usr/local可以安装到自定义前缀。之后需要通过LD_LIBRARY_PATH和PKG_CONFIG_PATH环境变量来让系统找到它。-DgRPC_BUILD_GRPC_NODE_PLUGINOFF-DgRPC_BUILD_GRPC_CSHARP_PLUGINOFF等如果你不需要某些语言的插件如Node.js C#可以关闭它们以加快编译速度。-DgRPC_USE_PROTO_LITEON: 使用轻量级的protobuf lite运行时适用于资源受限的环境如移动端但会缺失一些高级特性如反射。-DBUILD_SHARED_LIBSON: 默认编译的是静态库.a或.lib。设置此选项为ON可以编译生成动态链接库.so或.dll。注意gRPC官方文档曾指出C API的二进制兼容性在动态库上难以保证因此生产环境通常推荐使用静态链接。5.2 Linux/Windows常见编译错误与解决方案问题1CMake配置时找不到OpenSSL。Linux:确保已安装libssl-dev。如果安装在自定义路径使用-DOPENSSL_ROOT_DIR/path/to/openssl。Windows:确保-DgRPC_SSL_PROVIDERmodule让CMake自动编译BoringSSL。如果网络下载失败可以尝试手动下载BoringSSL源码放在third_party/boringssl-with-bazel目录下注意目录名然后重试。问题2编译过程中protobuf相关错误如“undefined reference togoogle::protobuf::...”。这几乎总是因为protobuf库的版本不匹配或链接顺序问题。最彻底的解决方案是确保gRPC使用其自带的protobuf子模块编译即设置-DgRPC_PROTOBUF_PROVIDERmodule。编译安装后你的程序在链接时必须先链接grpc再链接protobuf。问题3在Windows上链接时出现“LNK2005: 符号已在...中定义”或“LNK2038: 检测到‘RuntimeLibrary’不匹配”。这是Windows VC编译的经典问题。确保所有库gRPC、protobuf、你的项目使用相同的运行时库/MT/MTd/MD/MDd和平台工具集Visual Studio版本进行编译。最安全的方法是你的项目使用与gRPC完全相同的Visual Studio版本和构建配置Release/Debug进行编译。问题4git submodule update失败或速度极慢。由于网络原因同步grpc的第三方子模块特别是boringssl可能会失败。可以尝试修改git配置使用代理或者手动修改.gitmodules文件中的URL将https://github.com/...替换为https://ghproxy.com/https://github.com/...等镜像地址需注意镜像服务的可用性。更直接的方法是在克隆时指定深度和并行数git clone --depth 1 --jobs 8 --recurse-submodules repo_url。问题5编译内存不足特别是在虚拟机上。gRPC的完整编译非常消耗内存尤其是C部分。如果内存不足可以尝试减少并行编译作业数make -j2。只编译你需要的语言运行时。例如如果你只用C可以尝试在CMake配置后只编译grpc相关的目标而不是整个ALL_BUILD或INSTALL。但这需要对CMake目标结构比较了解。增加交换空间swap。5.3 生产环境部署建议版本固化为生产环境编译时务必使用固定的发布版本标签如v1.60.0而不是master分支。这能确保每次构建的一致性。静态链接优先对于部署到服务器的应用建议静态链接gRPC和protobuf库。这样可以避免目标服务器上缺失特定版本的动态库带来的依赖问题。在Linux上静态链接时可能需要额外链接-lpthread -ldl -lrt等系统库。制作编译镜像如果需要在CI/CD中频繁编译可以制作一个Docker镜像Linux或虚拟机模板Windows其中预装所有正确版本的依赖和工具。这能极大提升编译的可靠性和速度。分离编译与安装环境可以在一个专门的环境“构建机”上完成编译然后将生成的库文件、头文件和工具打包分发到最终的生产或开发环境“目标机”使用。在Linux上可以使用make DESTDIR/tmp/grpc-release install来指定一个临时安装根目录然后打包/tmp/grpc-release下的内容。手动编译安装gRPC的过程就像一次对这套通信框架的深度体检。你会清楚地知道它依赖什么、由哪些部分组成、如何被构建出来。这份理解在你未来进行性能调优、问题排查和深度定制时会成为无比宝贵的财富。虽然第一次操作可能会遇到一些障碍但一旦走通你会发现面对复杂的构建问题时自己拥有了更多的解决工具和思路。