声网 rtc sdk 示例代码运行教程：从零开始的完整指南
如果你刚刚接触声网的实时音视频开发，可能会觉得官方文档有点摸不着头脑。我当初第一次跑通 SDK 示例的时候也踩了不少坑，今天就把这些经验整理出来，希望能帮你少走一些弯路。这篇教程不会讲太多大道理，咱们直接动手，把示例代码跑起来才是正经事。
一、前期准备工作
在开始运行示例代码之前，有几样东西是必须准备好的。这些准备工作看似简单，但很多人就是卡在某个小环节上耽误半天。
1.1 开发环境要求
不同的开发平台对环境的要求不太一样，我分别说清楚。
| 平台 | 操作系统要求 | 必备软件 | 其他要求 |
| Android | Windows 7+ / macOS 10.14+ / Linux | Android Studio 3.0+、JDK 1.8+ | Gradle 4.6+、支持真机调试 |
| iOS | macOS 10.15+ | Xcode 12.0+ | iOS 12.0+ 真机或模拟器 |
| Windows | Windows 7+ (64位) | Visual Studio 2017+ | DirectX 9.0c 兼容显卡 |
这里有个小提醒，很多人喜欢用虚拟机跑 Android 开发，也不是不行，但涉及到音视频采集和硬件加速的时候，虚拟机会有一些兼容性问题，最好还是用真机调试。另外，苹果的开发者证书和描述文件这个环节卡住了不少人，如果你之前没搞过 iOS 开发，建议提前去 Apple Developer 网站把证书配置好，不然 Xcode 连编译都过不去。
1.2 获取 SDK 和示例代码
声网的 SDK 获取其实很方便，但新手容易找错地方。最直接的方式是去声网的官方网站，在文档中心或者开发者专区能找到最新的 SDK 下载链接。示例代码的话，GitHub 上有官方仓库，名字通常包含 agora-rtc-sdk 这样的关键词。
我建议你直接把整个示例项目克隆下来，而不是只下载 SDK。因为示例项目里不仅有代码，还包括完整的项目配置、依赖管理文件（比如 build.gradle、package.json 这些），新手自己配置环境很容易出错。
git clone https://github.com/agorameeting/Agora-Android-Tutorial-1to1.git
# 或者其他你需要的平台
下载完成之后，先别急着运行，把项目结构搞清楚。每个示例项目里面通常会有一个 README 文件，这个一定要仔细读一遍，开发者会把一些特殊的配置要求写在里面。
二、创建声网开发者账号
这一点我必须单独拿出来说，因为太多人忽略了。声网的 SDK 虽然可以免费下载和使用，但在正式集成之前，你需要去声网官网注册一个开发者账号，然后获取 App ID。没有这个 App ID，SDK 初始化的时候会报错，你连门都进不去。
注册过程很简单，访问声网开发者官网，用邮箱或者手机号注册一个账号就行。注册成功后，登录进去创建一个新项目，系统会自动给你分配一个 App ID。这个 ID 相当于你的"身份证"，每个项目的 ID 都是唯一的。
拿到 App ID 之后，你需要把它填到示例代码里。通常在示例项目的配置文件或者代码文件里，会有一个类似 APP_ID 的常量，把刚才获取到的值替换进去就行。有些示例项目会把这个值放在一个单独的配置类里，找不到的话全局搜索一下 "appId" 或者 "APP_ID" 关键字。
三、分平台运行示例
准备工作做完之后，我们来分别看看各个平台怎么把示例跑起来。我会重点讲 Android 和 Web 平台，因为这两个是新手最常用的。如果你做的是其他平台，思路也是类似的。
3.1 Android 平台运行步骤
Android 平台的示例代码我是最熟悉的，毕竟平时写 Android 开发比较多。
第一步，用 Android Studio 打开刚才下载的项目。打开的时候选择"Open an Existing Project"，然后找到项目根目录下的 build.gradle 文件。Android Studio 会自动识别这是一个 Gradle 项目，然后开始下载依赖。
这里有个潜在的坑：网络问题。因为很多依赖库是从 Maven 中央仓库下载的，国内访问有时候会抽风。如果下载失败，你可以尝试在国内镜像源，或者设置代理。修改项目根目录下的 build.gradle 文件，在 repositories 里面加入国内镜像。
依赖下载完成之后，把手机通过 USB 连到电脑上，确保手机已经开启了开发者模式和 USB 调试。然后在 Android Studio 的设备列表里应该能看到你的手机，选中它，点击运行按钮。
如果一切正常，大概十几秒之后应用就会安装到手机上并自动启动。首次启动可能会请求相机和麦克风权限，一定要允许，不然没法进行音视频通话。同意权限之后，你会看到示例应用的主界面，通常会有一个"开始通话"或者"加入频道"的按钮，点击它就能进入通话了。
这时候你可能会发现只有自己一个人——那是因为你还没有让另一个人加入同一个频道。示例代码里通常会有说明，告诉你是用同一个 App ID 在另一台设备上也运行这个应用，或者使用声网提供的测试工具。两个人都进入同一个频道之后，就能看到对方的视频画面了。
3.2 iOS 平台运行步骤
iOS 的流程和 Android 有些不一样，主要是因为 Xcode 的限制。
首先把下载下来的示例项目解压，用 Xcode 打开 .xcodeproj 文件。打开之后，在左侧的项目导航栏里找到配置文件，通常是 Info.plist，你需要在这里添加相机和麦克风的使用描述。苹果的隐私政策比较严格，如果不写清楚为什么需要这些权限，应用是没法调用硬件的。
找到 Info.plist 文件，添加下面这些内容：
- NSCameraUsageDescription - 需要访问相机进行视频通话
- NSMicrophoneUsageDescription - 需要访问麦克风进行语音通话
添加完之后，把你的 iPhone 通过数据线连到 Mac 上，在 Xcode 的设备列表里选择你的设备，然后点击运行按钮。和 Android 不一样的是，iOS 应用必须使用真机调试，模拟器虽然也能运行，但很多音视频相关的功能在模拟器上是没法正常工作的。
第一次在真机上运行的时候，Xcode 会要求你登录 Apple ID 并配置证书。如果只是开发调试的话，用免费的 Apple ID 就行，但如果要测试推送通知或者后台运行这些功能，就需要付费的开发者账号了。
3.3 Web 平台运行步骤
Web 平台可能是最简单的，因为不需要安装任何东西，只要有个浏览器就能跑。
示例代码下载下来之后，直接用浏览器打开 index.html 文件就行。但这里有个问题：浏览器的安全策略限制，Web 应用调用摄像头和麦克风必须在服务器环境下，直接打开本地文件可能没法正常工作。
最省事的办法是用 VS Code 的 Live Server 插件，或者直接用 Python 启动一个简单的 HTTP 服务器。在项目根目录下打开终端，输入：
python -m http.server 8080
然后在浏览器里访问 http://localhost:8080 就能看到页面了。点击"加入频道"按钮，浏览器会弹出一个授权请求让你允许访问摄像头和麦克风，点同意之后就进入通话页面了。
Web 平台有个好处是调试特别方便，你可以直接按 F12 打开开发者工具，看控制台的日志输出，这对排查问题很有帮助。
四、常见问题和排查方法
即使你严格按照上面的步骤来，也可能会遇到一些问题。我把最常见的问题和排查方法列出来，希望能帮到你。
4.1 初始化失败
如果 SDK 初始化失败，首先检查 App ID 是不是填错了。App ID 是一串很长的字符串，很容易复制错。确认 App ID 没问题的话，看看网络连接，初始化需要访问声网的服务器，网络不通肯定是不行的。
还有一种可能是 SDK 版本和示例代码不匹配。声网会经常更新 SDK，如果你的示例代码是很久以前下载的，可能需要更新到最新版本。查看一下项目里依赖的 SDK 版本号，去声网官网下载对应版本的 SDK 替换进去。
4.2 加入频道失败
加入频道失败的原因有很多，最常见的是网络问题。检查一下你的网络连接，可以试试访问其他网站看看是否正常。如果网络没问题，看看防火墙是不是把声网的服务器地址给拦截了。声网的服务器地址在文档里有列出来，你需要在防火墙里把这些地址加入白名单。
另一个可能是频道名称不对。两个人要加入同一个频道，频道名称必须完全一致，包括大小写。建议在测试的时候用简单的字母数字组合，避免特殊字符。
4.3 看不到对方视频
这个问题通常是两端的状态不一致造成的。先检查两端是不是真的进入了同一个频道，可以在界面上显示一下当前频道名称和用户 ID，确认一致之后，再看视频渲染的逻辑。
有些示例代码默认是不自动渲染视频的，需要调用特定的 API 才能看到画面。翻一下示例代码里的注释或者 README 文件，看看是不是需要手动触发视频渲染。
还有一种情况是浏览器或者系统的隐私设置禁止了摄像头访问。检查一下浏览器的设置，确保没有禁用摄像头和麦克风。如果是 iOS Safari 的话，要注意苹果对某些 API 的限制可能和其他浏览器不一样。
五、跑通之后的下一步
恭喜你成功把示例代码跑起来了！但这只是一个开始，示例代码只是展示了最基础的功能，真正的开发工作还在后面。
我建议你在跑通示例之后，尝试做一些小改动来加深理解。比如把视频分辨率改一改，看看画面质量有什么变化；或者加入美颜功能，这个在声网的 SDK 里是有现成支持的。动手改一改代码，比只看文档学得快得多。
如果你在做特定场景的开发，比如直播、社交、视频会议之类的，可以去声网的文档中心找对应的场景化文档。那些文档会针对不同场景给出最佳实践和代码示例，比自己摸索效率高很多。
最后我想说，音视频开发这个领域水很深，刚入门的时候遇到问题太正常了。多看看官方文档，多逛逛开发者社区，遇到问题先搜一搜，大部分情况下你遇到的问题别人也遇到过。声网的文档和社区做得还是不错的，遇到问题基本上都能找到答案。
祝你开发顺利，有问题随时来交流。
