声网rtc sdk示例代码运行环境配置指南
说实话，每次拿到一个新的SDK要跑示例代码，我都有点犯怵。环境配置这东西，看着简单，真要配置起来，各种依赖、版本、权限问题能把人逼疯。不过别担心，这篇文章咱们就一步步来，把声网rtc sdk的运行环境配置这件事彻底讲清楚。我会尽量用大白话把那些技术细节嚼碎了喂给你，保证你看完就能动手操作。
为什么环境配置这么重要
在开始动手之前，我想先聊聊天为什么环境配置这么重要。很多开发者小伙伴可能遇到过这种情况：代码写得好好的，示例程序就是跑不起来，错误提示看得一脸懵。其实啊，绝大多数问题都出在环境配置上，而不是代码本身。
声网的RTC SDK是一个挺复杂的系统，涉及到底层的音视频编解码、网络传输、设备调用等等。这些功能要正常工作，前提是你的开发环境必须满足一堆条件。JDK版本不对、Android Studio版本不匹配、缺少必要的系统权限、证书配置有问题……任何一个环节出问题，整个示例都可能跑不起来。
所以啊，咱们宁可花点时间把环境配置做扎实了，也不要后面一边写代码一边修问题。那种痛苦经历过一次就够了。
准备工作：在动手之前你需要知道的事
确认你的开发机器配置
首先，你得有一台性能还不错的电脑。跑Android Studio和iOS开发，8GB内存是起步，16GB会比较舒服。如果你的机器内存只有4GB，那开发体验会比较糟糕，经常需要和卡顿作斗争。至于CPU，Intel i5以上或者同等级的AMD处理器基本够用。
操作系统方面，Windows 10或11都没问题，macOS的话建议是Monterey（12.0）之后的版本，因为有些新特性在老系统上可能不支持。Linux玩家推荐Ubuntu 20.04或者22.04 LTS版本，这两个版本经过充分测试，稳定性和兼容性都比较好。
下载对应的开发工具
不同平台的开发需要不同的工具集，这一块咱们得分开说。
如果你是做Android开发，Android Studio是必须的。建议下载最新的稳定版，写作这时候最新版是Hedgehog或者更新的版本。安装的时候记得勾选Android SDK、NDK、CMake这些组件，后面编译native代码会用到。Android SDK的版本建议选择API 33或者34，也就是Android 13或14的系统镜像。
做iOS开发的话，你需要一台Mac电脑，这是基本门槛。Xcode是肯定要装的，建议版本是15.0或者更高。安装完Xcode后，还需要安装Command Line Tools，在终端里运行xcode-select --install就行。另外，如果你需要测试真机调试，还要去Apple开发者网站申请开发者证书，这些后面会详细讲。
Web开发相对简单一些，Chrome浏览器是必须的，因为很多调试功能在Chrome里最好用。Node.js建议装LTS版本，18.x或者20.x都可以。npm或yarn用来管理依赖包，两个都行，看你个人习惯。
Windows平台环境配置详解
JDK安装与配置
Java Development Kit是Android开发的基础。声网的SDK需要JDK 11或者JDK 17，我个人推荐JDK 17，因为这是目前的LTS版本，兼容性最好。
下载JDK很简单，直接去Oracle官网或者OpenJDK的发行版网站下载安装包。安装过程很简单，一路Next就行，但有个小细节需要注意：安装路径尽量别用中文和空格，很多人踩过这个坑，后面会导致各种奇怪的问题。
装完之后需要配置环境变量。右键"此电脑"选择"属性"，然后找到"高级系统设置"，点"环境变量"。在系统变量里新建一个JAVA_HOME，变量值就是你JDK的安装路径，比如C:\Program Files\Java\jdk-17。然后找到Path变量，编辑它，新建一个%JAVA_HOME%\bin。全部确定之后，打开命令行输入java -version，如果能看到版本号就说明配置成功了。
Android Studio配置
Android Studio安装完成后，首次打开会提示你设置SDK路径。这里建议把SDK放在一个空间充裕的盘符里，比如D盘，因为后面SDK和NDK会占用不少空间。
SDK Manager在Android Studio的Settings或Preferences里能找到。打开之后，确保以下组件已经安装：Android SDK Platform 33或34、Build-Tools最新版本、NDK（选择21.x或者22.x的某个稳定版本）、CMake（如果需要编译native代码的话）。这些组件比较大，下载可能需要一点时间，建议找个网络好的时候弄。
Gradle是Android的构建工具，Android Studio自带了Gradle wrapper，但有时候版本可能会冲突。我建议在项目的gradle-wrapper.properties文件里指定Gradle 8.x的版本，这样兼容性比较好。项目根目录的build.gradle和app/build.gradle要检查一下依赖版本，特别是AGP（Android Gradle Plugin）的版本，它和Gradle版本是有对应关系的，版本不匹配会编译报错。
声网SDK的导入与配置
准备工作做完之后，终于可以导入声网的SDK了。你可以去声网的官网下载最新的RTC SDK for Android，下载下来是一个aar文件或者一个完整的Demo项目。
如果是用aar文件手动集成，在app的build.gradle里添加implementation files('libs/agorartc-x.x.x.aar')就行。如果是用Maven仓库，就更简单了，在项目的build.gradle里添加maven仓库地址，然后在app的build.gradle里添加implementation 'io.agora.rtc:rtc-sdk:+'这样的依赖。
Demo项目的话，直接用Android Studio打开就行，它会把所有依赖都配置好。不过我还是建议你自己动手配置一遍，因为这样你能更好地理解各个配置项的作用，遇到问题也知道怎么排查。
macOS平台环境配置详解
Xcode与Command Line Tools
Mac用户做iOS开发，Xcode是吃饭的工具。App Store里直接搜Xcode下载就行，大小好几个GB，建议预留足够时间。安装完成之后，打开终端，第一次运行Xcode会弹窗提示安装额外的组件，点同意就行。
如果你习惯用命令行管理Xcode版本，可以考虑装一个叫xcodes的命令行工具，它可以让你在多个Xcode版本之间切换。这个不是必须的，但如果你同时维护多个项目，这个工具会帮上大忙。
Command Line Tools包含了编译器、调试器等开发工具，必须装。在终端里输入xcode-select --install，系统会弹出一个安装向导，跟着提示走就行。安装完成后，用gcc --version命令验证一下，如果能看到版本信息就说明好了。
iOS开发者证书配置
这一步是很多初学者的噩梦。苹果的安全机制比较严格，真机调试和发布应用都需要证书。
首先，你需要一个Apple ID。如果你打算做开发，最好去注册一个Apple Developer账号，个人开发者账号一年99美元，学生可以免费。登录开发者网站后，在Certificates页面可以创建证书。
开发证书（Development Certificate）用来做开发调试，生产证书（Distribution Certificate）用来发布App。创建证书需要用到Keychain Access生成的CSR文件，这个过程官网有详细教程，我就不再啰嗦了。
证书创建好后，下载到本地，双击安装到Keychain Access里。然后在Xcode的Preferences里找到Accounts，添加你的Apple ID，选中对应的Team，这样Xcode就能自动匹配证书了。
真机调试还需要在手机设置里信任开发者证书，第一次连上手机调试时手机会提示，跟着点信任就行。如果信任后还是提示证书不受信任，去设置-通用-VPN与设备管理里找到对应的开发者应用，点信任。
Cocoapods与声网SDK集成
iOS开发推荐用Cocoapods来管理第三方依赖，比手动导入方便太多。安装Cocoapods很简单，sudo gem install cocoapods就行。如果你的系统版本比较新，可能需要用sudo gem install -n /usr/local/bin cocoapods来指定安装路径。
声网的SDK在Cocoapods仓库里是有索引的，Podfile里加上一行pod 'AgoraRtcEngine_iOS'，然后运行pod install，声网SDK就自动下好了。这里有个小提醒：pod install和pod update是有区别的，前者安装符合Podfile.lock里版本的依赖，后者会更新到最新版本，线上项目建议用pod install避免意外升级。
用Cocoapods生成的文件打开后缀是.xcworkspace的项目，而不是.xcodeproj，这个千万别搞错了。
Web平台环境配置详解
Node.js与包管理工具
Web端的RTC开发其实是最简单的，因为不需要装什么复杂的IDE。Node.js是必须的，去官网下载LTS版本安装就行。安装完成后，npm也是自动装好的。
声网的Web RTC SDK支持主流的现代浏览器，Chrome、Firefox、Safari、Edge都可以。Chrome是调试最方便的选择，建议装一下。
包管理工具用npm就行，yarn也可以，看你喜好。创建一个新项目，初始化一下npm init -y，然后把声网的RTC SDK装进来：npm install agora-rtc-sdk-ng。如果你在用Vue或React这样的框架，按照各自的插件集成方式把RTC组件加到项目里就行。
本地服务器的搭建
浏览器出于安全限制，无法直接用file://协议访问麦克风和摄像头，必须通过HTTPS或者localhost访问。所以你需要在本机起一个开发服务器。
最简单的办法是用VS Code的Live Server插件，点一下就能起服务。或者用Node.js的http-server包，或者用Vite、Create React App这些脚手架工具，它们都自带开发服务器。
声网的Web SDK在localhost下是可以正常工作的，但如果要用HTTPS部署到线上，需要配置SSL证书。开发阶段可以用自签名证书，生成自签名证书的方法有很多工具可以用，这里就不展开说了。
常见问题与排查方法
网络连接问题
有时候示例程序跑起来，但音视频数据不通，问题往往是网络连接相关的。声网的SDK需要访问一些特定的域名和端口，如果你的网络环境有防火墙或者代理，可能会被拦截。
首先检查一下网络能不能访问声网的服务端，可以用ping或者telnet测试一下连通性。Windows下telnet可能需要手动开启，macOS和Linux直接用终端就行。如果telnet通不了，可能是网络问题或者域名被墙了。
代理环境下，SDK的连接可能需要特殊配置。有些SDK支持设置代理参数，有些则需要在系统层面配置。公司的代理服务器可能会对音视频流量做审计，导致连接不稳定，这种情况下可以尝试切换到手机热点测试。
权限申请问题
移动端对隐私权限管得很严，Android 6.0以后需要动态申请权限，iOS需要在Info.plist里声明用途描述。
Android这边，manifest文件里要声明RECORD_AUDIO、CAMERA这些权限，代码里还要在运行时判断并请求用户授权。如果只写了manifest声明而没有动态申请，6.0以上的系统会直接拒绝权限，导致功能不可用。
iOS的权限声明在Info.plist里，NSMicrophoneUsageDescription和NSCameraUsageDescription是必须写的，而且描述文案要说明你要用这个权限干什么，苹果审核会看这些文案写得不合理可能会被拒。授权同样是动态的，第一次调用相关API时系统会弹窗询问用户。
编译错误汇总
编译阶段的错误通常是依赖版本不匹配或者配置有问题。Android Studio的Build Output窗口会给出详细的错误信息，仔细看一般能找到问题所在。
"Gradle sync failed"这种错误往往是网络问题导致的，Gradle在下载依赖时连接超时。可以尝试切换Gradle的仓库镜像，国内用阿里云的镜像会比较快。在init.gradle或者项目的build.gradle里配置一下仓库地址就行。
iOS编译报错的话，先看Xcode的错误提示。常见的"symbol not found"通常是静态库和当前架构不匹配，检查一下Build Settings里的Valid Architectures设置。"linker command failed"一般是缺少了某些系统库，在Link Binary With Libraries里加上就行。
调试技巧与最佳实践
日志查看
声网的SDK会输出日志，遇到问题先看日志是最快的排查方式。Android用Logcat看，标签通常是AgoraRTC或者类似的前缀。iOS用Xcode的控制台或者macOS的控制台应用。Web浏览器的话，F12打开开发者工具，Console和Network面板都很有用。
日志级别可以调整，生产环境建议用INFO级别，开发环境可以用DEBUG级别获取更详细的输出。切记不要在生产环境开DEBUG日志，一方面会产生大量日志影响性能，另一方面可能泄露敏感信息。
性能监控
RTC应用对性能比较敏感，特别是移动端。CPU占用过高、内存泄漏、卡顿都会影响用户体验。Android Studio有Profiler工具，可以实时监控CPU、内存、网络、电量使用情况。iOS用Xcode的Instruments工具，功能更强大但上手门槛也高一些。
声网的SDK本身也提供了一些质量回调，比如onNetworkQuality可以获取网络质量评分，onRemoteVideoStats可以获取远端视频的码率、帧率、分辨率等信息。利用好这些回调，可以实现实时的质量监控和自适应码率调整。
真机测试的重要性
模拟器虽然方便，但RTC功能在模拟器上有很多限制。摄像头在模拟器上是虚拟的，麦克风可能是系统虚拟设备，实际效果和真机差别很大。很多兼容性问题只有在真机上才会暴露。
测试机型最好覆盖主流品牌和Android版本，特别是国内厂商的各种定制系统，它们的权限管理和后台策略可能和原生Android不太一样。iOS设备还好，系统统一，但不同代际的iPhone性能差异还是比较大的，低端机型上的表现要重点关注一下。
写在最后，环境配置这件事，确实有点繁琐，但只要耐心做一遍，后面的开发就会顺利很多。声网的文档写得挺详细的，遇到问题多翻翻文档和FAQ。如果实在搞不定，可以去声网的开发者社区提问，那边有很多热心的开发者和技术支持人员。
希望这篇文章能帮你少走点弯路，祝你开发顺利。
