简介这份仿抖音上下滑动切换视频的 Android 工程面向希望掌握短视频流交互与播放器集成的移动端开发者围绕 RecyclerView、SnapHelper 与自定义 LayoutManager 的组合解决整页滑动切换、停止后自动居中定位等问题。压缩包共 1486 个文件、约 58.73MB含 25 个 Java 源码、61 个 XML 布局与配置、3 个 Gradle 脚本以及 200 个 dex、198 个 class、58 个 jar、20 个 so 等依赖与编译产物另有 2 个 mp4 素材和 1 个 apk可直接对照运行。已有 4848 人学习下载。内容覆盖视频异步加载、ExoPlayer 播放、手势识别、ItemAnimator 过渡动画及 DiffUtil 性能优化便于拆解工程结构、复用核心实现并排查滑动冲突与卡顿。1. 竖屏上下滑动切换视频看起来只是翻页真正的坑全在播放器上第一次接到「上下滑动切换视频」的需求多数人第一反应是套一个竖向 PageView 或 Swiper半天就能跑出 demo一屏一个视频手指一划下一个。真机一上全露馅——滑到第三条黑屏两秒、来回滑几次内存冲到 800M 下不来、已经划走的视频声音还在响。这套仿短视频竖滑效果的工程真正要解决的从来不是翻页动画而是「一屏一个播放器」这个模型在移动端的资源账实例怎么复用、预加载到第几条、切走之后谁负责释放。它适合三类人想给自己 App 塞一条竖屏信息流的业务开发、接手了别人跑不起来的 demo 要救火的人、以及准备把这套交互搬到自己的技术栈里的同学。下面按结构、链路、优化、踩坑、二次开发五段拆开讲。2. 工程结构与选型滑动层和播放层为什么必须拆开竖滑效果做砸的项目八成在第一天就把「翻页」和「播放」写在了同一个 Widget 里。翻页是 UI 层的事播放是原生解码器的事两者生命周期完全不一致页面可以缓存 10 个播放器实例却只敢同时存在 2 到 3 个。分层不是为了好看是为了让「页面切走了但播放器还留一会儿」这件事有地方落。2.1 目录结构谁负责滑动谁负责播放拿到工程先看目录能不能二次开发基本一眼就能判断。vfeed/ ├── lib/ │ ├── main.dart # 入口只做主题和路由 │ ├── models/ │ │ └── video_item.dart # 数据模型字段对齐后端返回 │ ├── pages/ │ │ └── feed_page.dart # 竖滑容器只管 PageView 和索引 │ ├── widgets/ │ │ ├── video_cell.dart # 单屏视频单元只管渲染 │ │ └── gesture_wrapper.dart # 自定义手势阈值可选 │ ├── services/ │ │ ├── player_pool.dart # 播放器实例池核心中的核心 │ │ ├── preload_queue.dart # 预加载队列 │ │ └── feed_repository.dart # 数据源抽象方便替换 │ └── utils/ │ └── throttle.dart # 滑动事件节流 ├── assets/covers/ # 兜底封面图弱网时顶一下 └── pubspec.yamlfeed_page.dart里不应该出现VideoPlayerController这个词player_pool.dart里也不应该出现任何Widget。这条线一旦破了后面所有内存问题都会变成玄学。video_cell.dart只接收一个VideoItem和一个isActive布尔值渲染逻辑全部由状态驱动不主动调播放接口——这一点在第四章讲内存时会再提一次。2.2 技术选型与换栈映射工程主体用的是 FlutterPageView.builder负责竖向翻页video_player负责解码底层在 Android 走 ExoPlayeriOS 走 AVPlayerdio拉接口缓存封面用cached_network_image。层次本项目实现Android 原生对应iOS 原生对应Web 对应翻页容器PageView.builder(vertical)ViewPager2 竖向UICollectionView 竖向分页Swiper vertical播放能力video_playerExoPlayer / Media3AVPlayervideo hls.js实例复用手写 PlayerPool对象池 Surface 复用AVPlayerItem 复用单个 video 标签换 src预加载PreloadQueueonBindViewHolder 里预 prepare提前 prepareItem预加载 m3u8 首片段这张表的价值在于这套池化和预加载思路是通用的换栈只需要替换播放器 API调度逻辑本身不用重写。选 Flutter 是因为它把两个平台的播放器差异抹平了一层代价是某些底层能力比如硬解策略拿不到真要抠首帧时间还是得写 platform channel。2.3 数据模型与接口约定模型字段设计得好不好直接决定后面预加载写起来顺不顺。// lib/models/video_item.dart class VideoItem { final String id; final String playUrl; // 播放直链别在切页时再做码率协商 final String coverUrl; // 首帧出现前的占位图必须有 final int width; // 原始宽高用于封面裁切和留黑边判断 final int height; final int durationMs; final String authorName; final String desc; const VideoItem({ required this.id, required this.playUrl, required this.coverUrl, required this.width, required this.height, required this.durationMs, required this.authorName, this.desc , }); // 竖屏流几乎所有布局都围绕这个比例走缓存一份避免每帧重算 double get aspectRatio height 0 ? 9 / 16 : width / height; factory VideoItem.fromJson(MapString, dynamic json) VideoItem( id: json[id] as String, playUrl: json[play_url] as String, coverUrl: json[cover_url] as String, width: (json[width] as num?)?.toInt() ?? 720, height: (json[height] as num?)?.toInt() ?? 1280, durationMs: (json[duration_ms] as num?)?.toInt() ?? 0, authorName: json[author_name] as String? ?? , desc: json[desc] as String? ?? , ); }id是池子的 key必须是稳定的字符串别拿列表下标当 key——下拉刷新一次就全乱了。playUrl一定要是拿起来就能播的直链很多项目把签名和码率协商放在播放前一步做结果切页时多一次网络往返首帧时间直接翻倍。coverUrl和width/height都是为了「首帧出现前的 200 毫秒」服务的缺一个都会露出黑底。接口侧按游标分页常见做法是{page, size}加一个has_more前端在距离列表底部还有 3 条时触发下一页。别等滑到最后一条才请求那时候用户已经在盯着 loading 了// 下一页触发判定放在 onPageChanged 里 const PREFETCH_WHEN_LEFT 3; function shouldLoadMore(currentIndex, total, hasMore) { if (!hasMore) return false; return total - currentIndex PREFETCH_WHEN_LEFT; }PREFETCH_WHEN_LEFT这个 3 是经验值滑得快的人一次能连划两屏留 3 条刚好够缓冲。留 1 条会在弱网下频繁看到骨架屏留 8 条则会让首屏请求变大、进入时间变长。3. 核心链路一次上下滑动从手指到第一帧的全过程把一次滑动拆开实际发生的事是手指抬起 → PageView 判定是否翻页 → 索引变化 → 旧视频暂停 → 新视频定位到 0 秒 → 起播 → 首帧上屏。中间任何一步做了异步等待而没做竞态保护就会出「滑走三屏了前一个还在响」这种事。3.1 手势与翻页阈值到底该定多少Flutter 的PageView自带翻页判定但产品经常要求「拖过四分之一屏就翻」。要改手感就得自己接管手势核心是一个比例阈值// lib/widgets/gesture_wrapper.dart const double kFlipThreshold 0.25; // 拖过屏高 25% 就翻页 /// dy: 手指位移向上拖为负screenHeight: 屏幕物理高度 int? resolveTarget(double dy, double screenHeight, int current, int total) { final ratio dy / screenHeight; if (ratio.abs() kFlipThreshold) { return null; // 没到阈值回弹到当前页不切 } // 向上拖 - 下一条向下拖 - 上一条 final target dy 0 ? current 1 : current - 1; if (target 0 || target total) { return null; // 边界直接吞掉别让它抖一下 } return target; }kFlipThreshold取 0.25 是有依据的低于 0.15 时误触率明显上升用户想滚一下评论区就翻页了高于 0.4 又会让人觉得「划不动」。返回值用int?而不是直接跳转是为了把「判定」和「执行」分开——判定是纯函数可以单测执行才涉及动画和播放器。3.2 翻页容器几个参数决定手感// lib/pages/feed_page.dart节选 PageView.builder( controller: _controller, scrollDirection: Axis.vertical, // 一行决定方向 pageSnapping: true, // 一屏一屏停别停在半路 physics: const ClampingScrollPhysics(), // 关掉 iOS 回弹避免边界露底色 itemCount: _items.length, onPageChanged: _onPageChanged, itemBuilder: (context, index) VideoCell( item: _items[index], isActive: index _current, // 只传状态不传控制器 ), )ClampingScrollPhysics这条是被投诉出来的iOS 默认的BouncingScrollPhysics会让第一屏往下拖时露出黑色背景视觉上像闪了一下。pageSnapping: true保证手指松开后一定停在整屏位置否则会出现半屏视频半屏黑的诡异画面。onPageChanged是整个链路的分发点这里只做三件事别塞更多void _onPageChanged(int index) { final previous _current; setState(() _current index); PlayerPool.instance.switchTo(_items[index], previous: _items[previous]); PreloadQueue.instance.onIndexChanged(index, _items); }3.3 播放器池为什么不能一屏一个实例这是整个工程最值钱的一段。PageView.builder会缓存相邻页面如果每个VideoCell在initState里各自 new 一个控制器滑过十条视频就存在十个解码器内存和硬解资源双双爆掉。// lib/services/player_pool.dart class PlayerPool { static final PlayerPool instance PlayerPool._(); PlayerPool._(); static const int maxPlayers 3; // 当前 上一条 下一条再多就是自杀 final MapString, VideoPlayerController _pool {}; final ListString _lru []; // 末尾是最近使用的 FutureVideoPlayerController acquire(VideoItem item) async { final cached _pool[item.id]; if (cached ! null) { _touch(item.id); return cached; } final controller VideoPlayerController.networkUrl(Uri.parse(item.playUrl)); await controller.initialize(); // 拿到首帧后才敢往下走 await controller.setLooping(true); // 短视频默认循环播放 _pool[item.id] controller; _touch(item.id); await _evictIfNeeded(); return controller; } void _touch(String id) { _lru.remove(id); _lru.add(id); } Futurevoid _evictIfNeeded() async { while (_pool.length maxPlayers) { final oldest _lru.removeAt(0); final c _pool.remove(oldest); await c?.pause(); await c?.dispose(); // 不 dispose原生解码器不释放 } } }maxPlayers 3这个数不是拍脑袋用户向上划一条要 300ms 左右向下划回来同样要 300ms保留上下各一个刚好覆盖「划过去又划回来」的高频操作。设成 5 在小内存机型上会开始频繁 GC设成 1 又会让回滑必然黑屏。_evictIfNeeded里pause和dispose必须都调。只dispose不pause在某些 Android 机型上会让音频焦点残留只pause不dispose就是内存泄漏的经典写法。3.4 切换时机await 之后必须重新判断Futurevoid switchTo(VideoItem current, {VideoItem? previous}) async { if (previous ! null previous.id ! current.id) { await _pool[previous.id]?.pause(); // 先停旧再起新避免双音轨 } final c await acquire(current); // 这里可能等几百毫秒 if (_disposed) return; // await 之后状态可能已经变了 if (_currentId ! current.id) return; // 用户已经滑到别的视频了 await c.seekTo(Duration.zero); await c.play(); }if (_currentId ! current.id) return;这两行是血泪经验。acquire里有一次initialize()的网络等待如果用户手快连划两屏第一个switchTo会在第二个之后返回结果就是播了错的视频。所有跨越await的播放操作后面都补一句状态校验这是这套代码里唯一不能省的防御。3.5 预加载队列只预热真正需要的两条// lib/services/preload_queue.dart class PreloadQueue { static final PreloadQueue instance PreloadQueue._(); PreloadQueue._(); bool _busy false; // 同一时刻只跑一个别抢带宽 final SetString _done {}; void onIndexChanged(int index, ListVideoItem items) { final targets VideoItem[ if (index 1 items.length) items[index 1], // 最该准备好的 if (index 2 items.length) items[index 2], // 手快的人够用 ]; _warmUp(targets); } Futurevoid _warmUp(ListVideoItem targets) async { if (_busy) return; _busy true; try { for (final item in targets) { if (_done.contains(item.id)) continue; final c await PlayerPool.instance.acquire(item); await c.setVolume(0); // 预热静音用户听不见 await c.pause(); _done.add(item.id); } } finally { _busy false; } } }_busy这个锁很关键。连续快速滑动会触发多次onIndexChanged没有锁的话会同时发起五六个initialize()把当前视频的带宽抢干净首帧时间反而更长。setVolume(0)是必须的否则预加载的视频会在后台出声这在真机上一测就露。4. 播放体验优化首帧、带宽、内存三笔账竖滑流体验好不好用户其实只感知两件事滑过去之后多久出现画面以及滑十分钟手机烫不烫。前者靠封面和预加载后者靠实例回收和渲染降级。4.1 首帧先用封面顶住再让画面接管从initialize()完成到第一帧真正上屏中间还有一段纹理上传的时间。这段空白用一个 200ms 的淡入盖住观感差别非常大// lib/widgets/video_cell.dart节选 Stack( fit: StackFit.expand, children: [ // 底层永远有封面弱网时用户看到的是图不是黑屏 CachedNetworkImage( imageUrl: item.coverUrl, fit: BoxFit.cover, memCacheWidth: 720, // 限制解码尺寸别按原图分辨率解 ), if (isActive _ready) FadeTransition( opacity: _fade, // 200ms长了会显得卡 child: VideoPlayer(_controller), ), ], )memCacheWidth: 720容易被忽略。封面图如果是 1080×1920 的 PNG一张解出来就是 8MB滑十条就是 80MB比播放器还占内存。限制到屏幕宽度即可竖屏流不需要原图精度。4.2 预加载的边界别把推荐流当本地播放器预加载只做两条不做五条原因是带宽。移动端单连接有效带宽有限同时拉三个视频流当前这条的起播速度会明显变慢。判断标准很简单如果在弱网模拟 3G下首帧时间超过 1.5 秒先砍预加载数量再考虑降码率。还有一个容易翻车的点预加载完成的实例如果用户一直没滑到PlayerPool会在池子超限时把它淘汰掉_done里的记录却还在。所以evict的时候要同步清理_done否则下次滑到它会误判成「已经预热过」直接播黑屏。这个 bug 只在快速来回滑动时出现测试用例很难覆盖属于典型的黑匣子问题。4.3 内存与生命周期三个必须接的口子// 页面级生命周期统一收口 override void didChangeAppLifecycleState(AppLifecycleState state) { switch (state) { case AppLifecycleState.paused: PlayerPool.instance.pauseAll(); // 只暂停不销毁回来能秒播 break; case AppLifecycleState.resumed: PlayerPool.instance.resumeCurrent(); break; default: break; } } override void dispose() { _controller.dispose(); PlayerPool.instance.disposeAll(); // 页面销毁才真正全清 super.dispose(); }三个口子分别是切后台暂停不然锁屏了还在放、页面销毁全清不然退出后解码器还挂着、路由被覆盖时暂停比如打开了评论半屏弹窗。第三个最容易被漏实现方式是给FeedPage套一层RouteAware在didPushNext里暂停。pauseAll和disposeAll的区别要分清前者保留实例回来时 0 延迟恢复后者释放全部资源。切后台用前者退出页面用后者混用会导致「切回来黑屏」或者「退出后内存不降」。5. 避坑与排查真机上最容易翻车的五个场景下面这五条都是自测时发现不了、上线后被反馈出来的问题每条按现象、原因、解决写遇到同类症状可以直接对号入座。5.1 滑到第三条开始黑屏两秒现象前两条秒开从第三条起每次都要等一到两秒才出画面网络越好越不明显弱网必现。原因initialize()是在onPageChanged之后才发起的等于用户已经滑到了才开始下载。前两条之所以快是因为它们被PageView提前构建、碰巧提前初始化了。解决接上PreloadQueue在当前索引变化时预热后两条并且给预加载实例设setVolume(0)pause()。改完之后第三条的首帧时间从 1.8 秒压到 300ms 以内。5.2 来回滑十几次内存涨到 800M 不回落现象冷启动内存 180M连续上下滑动两分钟后涨到 800M停下来也不降最后被系统杀掉。原因两个叠加问题。一是VideoCell在initState里自己创建控制器池子根本没生效二是封面图没限制解码尺寸一张 1080P 的 PNG 解出来就是 8MB滑十条就 80MB。解决把所有控制器创建收口到PlayerPool.acquireVideoCell只从池子里取封面加memCacheWidth限制到屏幕宽度。用 DevTools 的 Memory 面板对比改前改后峰值内存从 800M 降到 260M 左右。5.3 视频已经滑走了声音还在响现象快速连划三屏能同时听到两段音频混在一起过一两秒才恢复。原因switchTo里pause和play都是异步的await acquire()期间用户已经滑到下一个等它返回时执行play()的是上一个视频。这是典型的竞态。解决在await之后补状态校验索引不对就直接 return不再执行play()。同时switchTo里先pause旧实例再acquire新实例不要并行。5.4 iOS 上第一屏往下拖会闪一下白现象在顶部继续向下拖露出白色或灰色背景视觉上像闪屏。原因PageView默认用了BouncingScrollPhysics边界处允许回弹露出的是Scaffold的背景色。解决换成ClampingScrollPhysics并把Scaffold的backgroundColor设成纯黑。这样即使有一帧露出底色也是黑的肉眼看不出。5.5 列表滑到几十条之后越滑越卡现象前二十条很流畅越往后滑动越黏手帧率从 60 掉到 30 左右。原因itemBuilder里传了isActive每次setState都会重建所有已缓存的 cell包括那些根本不可见的。PageView默认缓存相邻页面重建成本被放大。解决把isActive的判断下沉VideoCell用ValueListenableBuilder或者Selector只监听自己这一条的状态父级setState不触发全量重建。改完之后滑动帧率稳定在 55 到 60。6. 二次开发三个改造点和一套验证方法拿到这套工程之后绝大多数人的目标不是「跑起来看看」而是接自己的业务。改造路径其实很固定按下面三块动刀就行。6.1 换数据源把 Repository 抽出来工程里没有把网络请求写死在页面里而是留了一个抽象接口。你只需要实现自己的fetch页面代码一行不用改abstract class FeedRepository { FutureListVideoItem fetch({int page 0, int size 10}); bool get hasMore; } class RemoteFeedRepository implements FeedRepository { final Dio _dio; RemoteFeedRepository(this._dio); override bool hasMore true; override FutureListVideoItem fetch({int page 0, int size 10}) async { final res await _dio.get(/feed, queryParameters: {page: page, size: size}); // 约定返回 {code:0, data:{list:[], has_more:true}} final data res.data[data] as MapString, dynamic; hasMore data[has_more] as bool? ?? false; return (data[list] as List) .castMapString, dynamic() .map(VideoItem.fromJson) .toList(); } }关键在play_url的产出方式。如果你的后端给的是带鉴权签名的临时地址一定要在返回前就算好别留到播放器里去拼——签名逻辑一旦跑进 UI 层后面换 CDN 就是灾难。6.2 加互动层别碰播放逻辑点赞、评论、分享这些浮层统一挂在VideoCell的Stack最上层通过回调把事件抛给页面。这里有个硬约束互动层的任何状态变化都不能引起PageView重建。常见做法是把互动状态放在一个独立的ChangeNotifier里每个 cell 用Selector订阅自己那一份父级完全不参与。改造点不改什么常见误区换数据源PlayerPool、PreloadQueue在页面里直接调 dio加互动层播放器实例管理点赞状态放在页面 setState加广告位预加载队列把广告视频也塞进预热池第三条特别容易出事广告视频往往比内容视频码率高、时长长一旦进了预加载池会挤掉正常内容的预热名额用户划到正片反而黑屏。做法是在PreloadQueue里判断类型广告一律不预热。6.3 验证方法三个数字就够了改完之后怎么确认没退化我的习惯是固定测三项首帧时间、峰值内存、滑动帧率。首帧用Stopwatch在initialize开始和firstFrame回调之间打点连续测十条取中位数峰值内存用 DevTools Memory 面板滑动三分钟后读一次帧率开 Performance Overlay 看那条黄线。三项里任何一项比改之前差 20% 以上就要回头查是哪一步破了。从那以后我每次改这类流式播放的代码都强制自己按「滑十条、来回滑五条、切后台再回来」这套动作走一遍不图别的就图别再被同一类竞态坑第二次。这份工程的结构和逐段注释都能直接对照着看拿去跑一遍再拆比只读代码快得多。希望帮到你。本文还有配套的精品资源点击获取