20、日志调试：启用 Chrome 的 --enable-logging 参数，分析 webrtc 日志文件
说实话，做 WebRTC 开发最头疼的是什么？不是代码写不出来，而是出了问题你根本不知道它死在哪。网络通了没？信令发出去没？媒体流有没有建立？这些信息，光靠 console.log 是远远不够的。
我个人习惯，一上来就先开日志。Chrome 的 --enable-logging 参数，说白了就是给浏览器装了个黑匣子。你飞的时候可能感觉不到，但一旦坠机，这玩意儿能帮你还原事故现场。
为什么需要日志调试？
WebRTC 的调用链路很长。从 getUserMedia 获取摄像头，到 createOffer 创建 SDP，再到 ICE 协商、DTLS 握手、SRTP 加密……任何一个环节出问题，表现可能只是「黑屏」或「卡顿」。但原因可能藏在几十个异步回调里。
我记得有一次，用户反馈视频一直黑屏。我查了半天代码，逻辑没问题啊。最后打开日志一看，原来是摄像头被别的应用占用了，getUserMedia 返回了 NotReadableError。console 里只打印了一个模糊的 DOMException，但日志里清清楚楚写着设备冲突。
所以，日志不是万能的，但没有日志是万万不能的。
启用 Chrome 日志的两种方式
嗯，这里要注意，不同系统下操作略有不同。我直接给你总结成表格，省得你翻文档。
| 操作系统 | 命令行示例 | 日志输出位置 |
|---|---|---|
| Windows | chrome.exe --enable-logging --v=1 |
%LOCALAPPDATA%\Google\Chrome\User Data\chrome_debug.log |
| macOS | /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --enable-logging --v=1 |
~/Library/Application Support/Google/Chrome/chrome_debug.log |
| Linux | google-chrome --enable-logging --v=1 |
~/.config/google-chrome/chrome_debug.log |
参数说明：
--enable-logging：开启日志输出，默认是关闭的。--v=1：日志详细级别。0 是最简，1 是推荐，2 以上会刷屏（我一般只用 1）。--vmodule=*/webrtc/*=2：只对 webrtc 模块开启详细日志，其他模块保持安静。这个我强烈推荐，不然日志文件会大到吓人。
alias chromedebug='open -a Google\ Chrome --args --enable-logging --v=1 --vmodule=*/webrtc/*=2'。每次调试直接敲 chromedebug 就行，省得记路径。
日志文件里到底有什么？
你打开 chrome_debug.log，可能会被吓到——密密麻麻全是时间戳和模块名。别慌，我教你抓重点。
WebRTC 相关的日志，通常以 [webrtc] 或 [rtc] 开头。你直接搜索这几个关键字就行。我个人习惯用 grep 或者编辑器里的搜索功能，先过滤出 webrtc 相关的行。
举个例子，这是我从一次成功通话中截取的关键日志片段：
[2025-03-20 10:15:23.456] [webrtc] CreateSessionDescription: type=offer
[2025-03-20 10:15:23.789] [webrtc] SetLocalDescription: type=offer
[2025-03-20 10:15:24.012] [webrtc] ICE: New candidate: 192.168.1.100:54321
[2025-03-20 10:15:24.345] [webrtc] ICE: New candidate: 10.0.0.1:54321 (srflx)
[2025-03-20 10:15:24.678] [webrtc] ICE: New candidate: 2001:db8::1:54321 (relay)
[2025-03-20 10:15:25.001] [webrtc] ICE: Connection state changed: CHECKING -> CONNECTED
[2025-03-20 10:15:25.234] [webrtc] DTLS: Handshake completed
[2025-03-20 10:15:25.567] [webrtc] Media: Video track added: local_track_1
你看，整个流程一目了然：
- 创建了 offer
- 设置了本地描述
- 发现了三个 ICE 候选（本地、NAT、中继）
- ICE 连接建立
- DTLS 握手完成
- 媒体轨道添加成功
如果其中某一步卡住了，比如 ICE 一直处于 CHECKING 状态，那问题大概率出在网络连通性上。我曾经遇到过一个案例，ICE 始终无法从 CHECKING 变成 CONNECTED，日志里反复出现 STUN: request timeout。后来发现是公司的防火墙把 STUN 端口给封了。
常见问题与日志特征
我把平时遇到最多的几种情况整理了一下，你对照着看，能省不少时间。
| 问题现象 | 日志关键字 | 可能原因 |
|---|---|---|
| 黑屏/无视频 | GetUserMedia failed、NotReadableError |
摄像头被占用或权限被拒绝 |
| 连接超时 | ICE: Timeout、STUN: request timeout |
防火墙阻挡了 STUN/TURN 端口 |
| 媒体流卡顿 | Packet loss: 15%、Jitter: 200ms |
网络质量差，丢包率高 |
| 无法建立连接 | DTLS: Handshake failed、Certificate error |
证书问题或 DTLS 版本不匹配 |
| 只有音频没有视频 | Video receive stream: inactive |
远端没有发送视频，或 SDP 中视频被禁用 |
--v=1，并且用 --vmodule 限制模块。不然你的硬盘会报警的。
如何高效分析日志？
直接看原始日志，眼睛会瞎的。我推荐几个工具和方法：
- grep 过滤：
grep "\[webrtc\]" chrome_debug.log > webrtc_only.log，只保留 webrtc 相关行。 - 按时间线排序：日志本身是按时间顺序写的，但如果你合并了多个日志，可以用
sort命令重新排序。 - 关注状态变化：搜索
state changed、failed、error、timeout这些关键词，它们往往是问题的入口。 - 对比成功与失败：我经常做的一件事，是先跑一次成功的通话，把日志存下来。然后复现 bug，再跑一次。用 diff 工具对比两个日志，差异点往往就是问题所在。
为什么会这样？因为成功的日志是一个「基线」，你只要看失败日志里多出了什么、少了什么，就能快速定位。
核心知识体系
下面这张图，是我自己总结的 WebRTC 日志调试流程。你照着这个思路走，基本不会漏掉关键信息。
这张图的核心逻辑是：先拿到日志，再过滤，最后对比。你想想看，如果没有对比，你根本不知道哪些日志是「异常」的。我每次排查问题，都会先跑一遍正常的流程，把日志存下来当「对照组」。
避坑指南
我曾经犯过一个低级错误：在 Windows 上直接双击 Chrome 图标，然后以为日志已经开启了。结果折腾了半天，日志文件里啥也没有。后来才发现，--enable-logging 必须在命令行启动时带上，双击图标是不会加载这些参数的。
还有一次，我忘了加 --v=1，默认的日志级别是 0，只输出 fatal 级别的错误。结果日志文件只有几行，根本看不出问题。嗯，从那以后我每次启动都会检查一下命令行参数。