1. 项目缘起为什么要在Windows上手动编译gRPC如果你是一个在Windows平台上用Visual Studio 2019搞C开发的迟早会碰到需要集成gRPC的情况。无论是做微服务、游戏服务器还是需要高性能RPC的桌面应用gRPC都是绕不开的现代网络通信框架。官方文档和网上教程很多但真到了自己动手编译的时候十个有八个会卡在某个环节上。最常见的场景是你兴冲冲地打开vcpkg一句vcpkg install grpc:x64-windows下去结果发现要么编译时间长得离谱要么依赖冲突要么生成的库文件和你项目的运行时库MT/MD不匹配最后链接器报一堆找不到符号的错误直接心态爆炸。所以放弃幻想准备战斗。手动编译gRPC虽然步骤繁琐但它是让你真正掌控项目依赖、确保环境纯净、并能针对自己项目进行定制化优化的唯一可靠途径。这个过程就像组装一台高性能电脑自己挑选每一个零件依赖库自己拧每一颗螺丝编译配置虽然麻烦但装好之后系统无比稳定你对它的了解也深入骨髓。今天我就把我自己从无数次失败中总结出来的、在Windows 10/11 VS2019环境下从零开始编译gRPC包括其核心依赖如protobuf、absl等的完整流程、核心原理和避坑指南毫无保留地分享给你。2. 战前准备理清依赖关系与工具链在动手敲命令之前我们必须像将军看地图一样先搞清楚gRPC这座“城池”的构造和它外围的“护城河”。盲目开干只会陷入无尽的依赖地狱。2.1 gRPC的核心组件与依赖图谱gRPC不是一个单一的库而是一个由多个紧密协作的组件构成的生态系统。在Windows上编译你需要面对以下核心成员Protocol Buffers (protobuf)这是gRPC的“语言”。gRPC使用protobuf作为接口定义语言IDL和默认的序列化协议。编译gRPC前必须先编译protobuf的编译器protoc和对应的C运行时库。这是最基础、也最容易出错的依赖。Abseil (absl)Google开源的C通用库提供了大量标准库的补充和替代组件如字符串处理、容器、算法等。gRPC大量使用了absl因此它必须被正确编译并链接。c-ares一个异步DNS解析库。gRPC使用它来处理域名解析这对于服务发现和负载均衡至关重要。zlib和OpenSSL或BoringSSL分别用于压缩和加密。gRPC的HTTP/2传输层需要TLS加密OpenSSL而某些功能可能用到压缩zlib。官方推荐在Windows上使用OpenSSL。gRPC CoregRPC的核心C语言实现提供了最底层的API。gRPC C基于Core的C封装层也是我们最常使用的API。gRPC Plugins最重要的就是grpc_cpp_plugin.exe它是一个protoc的插件用于在编译.proto文件时自动生成gRPC服务端和客户端的C桩代码。它们之间的依赖关系大致是gRPC C-gRPC Core-protobuf,absl,c-ares,OpenSSL,zlib。编译顺序必须遵循这个依赖链。2.2 工具链选择CMake、Ninja与VS2019的三角关系在Windows上我们主要使用CMake作为构建系统生成器。但这里有个关键选择为CMake指定什么后端GeneratorVisual Studio 2019 解决方案-G “Visual Studio 16 2019”这是最直观的方式CMake会生成一个.sln文件你可以用VS2019打开并像普通项目一样编译。但我不推荐这么做。原因有二一是编译速度慢VS的MSBuild在编译大型项目时效率不如Ninja二是会生成一大堆.vcxproj文件目录结构混乱不利于脚本化自动化。Ninja-G “Ninja”这是强烈推荐的方式。Ninja是一个专注于速度的小型构建系统。CMake生成build.ninja文件然后Ninja以极高的并行度执行编译任务。它的输出清晰速度快得多。因此我们的黄金组合是CMake Ninja VS2019的MSVC编译器。你需要确保安装最新版的CMake3.15并将其bin目录加入系统PATH。安装Ninja同样将其所在目录加入PATH。你可以通过pip install ninja或从GitHub release页面下载可执行文件。确保VS2019的开发者命令行环境可用。我们后续所有操作都需要在一个“适用于 VS 2019 的 x64 本机工具命令提示符”中执行。这个环境会自动设置好cl.exe,link.exe等编译工具以及必要的库路径。注意永远不要在普通的CMD或PowerShell中直接操作。必须使用VS2019自带的那个“开发者命令提示符”否则CMake找不到编译器。2.3 源码获取Git与子模块的坑gRPC的源码通过Git管理并且使用了Git子模块Submodule来管理其依赖如absl, protobuf等。# 克隆主仓库推荐使用深度克隆以节省时间 git clone -b v1.60.0 --depth 1 --recursive https://github.com/grpc/grpc.git cd grpc这里的--recursive参数至关重要它会自动初始化并更新子模块。如果克隆时忘了加或者网络问题导致子模块拉取不全你需要git submodule update --init --recursive踩坑实录1子模块拉取失败是最常见的问题之一。因为依赖的仓库如google/abseil-cpp可能在国外容易超时。解决方法有两个一是使用代理需自行配置git的http.proxy二是耐心重试多次。有时候手动进入third_party目录分别克隆那些失败的子模块仓库是最终的解决方案。3. 编译实战分步拆解与参数精讲假设我们的工作目录是D:\Dev\grpc_build我们将在这里进行所有操作。目标是编译出适用于x64架构、使用MD动态链接运行时库的Release版本。3.1 第一阶段编译第三方依赖protobuf, absl, c-ares等gRPC的CMakeLists.txt本身包含了编译这些依赖的选项但为了更精细的控制我更喜欢先手动编译核心依赖特别是protobuf。步骤1编译并安装protobuf# 1. 进入protobuf源码目录 (grpc/third_party/protobuf) cd D:\Dev\grpc_build\grpc\third_party\protobuf # 2. 创建并进入构建目录 mkdir cmake_build cd cmake_build # 3. 配置CMake cmake .. -G Ninja ^ -DCMAKE_BUILD_TYPERelease ^ -DCMAKE_INSTALL_PREFIXD:\Dev\grpc_sdk\protobuf ^ -Dprotobuf_BUILD_TESTSOFF ^ -Dprotobuf_MSVC_STATIC_RUNTIMEOFF ^ -DABSL_PROPAGATE_CXX_STDON # 4. 编译并安装 cmake --build . --config Release --parallel 8 cmake --install . --config Release参数精讲-DCMAKE_INSTALL_PREFIX指定安装目录。将所有编译好的头文件和库文件集中安装到一个自定义的SDK目录如D:\Dev\grpc_sdk便于管理。-Dprotobuf_MSVC_STATIC_RUNTIMEOFF这是关键设置为OFF会编译链接到动态运行时库MD/MDd这与后续用VS2019默认创建的项目属性一致。如果设为ON则会使用静态运行时库MT/MTd极易导致与你的主项目冲突。-DABSL_PROPAGATE_CXX_STDON确保abslprotobuf内部使用的C标准设置能正确传递。步骤2编译并安装c-ares和zlib采用类似protobuf的流程在各自的third_party目录下用CMake配置、编译并安装到统一的D:\Dev\grpc_sdk目录下。注意同样要设置-DCMAKE_BUILD_TYPERelease和相应的运行时库选项。步骤3处理OpenSSLOpenSSL的编译稍复杂。对于初学者最稳妥的方法是使用预编译的二进制包。可以从 slproweb.com 下载适用于你系统架构Win64的OpenSSL安装包如Win64 OpenSSL v3.2.1。安装时选择 “The OpenSSL binaries (/bin) directory” 添加到系统PATH。记下安装路径比如C:\Program Files\OpenSSL-Win64。后续CMake需要知道这个路径。3.2 第二阶段编译gRPC核心库现在主角登场。我们回到gRPC的根目录。cd D:\Dev\grpc_build\grpc mkdir cmake_build cd cmake_build接下来是最核心的CMake配置命令一条命令决定了成败cmake .. -G Ninja ^ -DCMAKE_BUILD_TYPERelease ^ -DCMAKE_INSTALL_PREFIXD:\Dev\grpc_sdk\grpc ^ -DCMAKE_PREFIX_PATHD:\Dev\grpc_sdk\protobuf;C:\Program Files\OpenSSL-Win64 ^ -DgRPC_INSTALLON ^ -DgRPC_BUILD_TESTSOFF ^ -DgRPC_PROTOBUF_PROVIDERpackage ^ -DgRPC_PROTOBUF_PACKAGE_TYPECONFIG ^ -DProtobuf_DIRD:\Dev\grpc_sdk\protobuf\cmake ^ -DgRPC_ABSL_PROVIDERpackage ^ -DgRPC_CARES_PROVIDERpackage ^ -DgRPC_SSL_PROVIDERpackage ^ -DgRPC_ZLIB_PROVIDERpackage ^ -DOPENSSL_ROOT_DIRC:\Program Files\OpenSSL-Win64 ^ -DOPENSSL_USE_STATIC_LIBSOFF ^ -DCMAKE_MSVC_RUNTIME_LIBRARYMultiThreadedDLL关键参数逐行解析-DCMAKE_PREFIX_PATH这是CMake查找依赖包的路径。我们把之前安装protobuf的路径和OpenSSL的路径加在这里CMake就会自动去这些位置查找FindPackage所需的配置文件。-DgRPC_INSTALLON允许执行cmake --install命令将编译结果安装到CMAKE_INSTALL_PREFIX指定的目录。-DgRPC_PROTOBUF_PROVIDERpackage和-DProtobuf_DIR告诉gRPC“不要用你源码里自带的protobuf子模块去系统里找我指定的那个”。Protobuf_DIR必须指向protobuf安装目录下的cmake子目录那里有protobuf-config.cmake文件。-DgRPC_ABSL_PROVIDERpackage等同理告诉gRPC其他依赖也使用“package”模式即使用我们预先编译安装好的版本而不是编译源码树内的子模块。这能极大减少编译复杂度避免版本冲突。-DOPENSSL_ROOT_DIR和-DOPENSSL_USE_STATIC_LIBSOFF明确指定OpenSSL的根目录并告知使用动态链接的OpenSSL库libcrypto-3-x64.dll和libssl-3-x64.dll。-DCMAKE_MSVC_RUNTIME_LIBRARYMultiThreadedDLL另一个关键强制指定使用/MDRelease或/MDdDebug运行时库确保与之前编译的protobuf等依赖以及你未来的项目保持一致。配置成功后执行编译和安装cmake --build . --config Release --parallel 8 cmake --install . --config Release如果一切顺利你会在D:\Dev\grpc_sdk\grpc目录下看到完整的产出bin/: 包含grpc_cpp_plugin.exe,protoc.exe(可能是从protobuf目录拷贝来的) 等工具。include/: 所有头文件。lib/: 所有.lib导入库文件。cmake/: gRPC的CMake包配置文件方便其他项目用find_package(grpc)来引用。3.3 第三阶段验证与生成代码测试编译安装完成后必须验证其可用性。最好的方法就是实际用它编译一个示例。编写一个简单的.proto文件例如helloworld.proto。使用刚编译的工具链生成代码# 假设工具在 D:\Dev\grpc_sdk\grpc\bin D:\Dev\grpc_sdk\grpc\bin\protoc.exe --cpp_out. --grpc_out. --pluginprotoc-gen-grpcD:\Dev\grpc_sdk\grpc\bin\grpc_cpp_plugin.exe helloworld.proto这会生成helloworld.pb.cc和helloworld.grpc.pb.cc等文件。创建一个简单的VS2019控制台项目将生成的代码和gRPC的头文件、库目录配置进去。包含目录添加D:\Dev\grpc_sdk\grpc\include和D:\Dev\grpc_sdk\protobuf\include。库目录添加D:\Dev\grpc_sdk\grpc\lib和D:\Dev\grpc_sdk\protobuf\lib。附加依赖项链接器输入至少需要grpc.lib,grpc.lib,gpr.lib,address_sorting.lib,upb.lib,protobuf.lib,libcrypto.lib,libssl.lib等。最简单的方法是查看grpc/lib目录下的.lib文件根据你的需求添加。对于Release模式通常链接grpc.lib,grpc.lib,gpr.lib,protobuf.lib这几个核心库即可。运行时库确保项目属性 - C/C - 代码生成 - 运行时库设置为“多线程DLL (/MD)”与编译选项一致。复制DLL将grpc/bin和OpenSSL/bin目录下的所有.dll文件如grpc.dll,libcrypto-3-x64.dll等复制到你的可执行文件输出目录或者将它们所在的目录添加到系统PATH。如果能成功编译并运行一个简单的客户端-服务器示例那么恭喜你整个编译流程完全打通了。4. 深度排错常见编译与链接问题剖析即使按照上述步骤你也可能遇到各种错误。下面是我踩过的坑和解决方案。4.1 编译期错误找不到头文件或语法错误问题fatal error C1083: 无法打开包括文件: “absl/.../...h”或类似protobuf头文件找不到。根因CMake配置时-DCMAKE_PREFIX_PATH没有正确设置或者-DgRPC_XXX_PROVIDERpackage指定了package模式但CMake在指定路径下找不到对应的XXXConfig.cmake文件。排查检查D:\Dev\grpc_sdk\protobuf目录下是否有cmake/protobuf-config.cmake文件。检查CMake配置命令中-DCMAKE_PREFIX_PATH的路径分隔符是否正确Windows用分号;但在命令行中因转义问题常用引号包裹整个字符串。查看CMake生成的CMakeCache.txt文件搜索Protobuf_DIR、absl_DIR等变量的值看是否指向了正确的位置。解决确保依赖库是通过cmake --install安装的并且安装目录结构完整包含include,lib,cmake等子目录。如果缺失回到对应依赖的编译步骤重新安装。4.2 链接期错误LNK2005重复符号或LNK2019无法解析的外部符号这是最令人头疼的一类错误。场景一重复符号 (LNK2005)例如“void __cdecl absl::lts_20240116::... already defined in ...lib”。根因运行时库不匹配。这是Windows C开发的老大难问题。你的gRPC库是用/MD编译的但你的主项目设置成了/MT或多线程调试DLL/MDd与发布/MD混用。或者你链接了多个不同运行时库版本的相同库比如既链接了gRPC自带的absl又链接了自己单独编译的absl。解决统一运行时库确保你的主项目、以及所有你手动编译的依赖库protobuf, absl, gRPC在编译时使用的运行时库选项完全一致。对于Release版本全部使用/MD。这需要通过CMake的-DCMAKE_MSVC_RUNTIME_LIBRARYMultiThreadedDLL或Visual Studio项目属性来保证。清理旧库彻底删除旧的构建目录cmake_build和安装目录grpc_sdk从头开始严格按照上述流程确保所有组件编译参数一致。使用package模式如前所述使用-DgRPC_XXX_PROVIDERpackage可以强制gRPC使用外部统一的依赖避免其内部子模块编译出一套运行时库不一致的版本。场景二无法解析的外部符号 (LNK2019)例如“__declspec(dllimport) public: __cdecl grpc::...。根因库文件没找对或没链接项目配置的“附加库目录”或“附加依赖项”不正确、不完整。Debug/Release模式混淆试图在Debug模式下链接Release版本的库后缀不带d或者反之。这两种模式编译的库不兼容。代码生成器不匹配使用了不同编译器版本或不同工具集如v142 vs v143生成的库。确保你的VS2019项目使用的“平台工具集”与编译gRPC时CMake自动检测到的一致通常是Visual Studio 2019的默认工具集。解决仔细核对链接库去grpc_sdk/grpc/lib目录下确认你链接的.lib文件确实存在。对于Release模式链接grpc.lib,grpc.lib等对于Debug模式链接grpcd.lib,grpcd.lib等如果编译了Debug版本。检查项目配置管理器确保你的VS项目活动解决方案配置Debug/Release与所链接的库版本匹配。验证工具集在VS2019中项目属性 - 常规 - 平台工具集查看是否为“Visual Studio 2019 (v142)”。编译gRPC时CMake日志开头会显示检测到的工具集两者应一致。4.3 运行时错误找不到DLL问题程序编译链接成功但运行时弹出“无法找到grpc.dll”或“无法找到libcrypto-3-x64.dll”。根因动态链接库DLL没有放在应用程序可以找到的位置。Windows搜索DLL的顺序包括应用程序所在目录、系统目录、PATH环境变量中的目录。解决最直接将grpc_sdk/grpc/bin和OpenSSL/bin目录下的所有必要DLL复制到你的可执行文件.exe所在的输出目录如Debug/或Release/。一劳永逸开发环境将上述bin目录的路径添加到系统的用户PATH环境变量中。但要注意如果你有多个不同版本的gRPC或OpenSSL可能会引起冲突。不推荐静态链接理论上可以通过CMake选项-DgRPC_MSVC_STATIC_RUNTIMEON和-DCMAKE_MSVC_RUNTIME_LIBRARYMultiThreaded尝试编译静态库版本并将所有依赖静态链接。但这会极大增加最终可执行文件的大小且可能会因为静态库的符号冲突导致更复杂的问题对于gRPC这种依赖复杂的库在Windows上静态链接非常棘手。5. 进阶配置与生产环境优化当你成功编译出基础版本后可能还需要根据实际项目需求进行一些定制。5.1 编译Debug版本有时需要调试gRPC内部逻辑。只需在CMake配置时将-DCMAKE_BUILD_TYPERelease替换为-DCMAKE_BUILD_TYPEDebug并确保所有依赖如protobuf也以Debug模式编译并安装到不同的前缀路径如D:\Dev\grpc_sdk\protobuf_debug避免与Release版本冲突。链接时注意链接带d后缀的库文件。5.2 禁用不必要的组件以加速编译gRPC包含许多你可能用不到的扩展和工具可以通过CMake选项禁用-DgRPC_BUILD_CSHARP_EXTOFF \ -DgRPC_BUILD_GRPC_CPP_PLUGINON \ # 我们需要这个 -DgRPC_BUILD_GRPC_CSHARP_PLUGINOFF \ -DgRPC_BUILD_GRPC_NODE_PLUGINOFF \ -DgRPC_BUILD_GRPC_OBJECTIVE_C_PLUGINOFF \ -DgRPC_BUILD_GRPC_PHP_PLUGINOFF \ -DgRPC_BUILD_GRPC_PYTHON_PLUGINOFF \ -DgRPC_BUILD_GRPC_RUBY_PLUGINOFF \ # 禁用测试和示例代码 -DgRPC_BUILD_CODEGENON \ -DgRPC_BUILD_TESTSOFF \ -DgRPC_BUILD_EXAMPLESOFF5.3 集成到你的CMake项目手动管理包含目录和库文件很麻烦。最佳实践是将编译好的gRPC作为CMake的“包”来使用。在你的项目CMakeLists.txt中# 告诉CMake去哪里找我们自定义安装的gRPC set(CMAKE_PREFIX_PATH D:/Dev/grpc_sdk/grpc;${CMAKE_PREFIX_PATH}) # 查找gRPC包 find_package(gRPC CONFIG REQUIRED) find_package(Protobuf CONFIG REQUIRED) # 添加你的可执行文件 add_executable(my_app main.cpp) # 链接gRPC库 target_link_libraries(my_app PRIVATE gRPC::grpc gRPC::grpc gRPC::gpr Protobuf::libprotobuf) # 如果你用了gRPC代码生成还需要添加protobuf和grpc的代码生成支持 find_program(PROTOC_EXECUTABLE NAMES protoc PATHS D:/Dev/grpc_sdk/grpc/bin REQUIRED) find_program(GRPC_CPP_PLUGIN_EXECUTABLE NAMES grpc_cpp_plugin PATHS D:/Dev/grpc_sdk/grpc/bin REQUIRED)这样CMake会自动处理头文件路径、库文件链接甚至跨平台和Debug/Release配置的切换管理起来非常优雅。手动编译gRPC的过程就像一次精心准备的探险。初期会被复杂的依赖和诡异的错误困扰但一旦你亲手打通所有环节对整个构建链的理解会达到一个新的层次。以后遇到任何链接错误或运行时问题你都能快速定位到是哪个环节的配置出了偏差。这份掌控感是直接使用预编译包或包管理器无法给予的。最重要的是这套流程形成的脚本和配置可以成为你团队内部一份稳定的资产确保所有开发者的环境一致从根源上减少“在我机器上是好的”这类问题。
