Web端实时音视频必须用AgoraRTC（JavaScript SDK），rtc_php仅用于后端生成Token、校验AppID等，不处理音视频流；Token需PHP签发且与前端UID严格一致，同时需正确配置CORS和WebRTC初始化流程。
Web端根本不能直接用 rtc_php
PHP 是服务端语言，rtc_php 只是 Agora 提供的服务器端 SDK，用来做鉴权、查询频道状态、管理录制等后台任务，**不处理任何音视频流**。Web 页面要跑实时音视频，必须靠浏览器原生支持的 WebRTC —— 这和 PHP 没有直接关系。
常见错误现象：require 'AgoraRtcEngine.php' 后在 HTML 里调 joinChannel，控制台报 ReferenceError: AgoraRTC is not defined 或白屏无反应。
- Web 端真正要用的是
AgoraRTC（JavaScript SDK），从https://cdn.agora.io/sdk/release/AgoraRTC_N-4.19.0.js这类 CDN 引入 -
rtc_php的作用仅限于后端：生成 Token、校验 AppID、回调通知解析（如录制完成事件） - 如果跳过 Token 验证直接用临时 Token 或空 Token，在生产环境会立刻被 Agora 拒绝连接，错误信息类似
ERR_INVALID_TOKEN
Token 必须由 PHP 后端签发，且有效期要合理
Web SDK 加入频道前必须传一个有效 Token，它不是永久凭证，也不能前端拼接。PHP 这边得用 rtc_php 的 AccessToken 类生成，否则前端连不上。
使用场景：用户点击“开始通话”时，前端先 fetch('/api/generate-token.php?channel=room123&uid=456')，拿到 Token 后再传给 AgoraRTC.createClient。
立即学习“PHP免费学习笔记（深入）”；
- Token 过期时间建议设为 24 小时以内（
$token->addPrivilege(AgoraTokenBuilder::PRIVILEGE_JOIN_CHANNEL, 86400)），太长有安全风险，太短导致通话中途断连 - UID 在 PHP 签发时必须和前端
joinChannel传的 UID 完全一致，类型也要匹配（整数就传整数，字符串就传字符串），否则报ERR_INVALID_UID - App ID 和 App Certificate 必须从 Agora 控制台复制，注意别把测试环境的证书误用于线上
PHP 后端需正确响应跨域请求，否则前端 fetch 被拦截
前端 JS 调用 PHP 接口拿 Token 时，浏览器会先发 OPTIONS 预检请求。如果 PHP 没返回正确的 CORS 头，fetch 直接失败，控制台显示 Blocked by CORS policy。
实操建议：在生成 Token 的 PHP 文件开头加这几行：
header('Access-Control-Allow-Origin: https://your-web-domain.com');
header('Access-Control-Allow-Methods: GET, OPTIONS');
header('Access-Control-Allow-Headers: Content-Type');
if ($_SERVER['REQUEST_METHOD'] === 'OPTIONS') {
exit;
}
- 不要用
*通配 Origin，Agora Web SDK 在需要发送 Cookie 或认证头时会拒绝* - 如果前端走 HTTP（非 HTTPS），Origin 必须写成
http://localhost:3000这类明确地址，浏览器不认http://* - 确保 PHP 没开启
output_buffering导致 header 发送失败，可加ob_end_clean()前置清理
Web 端初始化失败的三个高频原因
即使 PHP 端 Token 正确、CORS 放行，Web 页面仍可能黑屏/无声/卡在 loading。问题通常不在 PHP，而在前端 JS 的调用链上。
-
AgoraRTC初始化必须等document.readyState === 'complete'或放在<script defer>里，否则AgoraRTC.createClient报undefined - 调用
client.join前没检查浏览器是否支持 WebRTC：if (!AgoraRTC.checkSystemRequirements()) { alert('不支持音视频'); return; } - 本地没麦克风或摄像头权限时，
createMicrophoneAudioTrack或createCameraVideoTrack会 reject，必须用try/catch捕获，不能假设一定能拿到媒体流
复杂点在于：Token 生效、CORS 通过、JS 初始化成功，只是“能连上”的前提；真正看到画面听到声音，还依赖用户设备权限、网络质量、Agora 控制台的项目配置（比如是否开启「强制使用 TLS」）——这些环节任何一个断掉，现象都差不多，但根因完全不同。
