adb录屏全流程详解：从命令参数到自动化脚本集成

安卓设备调试这个环节录屏需求出现的频率其实一直不低。不管是给bug单配一段可复现的视频还是记录某个复杂手势操作的完整路径直接在命令行工具里发起录屏往往比在手机屏幕上手动按录制更可控也更容易嵌入自动化流程。adb自带的screenrecord命令从Android 4.4时代就开始内置了不需要额外装App不占用手机前台资源能在电脑上直接指定分辨率、码率和时长录完一刀把文件拉回本地链路短、效率高是我日常调试和测试时最常用的方案之一。这篇内容围绕adb录屏从环境准备到脚本集成的全流程展开把命令参数怎么选、时长限制怎么绕、大文件怎么处理、日志和画面怎么对齐这些实操点都过一遍。刚接触命令行工具的新人可以照着一步步来经常做自动化测试或者在持续集成环境里收集构建附件的开发者也能从里面的脚本思路里找到能直接复用的东西。我不会绕弯子直接讲有用的。1. 为什么优先选择adb自带录屏能力1.1 和手机自带录屏的差别在哪里很多人一开始会问手机系统明明自带录屏为什么还要用命令行我的回答是自带录屏按钮是给普通用户用的不是给调试场景用的。厂商预装的录屏功能依赖图形界面手动操作不同品牌入口不一样清晰度预设也不同关键是没法在自动化脚本里稳定触发。虽然可以用UI自动化的方式去点那个录制按钮但多一层界面操作就多一层脆弱性而且录制过程中如果弹窗、Toast、系统级对话框打断很容易误触或者中断。adb录屏的本质是PC端通过adb shell向设备端下达录制指令设备端屏幕录制服务直接把合成后的画面编码成MP4文件不存在App前台激活、弹窗授权等交互步骤只要设备连上并且授权了调试命令就能在后台静默执行。这意味着它可以和测试脚本同时跑也可以在设备做其他操作时全程记录屏幕变化非常适合三类场景复现偶现bug、自动化用例的过程记录、CI构建后的附件收集。1.2 底层机制和两个隐藏限制想用好一个工具最好先知道它底下是怎么工作的。screenrecord命令依赖设备端的SurfaceFlinger也就是系统合成器来获取最终的屏幕画面然后通过MediaCodec硬件编码器压缩数据最后通过复用器封装成MP4。这里有两个很容易被忽略的点。第一它录制的是系统合成后的最终画面不是某个App内部的渲染层所以悬浮窗、Toast、权限弹窗这类系统级覆盖层都会被录进去。这个特性在定位问题时是优点因为你可以看到真实用户看到的完整画面但它也意味着如果你只想录某个App界面录前必须先确保其他遮挡元素不存在否则画面上会混进无关信息。第二编码能力上限取决于设备本身的硬件编码器不是软件想压多高就压多高。分辨率调太高、码率调太猛在低端设备上会出现编码器拒绝工作、掉帧增多甚至录制进程直接被系统杀掉的情况。理解这一点就不会在参数设置上无脑往最大值怼后续第三章的参数选择也会更有依据。2. 环境准备adb工具、设备连接与无线调试2.1 adb工具获取与版本检查说句实在话adb录屏这个功能本身不挑设备品牌也不挑系统版本但它挑adb工具的版本。第一件事是确认电脑上安装的platform-tools足够新。我见过不少老版本adb在新型号设备上遇到设备列表识别异常或者授权状态一直是unauthorized的问题更新工具包之后直接恢复正常。所以我对新环境的第一条建议永远是去官方渠道下载最新平台工具包而不是找别人拷贝一份好几年前的版本。安装好后在终端里执行一条验证命令adb version正常情况下会输出一串版本号就说明工具已经可用。如果系统提示找不到adb命令需要把platform-tools的路径配置到PATH环境变量里或者直接在platform-tools目录下执行./adb version来验证。Windows用户还要注意tools目录下同时有一个旧版的adb.exe容易和新版混淆建议只用platform-tools里的。2.2 首次连接的授权细节设备连接这一步坑集中在首屏授权上。把安卓设备通过USB插到电脑后默认并不会直接获得控制权需要到设备上打开开发者选项开启“USB调试”开关。首次连接时设备屏幕会弹出“允许USB调试吗”的授权窗很多人没注意设备屏幕一直盯着电脑终端结果adb devices里永远显示unauthorized。正确步骤是先确认设备端弹出窗口并勾选“始终允许”然后再执行连接状态检查adb devices正常结果大概长这样List of devices attached ABC1234567 device后面的状态如果是unauthorized去设备上重新勾选授权如果是offline重新拔插USB线或者执行adb kill-server和adb start-server重启adb服务。如果是Linux环境还经常遇到no permissions问题这是USB设备节点权限不够通常需要配置udev规则只靠adb重启只能临时缓解。2.3 无线调试的接入方式长时间插着一根线录屏我总觉得不踏实稍微碰一下桌子连接就掉线了。后来用到无线调试之后录屏场景里基本能脱离线缆。无线连接的原理其实就是让设备在某个端口上开启adb服务然后电脑通过网络连接过去。操作上分成两步。设备先以USB方式连接一次在终端里执行adb tcpip 5555然后可以拔掉数据线在电脑上指定手机在局域网内的IP地址adb connect 192.168.x.x:5555连接成功后adb devices里的状态和USB连接一致。无线调试对录屏有一个很实际的好处设备可以固定在支架上做长时间演示不用被线缆长度限制多个设备同时录制时也不会出现线缆缠绕的问题。不过无线传输不稳定会带来偶发中断录屏结束时必须确认命令是否真的正常退出不能让它挂在后台一直录。3. 录屏命令的实操参数选择与文件管理3.1 最基础的一条命令工具就绪后录屏的核心命令长这样adb shell screenrecord /sdcard/demo.mp4这条命令的意思是让设备端的screenrecord服务把屏幕内容写入/sdcard/demo.mp4文件。它会一直录制直到你手动中断它或者达到默认时长上限。默认时长上限是180秒分辨率由设备默认决定通常偏高直接这样录出来的文件体积会被撑得很大。停止录制的动作看着简单实际有讲究。最推荐的方式是直接在电脑端按CtrlC终止大多数设备会正常收尾并写好MP4文件索引。千万不要用CtrlZ把进程挂起那样screenrecord进程还留在设备端后台运行文件很可能没有正常finalize最后拉回来打不开。录完把文件拉到电脑上adb pull /sdcard/demo.mp4默认会放到当前所在目录也可以用相对路径或绝对路径指定存放位置。3.2 分辨率、码率、时长怎么选参数选择上我的习惯是先把三种核心参数的关系理清楚分辨率决定画面的细节清晰度码率决定同分辨率下的画质保留度时长决定总文件大小。这三者互相制约代码里设置不合理就会出现文件巨大但画质破碎或者文件很小但模糊不清的情况。常用参数对照先放这张表参数作用建议取值--size设置录制分辨率1280x720优先1080p以上需确认设备编码能力--bit-rate设置视频码率单位是bps纯界面操作4Mbps动态内容8Mbps起--time-limit设置单次录制时长上限单位是秒1到180之间超过需分段--rotate旋转画面90度横竖屏切换时使用--verbose输出详细日志排查启动失败时启用--display-id指定显示设备ID多屏设备使用普通设备忽略拿一个实际场景举例录制45秒的列表滚动操作希望文件体积控制在23MB以内命令这样写adb shell screenrecord --size 1280x720 --bit-rate 4000000 --time-limit 45 /sdcard/list_scroll.mp4这里4000000就是4Mbps换算成bps的结果。有人会把--bit-rate直接写成4000那样码率会低得离谱画面全是马赛克。4Mbps大约对应每秒0.5MB写入45秒录下来约23MB清晰度和体积在这个场景下比较平衡。如果录的是游戏操作或视频播放建议把码率调到8000000以上否则动态画面会有明显的模糊感。3.3 停止录制与文件完整性校验录屏停止后我强烈建议不要直接去拉文件先检查文件状态adb shell ls -l /sdcard/demo.mp4文件大小是零字节或者远小于正常体量基本可以断定录制中断或编码异常这时直接重录比尝试修复更省事。文件拉回本地后还有一步容易被忽略MP4的兼容性。部分设备硬件编码器生成的MP4在某些播放器或剪辑软件里解码异常表现是能听到声音但画面是黑屏或者干脆说文件已损坏。遇到这种情况先换VLC或ffmpeg重新封装试一下不要第一时间判定文件损坏。另外一个常见的黑屏现象不是bug而是设备锁屏了。锁屏状态下SurfaceFlinger仍然在工作但绘制层不包含真实内容采到的画面就是黑色。录屏之前确保设备处于亮屏且解锁状态如果设置了自动锁屏把锁屏时间暂时调长或者关闭避免录制中途锁屏。3.4 更多参数与场景调整除了上面那张表里的参数还有几个实战中会用到的细节。--rotate参数只在设备横竖屏切换时有用它会旋转整个录屏方向90度。但要注意它不会自动调整画面比例旋转后可能出现拉伸或者黑边需要自己在后期处理时裁剪。--display-id参数只在折叠屏、外接大屏这类多显示设备上才需要。开机后可以执行adb shell dumpsys SurfaceFlinger来查看当前有哪些显示设备ID普通手机上用不到。配合Seekbar调整的事我一般不在命令行里处理因为screenrecord不支持倍速回放这样的功能。如果需要针对某个时间段定位画面录制的时长越短越好所以录制前尽量明确录制目标能拍45秒不要录满180秒后面分析会省很多时间。4. 自动化场景录屏脚本与日志对齐4.1 PC端录制脚本的完整思路如果只是偶尔录一次手动输命令没有任何问题。但录屏一旦成为日常操作写一个脚本管理整个过程就很有必要。最简单也最实用的脚本应该包含四步按时间戳生成文件名、在设备端启动录制、自动拉取文件、按时间戳保存到本地归档目录。下面这段思路在我自己环境里跑过很多次可以直接照着改device$1 basepath$(date %Y%m%d_%H%M%S) remote_path/sdcard/screen_${basepath}.mp4 local_dir./recordings mkdir -p $local_dir adb -s $device shell screenrecord --time-limit 60 $remote_path adb -s $device pull $remote_path $local_dir/${basepath}.mp4 adb -s $device shell rm $remote_path这段脚本最核心的一点是使用-s 设备序列号指定设备因为在多设备连接时adb不会自动区分当前操作的是哪一台没有设备参数会直接导致命令串台。脚本执行后录屏文件、拉取动作、设备端清理一次完成不会在设备存储里堆积文件。4.2 多设备并发与CI集成多设备同时跑测试的场合脚本要多做一层并发控制。我的做法是遍历adb devices的输出按设备序列号逐个启动录制任务每个任务在独立的目录下保存文件。注意不要在同一目录下用相同的时间戳命名因为并发时两台设备可能在同一秒生成相同文件名会互相覆盖。CI环境里集成录屏有几点注意。持续集成节点上要提前安装好adb工具测试机要保持USB调试开启并允许授权最好做一个无人值守的授权配置不然每次构建都要人工点授权弹窗。录屏产物作为构建附件拉回后建议按任务ID和用例名组织目录结构方便后续追溯失败用例时快速找到对应录屏。4.3 录屏和日志时间戳对齐录屏本身的价值不在于能回放画面而在于画面能和其他调试数据对上时间。很多偶现bug是当你看到异常画面时已经错过了问题发生的第一现场这时候如果只有录屏没有日志依然很难定位。我的做法是启动录屏之前先在设备端写入一个日志标记记录起点时间然后在录制结束再写一个标记。接着在录制期间同步抓取logcatadb logcat -v time log_${basepath}.txt adb shell screenrecord --time-limit 60 $remote_path waitlogcat输出的每行都带时间戳录屏文件也有一个精确到秒的启动时间把日志里标记时间和录屏时间做对照就能锁定某个UI异常发生前的最后几秒操作轨迹。这套组合在我排查过一个偶现崩溃的问题频繁复现几次之后从录屏里看到了崩溃前一瞬间的动画状态再翻logcat定位到具体的异常调用栈大大缩短了排查时间。需要注意的坑是logcat进程要确保在录制结束后正常终止不然会一直往磁盘里写日志文件CI节点上跑久了很容易把磁盘写满。4.4 超长录制的分段方案单次录屏180秒的上限遇到超过3分钟的需求时必须分段处理。最直接的方式是循环启动短时长录制for i in 1 2 3 4; do adb shell screenrecord --time-limit 180 /sdcard/part_$i.mp4 done这样会产生连续的多段文件但每段之间会有一个启动间隙画面存在短暂断层。如果对连续帧要求不高这是最简单的方案。要求无缝连续录制的场景我建议不要在这个方案上死磕直接考虑其他录制方案更省心。特别是长时间录制时设备持续编码发热掉帧和文件损坏的概率都会增加分段的间隔反而给了编码器一点喘息时间。5. 高频问题排查与经验总结5.1 连接状态异常的处理adb录屏最常见的拦路虎永远在连接环节。设备明明插上了adb devices列出的状态却总是不对。我把几种典型状态和解决办法整理成表状态原因处理办法unauthorized授权弹窗未确认或已撤销设备开发者选项里撤销USB调试授权重新插拔并确认弹窗offline驱动异常或adb服务卡死adb kill-server再adb start-server更换数据线no permissionsLinux下USB设备权限不足配置udev规则临时可执行adb usb空列表USB线和接口接触不良换线和接口检查设备是否进入USB调试模式数据线的质量在这一步非常关键我遇到过不少频繁掉线的问题最后发现是劣质数据线只有充电线没有数据线信号极其不稳定。建议备一根质量有保证的短数据线做调试专用。5.2 文件打不开或黑屏的排查路径录制完成但拉回本地后无法播放这个坑我踩过不止一次。排查路径是这样的先看设备端文件大小如果只有几百字节基本可以放弃修复直接重录如果文件大小正常但播放器提示损坏换VLC或者ffmpeg重新封装多半能解决。黑屏则要区分录制阶段的表现。如果录屏从启动那一刻就是黑的先检查设备是否在锁屏状态如果前半段正常后半段黑屏很可能是录制过程中设备自动锁屏了。解决方法是录前关闭或延长自动锁屏时间保持屏幕常亮同时把充电线插上防止设备休眠。5.3 时长限制与音频缺失的妥协方案--time-limit参数最大180秒这个限制在实际使用中确实让人烦躁但它是稳定性考量。单次录制时间太长移动设备硬件编码器长时间高负荷工作容易发热掉帧和文件损坏的概率都会增加。分段录制不是绕过限制而是在稳定性和连续性之间找平衡。另外screenrecord在原生实现里根本不支持录音录出来的视频永远是静音。如果你需要带声音的演示视频只能另行采集音频。我的做法是先用无声音的录屏作为排查素材等需要做存档或分享时再单独录制系统音频或者用电脑端录音最后用ffmpeg合成。这样既保证了排查效率又得到了带讲解音的成品视频。需要注意的是android系统机型差异会导致录屏静音现象表现略有不同但原生命令层面确实不处理音频轨道。5.4 一个完整的实操案例流程最后分享一个我实际跑过的完整流程你可以把它当作模板。某天同事反馈一个偶现问题现象是某个页面加载时偶尔出现短暂白屏持续时间极短肉眼很难看清。我准备了两台设备一台跑自动化的压力操作一台专门录屏。我的操作顺序是先配置无线连接让设备脱离USB线缆然后执行adb tcpip和adb connect接着写一个结合logcat和screenrecord的脚本把操作过程完整记录60秒。录完之后按时间戳拉回文件检查文件大小确认没有损坏再用播放器逐帧查看白屏出现的时间点回头翻logcat定位到对应的日志级别和报错信息很快锁定了是资源加载回调异常导致的页面渲染延迟。这一步流程里没有使用任何第三方录屏工具全部靠adb自带能力完成。熟练之后一个包含连接、录屏、拉取、归档、日志对照的完整链路大概几分钟就能跑完比在手机上手动录屏再导出要快得多而且整个过程可重复、可自动化。录屏这个能力单独看只是调试链路里的一环但和日志、截屏、性能数据组合起来看价值会被放大很多。工具本身不难难的是把它的参数选型、异常处理和自动化集成这些事情想清楚。你只要把基础命令跑顺再把脚本思路沉淀成自己的工具集后面遇到需要画面回放的调试场景基本都能从容应对。