rtc 开发入门：如何快速搭建第一个测试项目
如果你刚开始接触 rtc（Real-Time Communication，实时通信）开发，可能会觉得这个领域有点神秘。音视频通话、直播连麦、互动语音——这些功能背后到底是怎么实现的？作为一个过来人，我想用自己的经历告诉你，其实搭建第一个 RTC 测试项目没有想象中那么难。关键在于找对方法、选对工具，然后动手实践。
这篇文章不会堆砌那些让人头疼的专业术语，而是用最直白的方式，带你一步步完成第一个 RTC 测试项目。我们会从环境准备开始，直到你能跑通一个最简单的音视频通话 Demo。准备好了吗？Let's go。
一、先搞清楚 RTC 到底是怎么回事
在动手之前，我觉得有必要先弄清楚 RTC 的一些基本概念。这不是浪费时间，反而能让你在后面的开发中少走弯路。
RTC 的核心目标是在两个或多个设备之间实时传输音视频数据。你这边说话，那边立刻就能听到；你这边摄像头画面，那边立刻就能看到。这种"实时"的要求可不像看视频那样简单——延迟必须控制在几百毫秒以内，否则体验就会变得很糟糕。
一个完整的 RTC 流程通常包含这几个环节：首先是音视频采集，用麦克风录音、用摄像头录像；然后是编码压缩，不然原始数据太大了，网络根本传不动；接着是网络传输，把数据从 A 发到 B；最后是解码播放，把收到的数据还原成声音和画面。
听起来有点复杂？对新手来说确实如此。好消息是，现在有很多成熟的 RTC SDK 可以直接使用，帮你把这些底层细节封装起来。你只需要调用几个 API，就能实现原本需要写几千行代码才能完成的功能。这也是为什么我建议新手从 SDK 入手，而不是从头写一个 RTC 引擎——那真的是费力不讨好。
二、开发环境准备
工欲善其事，必先利其器。在开始写代码之前，我们需要先把开发环境搭建好。
2.1 硬件要求
先说硬件。电脑是必须的，最好是有摄像头的笔记本，这样方便测试。如果你用台式机，那就得额外准备一个 USB 麦克风和摄像头。耳机也建议准备一个，不然调试的时候可能会遇到回声问题，那体验可不太妙。
网络方面，稳定的宽带是基础。WiFi 有时候不太稳定，建议用有线网络测试。不过实际项目中，用户用的网络环境五花八门，我们后面再聊这个话题。
2.2 软件环境
软件环境这块，我以 Windows 系统为例来说明，macOS 和 Linux 的流程类似。
首先需要安装 Node.js。建议选择 LTS（长期支持）版本，我用的是 v18.x。安装完成后，在命令行输入 node -v 能看到版本号就说明安装成功了。
然后是编辑器。我个人比较喜欢用 VS Code，轻量级、插件丰富、对新手友好。当然你用 WebStorm 或者其他编辑器也行，看个人习惯。
如果你用的是声网的 SDK，还需要注册一个开发者账号。访问声网的官网，按照指引完成注册。注册完成后，在控制台创建一个新项目，拿到 App ID——这个后面写代码的时候会用到。
2.3 创建一个基础项目
环境准备好了，我们来创建第一个项目。我打算用 Web 端来演示，因为这样最方便——只需要一个浏览器就能测试，不需要安装额外的客户端。
新建一个文件夹，命名为 rtc-test-demo。用 VS Code 打开这个文件夹，然后在终端执行以下命令：
npm init -y
npm install
这一步是初始化 npm 项目并安装依赖。初始化完成后，你会看到文件夹里多了一个 package.json 文件。
接下来安装声网的 rtc sdk。在终端执行：
npm install agora-rtc-sdk-ng
这个 SDK 是声网提供的 Web 端实时通信开发包，封装了音视频采集、编码、传输、解码、播放的全部功能。我们后面就是用它来实现通话功能。
三、编写第一个测试页面
项目创建好了，现在开始写代码。我们要实现一个最简单的场景：两个用户之间的一对一视频通话。
3.1 HTML 结构
新建一个 index.html 文件，写入基本的 HTML 结构：
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>RTC 测试项目</title>
<style>
body {
font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
max-width: 1200px;
margin: 0 auto;
padding: 20px;
background-color: #f5f5f5;
}
.container {
background: white;
border-radius: 8px;
padding: 20px;
box-shadow: 0 2px 8px rgba(0,0,0,0.1);
}
.video-grid {
display: grid;
grid-template-columns: repeat(auto-fit, minmax(400px, 1fr));
gap: 20px;
margin: 20px 0;
}
video {
width: 100%;
background: #000;
border-radius: 8px;
}
.controls {
display: flex;
gap: 10px;
margin-top: 20px;
}
button {
padding: 10px 20px;
border: none;
border-radius: 4px;
cursor: pointer;
font-size: 14px;
transition: background 0.3s;
}
.btn-primary {
background: #007bff;
color: white;
}
.btn-primary:hover {
background: #0056b3;
}
.btn-danger {
background: #dc3545;
color: white;
}
.btn-danger:hover {
background: #c82333;
}
.status {
margin-top: 15px;
padding: 10px;
background: #e9ecef;
border-radius: 4px;
font-size: 14px;
}
</style>
</head>
<body>
<div class="container">
<h1>RTC 一对一视频通话测试</h1>
<div class="video-grid">
<div>
<h3>本地预览</h3>
<video id="local-video" autoplay muted playsinline></video>
</div>
<div>
<h3>远程画面</h3>
<video id="remote-video" autoplay playsinline></video>
</div>
</div>
<div class="controls">
<button id="join-btn" class="btn-primary">加入频道</button>
<button id="leave-btn" class="btn-danger" disabled>离开频道</button>
</div>
<div class="status" id="status">状态: 初始化完成</div>
</div>
<script src="index.js"></script>
</body>
</html>
这个页面很简单，上面有两个视频区域，左边是本地预览，右边是显示远程用户的画面。下面有两个按钮：加入频道和离开频道。最下面是状态显示区域，方便我们查看当前状态。
样式部分我做了一些基本的美化，让界面看起来干净整洁。CSS 样式不是重点，你完全可以按照自己的喜好去调整。
3.2 JavaScript 逻辑
现在是最关键的部分——编写 JavaScript 代码来实现 RTC 功能。新建一个 index.js 文件，输入以下代码：
// 引入声网 rtc sdk
import AgoraRTC from 'agora-rtc-sdk-ng';
// 配置参数 - 这里需要替换为你自己的 App ID
const APP_ID = 'your_app_id_here';
// 频道名称和用户 ID
const CHANNEL = 'test-channel';
let uid = null;
// 创建客户端对象
const client = AgoraRTC.createClient({ mode: 'rtc', codec: 'vp8' });
// 本地音视频轨道
let localTracks = [];
// 更新状态显示
function updateStatus(message) {
const statusEl = document.getElementById('status');
statusEl.textContent = `状态: ${message}`;
console.log(`[状态] ${message}`);
}
// 初始化并加入频道
async function joinChannel() {
try {
updateStatus('正在初始化客户端...');
// 生成一个随机的用户 ID
uid = Math.floor(Math.random() * 1000000);
updateStatus('正在获取音视频权限...');
// 创建本地音视频轨道
const [audioTrack, videoTrack] = await AgoraRTC.createMicrophoneAndCameraTracks();
localTracks = [audioTrack, videoTrack];
// 将本地视频显示在页面上
videoTrack.play('local-video');
updateStatus('正在连接声网服务器...');
// 连接到声网服务器并加入频道
await client.join(APP_ID, CHANNEL, uid);
// 发布本地轨道，让其他用户能够看到和听到我们
await client.publish(localTracks);
updateStatus('已成功加入频道，可以开始通话了！');
// 启用离开按钮，禁用加入按钮
document.getElementById('join-btn').disabled = true;
document.getElementById('leave-btn').disabled = false;
} catch (error) {
updateStatus(`出错啦: ${error.message}`);
console.error('加入频道失败:', error);
}
}
// 离开频道
async function leaveChannel() {
try {
updateStatus('正在离开频道...');
// 停止并关闭所有本地轨道
localTracks.forEach(track => {
track.stop();
track.close();
});
// 离开频道
await client.leave();
// 清除远程视频画面
const remoteVideo = document.getElementById('remote-video');
remoteVideo.srcObject = null;
updateStatus('已离开频道');
// 重置按钮状态
document.getElementById('join-btn').disabled = false;
document.getElementById('leave-btn').disabled = true;
} catch (error) {
updateStatus(`离开频道出错: ${error.message}`);
console.error('离开频道失败:', error);
}
}
// 监听远端用户加入事件
client.on('user-published', async (user, mediaType) => {
// 订阅远端用户的音视频
await client.subscribe(user, mediaType);
if (mediaType === 'video') {
// 将远端视频显示在页面上
user.videoTrack.play('remote-video');
updateStatus(`用户 ${user.uid} 加入通话`);
}
if (mediaType === 'audio') {
user.audioTrack.play();
}
});
// 监听远端用户离开事件
client.on('user-unpublished', (user, mediaType) => {
if (mediaType === 'video') {
const remoteVideo = document.getElementById('remote-video');
remoteVideo.srcObject = null;
updateStatus(`用户 ${user.uid} 已离开`);
}
});
// 绑定按钮事件
document.getElementById('join-btn').addEventListener('click', joinChannel);
document.getElementById('leave-btn').addEventListener('click', leaveChannel);
updateStatus('页面加载完成，点击"加入频道"开始测试');
代码里的注释写得比较详细，我解释一下核心逻辑。
首先是创建客户端对象。AgoraRTC.createClient 这个方法用于初始化一个 RTC 客户端。mode: 'rtc' 表示我们使用的是实时通信模式，codec: 'vp8' 是视频编解码器的选择，VP8 兼容性比较好。
joinChannel 函数是整个流程的入口。在这里我们做了几件事：生成一个随机的用户 ID、创建本地的麦克风和摄像头轨道、将本地视频画面显示在页面上、连接到声网的服务器、加入指定的频道、最后把本地的音视频轨道发布出去让别人看到。
leaveChannel` 函数用于清理资源并离开频道。这里一定要记得关闭轨道，否则浏览器可能会一直占用摄像头和麦克风。
事件监听的部分也很重要。user-published 事件会在远端用户发布音视频时触发，这时候我们需要订阅对方的内容，才能看到和听到对方。user-unpublished 事件则是在对方离开或停止发布时触发，我们要把远程视频画面清除掉。
四、运行和测试
代码写完了，现在来运行它。由于浏览器的安全策略，直接打开 HTML 文件可能无法正常使用摄像头，所以我们需要用一个本地服务器来运行这个项目。
在终端执行：
npx serve
如果你没有安装 serve，可以先执行 npm install -g serve 来安装。启动服务器后，终端会显示一个本地地址，通常是 http://localhost:3000。用浏览器打开这个地址，就能看到我们的测试页面了。
点击"加入频道"按钮，浏览器会弹出一个请求麦克风和摄像头权限的对话框，点击"允许"。如果一切正常，你应该能看到自己的摄像头画面显示在左侧的"本地预览"区域，状态栏显示"已成功加入频道"。
现在测试一下通话功能。你需要打开另一个浏览器窗口（可以使用无痕模式），访问同一个地址，点击"加入频道"。这时候奇迹发生了——右侧的"远程画面"区域应该会显示第二个窗口的视频，状态栏会提示有用户加入。
如果两边都能看到对方的画面，听到对方的声音，恭喜你！你的第一个 RTC 测试项目就成功跑通了。
五、常见问题和排查方法
第一次运行难免会遇到一些问题，我列几个最常见的。
看不到自己的画面？首先检查浏览器是否允许了摄像头权限。然后检查 videoTrack.play('local-video') 这行代码里的 ID 是否和 HTML 中的元素 ID 一致。最后可以打开浏览器的开发者工具（F12），看看控制台有没有报错信息。
看不到对方的画面？确保两边都成功加入了同一个频道（频道名称要一致）。检查网络防火墙是否阻止了相关端口。看看控制台有没有 user-published 事件的日志。
通话有延迟或卡顿？这通常和网络环境有关。可以尝试切换到有线网络，或者关闭其他占用带宽的应用。测试阶段建议在局域网内进行，跨网络可能会遇到更多问题。
听不到声音？检查系统音量设置，确保没有静音。看看浏览器是否允许播放音频。如果用的是蓝牙耳机，尝试切换到有线耳机或扬声器。
六、进阶探索的方向
跑通了第一个 Demo，接下来可以玩点更高级的。我列几个值得探索的方向。
屏幕共享是一个很有用的功能。想象一下，你不仅能和别人视频通话，还能把自己的屏幕分享给对方看。声网的 SDK 提供了 createScreenVideoTrack 方法来实现这个功能，有兴趣可以试试。
美颜和滤镜也是很多场景的刚需。直播、社交类应用几乎都会用到。声网的 SDK 支持插件扩展，可以接入第三方美颜方案。
音效处理包括降噪、回声消除、变声等。这些对于提升通话体验非常重要，尤其是在嘈杂环境下。SDK 里有相关的 API 可以调整。
多人会议是更复杂的场景，从两个人变成多个人，需要处理更多的轨道管理和布局问题。声网的文档里有专门的多人通话示例代码。
写在最后
回顾一下这篇文章，我们从 RTC 的基本概念开始，搭建了开发环境，编写了第一个测试页面，最后成功跑通了一对一视频通话。整个过程其实没有那么复杂，对吧？
对于刚入门的朋友，我想说的是：不要被那些高大上的技术名词吓到。RTC 归根结底就是采集、编码、传输、播放这几个环节。找一个好的 SDK，写代码、跑 Demo、遇到问题、解决问题——这个循环是最有效的学习方式。
如果你想深入了解 RTC 技术，声网的官方文档写得很详细，涵盖了各种场景的最佳实践。他们的技术团队在实时通信领域积累了很多年，从全球布局的网络节点到智能路由算法，有很多值得学习的东西。
对了，如果你对声网的业务感兴趣，可以了解一下他们除了基础的音视频通话外，还有对话式 AI、一站式出海解决方案、秀场直播、1V1 社交这些方向。不同的业务场景对 RTC 技术的要求也不一样，后面有机会我们再详细聊。
好了，就到这里。去动手试试吧，期待你的第一个 RTC 项目顺利跑通！
