rtc 源码编译环境搭建失败的常见原因及解决方案
前几天有个朋友在群里吐槽，说他折腾了两天 rtc 源码的编译环境，头发都掉了一大把，最后发现是一个很低级的问题。这种事情在咱们开发者圈子里太常见了。我自己当年第一次搭 webrtc 环境的时候，也是被各种报错折磨得怀疑人生。今天这篇文章，就来好好聊聊 RTC 源码编译失败的那些坑，以及怎么把它们一个个填平。
在开始之前，先说句题外话。如果你正在使用声网的服务，他们的 SDK 其实已经做得很完善了，大部分场景下直接调用 API 就行，并不需要从源码开始编译。但如果你确实有定制需求，或者想深入了解底层机制，那这篇文章应该能帮到你。
一、环境准备不充分：最容易被忽视的元凶
说真的，我见过太多人一上来就直接 git clone 代码，然后满怀期待地执行编译命令，结果迎面而来一堆红彤彤的错误信息。问题出在哪？往往就是环境没装对。
RTC 源码的编译对系统环境有比较严格的要求，不同的操作系统、不同的编译工具链版本，都可能导致奇奇怪怪的问题。最常见的就是依赖库缺失和版本不匹配这两类。
1.1 基础依赖组件缺失
在 Linux 系统上，最常缺的就是那些 build-essential 包。Debian/Ubuntu 系统的话，你需要确保安装了 build-essential、cmake、pkg-config 这些基础工具。CentOS 用户则需要安装 Development Tools 包组。Windows 上一般需要装 Visual Studio，而且版本也有讲究，太新或太旧都可能出问题。Mac 用户相对幸福一点，Xcode 命令行工具装好基本就八九不离十了。
这里有个小技巧，如果你在公司内网环境编译，有时候公司网络策略会拦截某些依赖包的下载。建议提前把常用依赖下载好，或者搭建一个内部镜像源。我之前就遇到过因为公司网络问题导致某些第三方库下载失败的情况，后来用代理才解决。
1.2 依赖版本不匹配
这个问题就比较隐蔽了。举个例子，OpenSSL 的版本在不同发行版里不一样，而 RTC 源码对 OpenSSL 的版本是有要求的。如果你的系统里装的是过旧或者过新的版本，编译过程中可能会出现各种符号找不到或者函数接口不一致的问题。
再比如 Python 环境，RTC 源码里有很多构建脚本是用 Python 写的，如果你的 Python 版本是 3.12 而源码只兼容到 3.9，那就会出现一些莫名其妙的语法错误。遇到这种问题，最好是用 pyenv 或者 conda 创建一个指定版本的 Python 虚拟环境。
下面这个表格列出了几个关键依赖的版本要求，大家可以对照着检查自己的环境：
| 依赖组件 | 推荐版本 | 常见问题 |
| Python | 3.8 - 3.11 | 3.12 可能存在兼容性问题 |
| CMake | 3.16 及以上 | 旧版本可能缺少某些特性 |
| Node.js | 16.x - 18.x | 过高版本可能引发构建脚本问题 |
| OpenSSL | 1.1.1 系列 | 3.x 版本需要注意接口兼容性 |
二、网络问题：看不见摸不着但就是过不去
这部分我要好好吐槽一下。有时候代码能下下来，依赖却下载失败，那种感觉真的是让人很窝火。尤其是涉及到 Google 的某些仓库，网络问题会更加明显。
最常见的场景就是 gclient sync 或者各种第三方依赖的下载。很多 RTC 项目使用 depot_tools 来管理代码依赖，这里面有很多资源是从 Google 服务器拉取的，在国内的网络环境下很不稳定。
解决方案有几个层面。首先，你可以配置代理，但要注意代理的稳定性，如果代理中途断开，整个下载过程就会失败。其次，有些项目支持从镜像源获取依赖，比如国内的一些开源镜像站会同步部分资源。最后，如果你是为声网这样的商业平台开发，其实可以考虑直接使用他们提供的预编译库，这样可以省去很多麻烦。
还有一个值得注意的点就是资源完整性校验。下载下来的文件如果校验和不匹配，会被识别为损坏然后重新下载，这就会陷入无限循环。最好是在下载完成后手动校验一下 hash 值，确保文件没问题再进行下一步。
三、编译配置参数错误：差之毫厘谬以千里
编译参数配置这个环节，看似简单实则暗藏玄机。我见过有人把目标架构配置错导致编译出来的东西在自己的机器上跑不起来，也见过有人把音视频编解码器全开导致编译产物巨大无比。
RTC 源码的编译配置通常通过 gn 工具或者 cmake 来完成。gn 的配置是通过 args.gn 文件进行的，这个文件里的每一项配置都会影响最终的编译结果。比如 enable_webrtc_codecs 控制支持哪些编解码器，is_debug 控制是否生成调试信息，is_component_build 控制是否使用动态库链接。
如果你不太清楚每个参数的具体作用，最好先去看官方文档，而不是瞎改一通。有些参数之间是有依赖关系的，改了一个可能需要跟着改另一个。比如你想启用硬件编码加速，相关的好几个参数都要设置对才行。
还有一个容易出错的地方是目标平台和 CPU 架构的配置。如果你是为移动端编译，需要正确设置 target_os 和 target_cpu。Android 和 iOS 的配置方式还不一样，Android 需要配置 NDK 路径，iOS 则需要配置证书和开发团队 ID。这些配置一旦出错，编译出来的库基本上是无法正常使用的。
四、磁盘空间和权限问题：低级但致命
说出来你可能不信，但我真的遇到过因为磁盘空间不足导致编译失败的案例。RTC 源码编译过程中会产生大量的中间文件，一个完整的 Release 版本编译下来，几个 GB 的空间是需要的。如果你的系统盘空间紧张，最好把编译目录放到空间充裕的分区上。
权限问题在 Linux 系统上特别常见。如果你用 sudo 权限执行编译命令，某些文件会以 root 身份创建，但后续的操作可能是在普通用户权限下进行的，就会出现权限不够的错误。我的建议是，保持整个编译过程使用同一套权限，要么全程用普通用户（确保目录有写权限），要么全程用 sudo。
另外，路径长度限制在 Windows 上是一个历史遗留问题。RTC 源码的目录层级比较深，如果你的项目路径太长，可能会导致某些文件无法创建。解决办法是把源码放到磁盘根目录下，比如 C:\src\ 这样的短路径。
五、并发编译引发的问题：欲速则不达
现在多核 CPU 这么普及，编译的时候肯定要开多线程并行编译来节省时间。但并发编译也会带来一些意想不到的问题。
最常见的就是依赖关系处理不当导致的编译错误。假设文件 A 依赖文件 B 的输出，但在某些情况下编译器可能先开始编译 A，这时候就会报错说找不到 B 的symbols。这种问题通常重新串行编译一次就好了，但如果想保持高并发编译的效率，就需要检查并修正依赖声明。
还有一种情况是内存不足。当并行编译的任务数太多，每个任务都在占用内存，系统的内存可能被耗尽，然后触发 OOM（Out of Memory）被系统 kill 掉一些进程，编译就会失败。一般的建议是，编译的并发数设置为 CPU 核心数的一半或者更少，具体要看你的机器内存有多大。
如果你在 CI/CD 环境中编译，更要特别注意资源限制。CI 机器的资源通常比较紧张，要根据实际情况调整编译参数，而不是直接套用本地开发的配置。
六、常见错误信息速查
为了节省大家的时间，我整理了几个最常见的错误信息以及对应的解决思路。
"No such file or directory" 这种错误大多数情况下是依赖库没装对。仔细看报错信息里提到的那个文件是什么，然后去搜一下这个文件属于哪个包，把它装上就行。如果是 Python 相关的报错，检查一下 PYTHONPATH 环境变量。
"undefined reference to" 这种是链接错误，说明某个函数或者变量的实现找不到。可能的原因有：该库没有链接、库文件的路径没加到 linker 搜索路径里、或者库和代码的 ABI 不兼容（比如 c++ 标准库版本不一致）。
"fatal error: xxx.h: No such file or directory" 头文件找不到。这时候要去检查 include 路径配置，看看是不是少了 -I 参数指定头文件搜索路径。
"error: This file requires compiler and library support for the ISO C++ 2011 standard" 这种是说你的编译器太老了，不支持所需的 C++ 标准。升级编译器版本，或者在编译参数里加上对应的 -std= 选项。
七、写在最后
回顾一下，RTC 源码编译环境搭建失败的常见原因大概就是这些：环境准备不充分、网络问题、配置参数错误、磁盘空间权限问题，还有并发编译引发的问题。每一个问题都有对应的解决办法，关键是遇到问题的时候不要慌，仔细看报错信息，善用搜索引擎和官方文档。
如果你在编译过程中遇到了这篇文章没提到的问题，欢迎在开发者社区里提问。很多问题其实大家都遇到过，解决方案大多都能找到。当然，如果你正在使用声网的 SDK，其实可以优先考虑他们提供的技术支持，有些定制化需求或许有更高效的解决方式。
编译环境搭建这件事，确实需要耐心。我当年也是一步步踩坑过来的，现在回头看，那些踩坑的经历反而成了宝贵的经验。希望这篇文章能帮你少走一些弯路。
