Flutter 动画 GIF 录制指南：用 adb screenrecord 与 QuickTime 制作动画 Bug 复现素材

本文基于 Flutter 官方贡献文档中的动画 GIF 制作指南（Making-animated-GIFs-of-Flutter-apps.md），完整讲解在 Android 真机与 iOS 模拟器上录制 Flutter 应用屏幕视频、并将视频转换为动图 GIF 的全流程，包括每条 adb 命令的作用、推荐的 GIF 尺寸与帧率参数。读完后你可以独立产出可直接附在 issue 或 PR 中的动画复现 GIF，用于记录动画曲线、转场、帧率抖动等只有动态画面才能说明的问题。

为什么动画类问题需要动图 GIF

在 Flutter 仓库中，这篇文档位于 issue hygiene（issue 卫生规范） 目录下，并被 用户文档索引收录，它的定位很明确：为 issue 中的动画问题提供可视化证据。

同目录的 issue 提交规范 要求：

• 每个 issue 都应包含清晰的复现步骤、期望结果与实际结果；
• 应尽可能提供"reduced test case"（最小复现工程）；
• 避免提交无法被文字描述完整覆盖的信息。

而动画行为——缓动曲线的形状、过渡的时序、滚动时的卡顿与丢帧——恰恰是静态截图无法表达的。一张静态截图只能说明"某一帧长什么样"，无法说明"帧与帧之间发生了什么"。Animated GIF 正是为此而用的：它体积小、可直接内嵌在 issue 与文档中、无需用户下载播放器，是记录动画类 Bug 的首选素材形式。

在 Android 设备上录制动画视频

前提条件

1. 设备系统版本：屏幕录制功能（screenrecord）在 Android 4.4（KitKat）及以上版本可用。

2. 以 release 模式启动应用：

   flutter run --release
   

   原文档特别强调这一点，理由是"更快的性能"。结合引擎的 运行模式说明可以印证：release 模式关闭全部断言、剥离尽可能多的调试信息，专为"快速启动、快速执行、小体积"而优化；而默认的 debug 模式"不针对执行速度、二进制体积做优化"，主要用于快速的开发/运行循环。用 debug 模式录制的动画，帧率表现不能代表终端用户的真实体验，因此涉及动画流畅性的问题，应当用 flutter run --release 启动后再录制。

开始录制

在命令行中执行：

adb shell screenrecord /sdcard/recording.mp4

说明：

• adb shell screenrecord 是 Android 系统自带的录屏工具，直接在设备端录制屏幕，输出为 MP4 文件；
• 参数 /sdcard/recording.mp4 是录制文件在设备侧的存储路径，录制完成后需要用下一条命令取回本地。

操作应用并停止录制

在录制进程保持运行的期间，正常操作 App（触发目标动画）。操作完成后，回到执行命令的终端，按 Ctrl+C 终止 screenrecord 进程，设备上的录制即告结束。

把视频取回本地硬盘

adb pull /sdcard/recording.mp4 ~/Downloads/

• 源路径必须是录制时写入设备的那个路径 /sdcard/recording.mp4；
• 目标路径 ~/Downloads/ 是本机下载目录，可按需替换为任意本地目录。

在 iOS 模拟器上录制动画视频

iOS 模拟器没有 screenrecord，文档给出的方案是使用 macOS 自带的 QuickTime Player 做屏幕录制：

1. 将 iOS 模拟器窗口移动到最顶层（置于其他应用之上），避免录制时被遮挡；
2. 启动 QuickTime Player 应用；
3. 从 File（文件） 菜单中选择 New Screen Recording（新建屏幕录制）；
4. 在模拟器窗口上框选一个矩形区域（只圈住模拟器画面即可，避免录入多余桌面内容以减小素材体积），然后点击 Start Recording（开始录制）；
5. 操作应用，触发需要记录的动画；
6. 结束后点击菜单栏上的 Stop Recording（停止录制）；
7. 如录制范围偏大，可通过 Edit（编辑） 菜单中的 Trim（修剪） 去掉首尾多余片段；
8. 保存录制文件。

将录制视频转换为 GIF

文档使用的转换工具是在线服务 ezgif 的 Video to GIF 功能。上传录好的视频后，按以下参数设置：

设置项	推荐值	说明
起止时间	按需要裁剪	若需进一步裁剪，选择 GIF 的起始与结束时间，只保留关键动画片段
尺寸	320 × AUTO	选择"足够小"的尺寸；原文档推荐宽度 320、高度自适应（320xAUTO）。宽度 320px 在 issue 页面中清晰可读，同时把 GIF 文件体积压到很小
帧率	尽量高（上限 20 fps）	帧率越高动画越平滑，该工具上限为 20 fps，建议直接取最大值

设置完成后执行转换，下载生成的 GIF 文件即可。

"先录视频、再转 GIF"这一两步式流程的设计意图：视频（MP4）采用有损压缩编码，体积远小于逐帧无损存储的 GIF。因此先在设备端录出紧凑的视频，再在转换阶段按需裁剪尺寸与帧率，比直接逐帧采集屏幕更省存储、也更灵活——同一段视频可以裁剪出多个不同长度的 GIF 用于不同 issue。

适用边界与相关材料

需要注意几点适用前提与限制：

• Android 方案要求设备为 KitKat 及以上；低版本设备不可用 screenrecord；
• Android 方案依赖本机已配置好 adb 并能连上目标设备（flutter run 能正常执行是同一前提）；
• iOS 方案依赖 macOS 上的 QuickTime Player，只覆盖模拟器场景；真机录屏需要走 Xcode 设备窗口或第三方工具，本文不展开；
• 帧率上限 20 fps、推荐尺寸 320×AUTO 是原文档给出的经验值，目标是"在 issue 页面中可读"与"文件体积可控"之间的平衡，而非追求最高画质。

与本文相关的仓库材料，可进一步阅读：

• 原始指南：docs/contributing/issue_hygiene/Making-animated-GIFs-of-Flutter-apps.md
• issue 提交与复现规范：docs/contributing/issue_hygiene/README.md
• Flutter 运行模式（debug/release/profile）说明：docs/engine/Flutter's-modes.md
• 用户文档索引：docs/wiki_archive/User-documentation-index.md