简介面向iOS中高级开发者的列表视频播放示例工程模仿网易视频和今日头条的浏览交互解决滚动列表内视频预览、点击全屏播放、切换后自动暂停等常见需求。工程基于列表控件与系统视频框架覆盖自定义视频单元格、渲染图层、单元格复用状态恢复、滚动预加载、手势识别、全屏转场与播放状态管理等完整链路兼顾滚动流畅度与资源开销。压缩包共31个文件以源代码与头文件为主体辅以界面布局、配置清单及Xcode工程配置整体仅66KB结构紧凑便于直接运行和分模块研读。已有九百余人学习下载。示例中包含播放器封装、列表控制器、自定义视图等可直接迁移的代码同时展示多尺寸适配、异步加载与内存管理细节可作为同类视频列表功能开发或技术面试的实用参考。1. 列表视频播放从“能播”到“像资讯App那样自动播”做iOS列表视频播放最迷惑人的地方在于单页面播放视频谁都能写但放进UITableView里就立刻变味。我拆过不少号称“模仿某新闻客户端视频流”的项目包大部分暴露的问题一模一样——滚动一快就黑屏、声音还在放但画面已经切走、滑回去又从头播。这次的资源主题直指“列表视频播放”核心目标是把网易视频、今日头条这类Feed流里的体验搬到你自己的UITableView上。适合两类读者已经被列表复用搞到头疼的iOS开发以及想做资讯类App视频流但不知道从哪下手的同学。它能解决的不只是“能播放”而是“说了算”——哪个Cell该播、什么时候停、复用后怎么不串台。2. 架构选型AVPlayer与UICollectionView的分工2.1 为什么不能每个Cell配一个AVPlayer最常见的错误做法是Cell初始化时创建一个AVPlayer绑定一个AVPlayerItem然后等滚动停下时各自播各自的。这在数据量小时看着还行一旦超过5个可见Cell就会出现两个问题。第一个是内存——AVPlayer内部有缓冲和渲染链路每个实例会吃几十MB级别的内存池同时存在多个播放器时App的Memory Footprint直接往上飙大型列表上分分钟触发内存警告。第二个是复用冲突——Cell滚出屏幕时被回收但播放器还挂在AVPlayerLayer上等这个Cell被复用到另一行时上一段视频的画面还粘在上面。正确的分工应该是Cell只负责提供容器View播放器由全局统一管理。这就像一个舞台Cell是舞台布景播放器是演员布景换了演员还在台上。实现上我用一个单例管理器持有唯一的AVPlayer和AVPlayerLayer哪个Cell需要播放就把Layer挂到哪个Cell的容器上。这样内存中永远只有一个播放器在运转和网易视频这类App的实现思路一致。2.2 三个可选方案的取舍具体在技术选型上我拆过三套方案各有适用场景。第一套是AVPlayerViewController自带控制面板、全屏切换和AirPlay支持但它的View结构固定塞进Cell后尺寸和交互都受限做列表流不灵活。第二套是AVPlayer AVPlayerLayer这是最可控的组合Layer是CALayer的子类可以自由控制frame、cornerRadius、videoGravity适合做沉浸式视频Feed流但手势控制、加载状态UI要自己画。第三套是用第三方播放器内核比如ijkplayer或自家的播放器SDK它们的核心还是包了一层音视频解码但对硬解、HLS、秒开做了优化适合视频播放场景复杂度高的项目。我的建议是如果你的目标是复刻今日头条那种“图片文字混排、视频只是其中一种卡片”的Feed流直接选方案二就够了不需要上重型内核。如果视频是全屏播放、清晰度切换、倍速、投屏这些全套再考虑方案三。2.3 播放器状态机的四个关键状态列表视频播放和普通播放器有个本质差异播放器的生命周期不完全由用户操作驱动而是由列表的滚动位置驱动。所以我习惯给播放器显式定义四个状态空闲Idle、预加载Preparing、播放中Playing、已暂停Paused。空闲状态表示当前没有任何播放任务预加载状态表示播放器已创建但还没ReadyToPlay播放中是Layer已经挂到Cell上且avplayer正在播放已暂停则是视频在列表不可见时主动停止而不是销毁。这四个状态必须由管理器统一管理Cell只能通过通知或代理请求“播放某个indexPath”不能直接调play。这样做的好处是所有状态切换都集中在Manager里出现任何异常如切后台、打断、网络失败时只需要在这个类里处理一次不用到处打补丁。3. 自动播放触发滚动停止检测与可视Cell选取3.1 滚动停止的两条判断路径自动播放最核心的触发条件是“列表滚动停止”。很多人只实现scrollViewDidEndDecelerating结果在慢速拖动后松手不产生减速时永远不触发。正确做法是两条路径都要处理extension ViewController: UIScrollViewDelegate { func scrollViewDidEndDecelerating(_ scrollView: UIScrollView) { // 快速滑动松手后减速结束 handleScrollStopIfNeeded() } func scrollViewDidEndDragging(_ scrollView: UIScrollView, willDecelerate decelerate: Bool) { // 慢速拖动后松手且不代表减速decelerate为false此时也算停止 if !decelerate { handleScrollStopIfNeeded() } } private func handleScrollStopIfNeeded() { guard let bestCell findBestPlayCell() else { Self.playerManager.stop() return } Self.playerManager.play(in: bestCell.videoContainer, url: bestCell.videoUrl) } }逻辑说明第一条路径DidEndDecelerating覆盖惯性滑动场景不管手指是快是慢只要滚动过程有加速和减速最后都会落到这个方法。第二条路径覆盖慢速拖动后直接松手的情况此时系统不会产生加速减速动画willDecelerate是false所以在这里手动兜底。参数说明handleScrollStopIfNeeded()里每次都调stop()再play(in:)宁可先停旧再开新也不要尝试在同一个播放器上不清Layer就直接换VideoItem后面避坑章会详细说这个。3.2 被选中的Cell可见面积比例优先不是所有可见Cell都值得播放。如果一行视频只露出50像素播放了也没人看得清还浪费CPU解码。我用的选取逻辑是按“可见面积”排序选出面积最大的那个Cellprivate func findBestPlayCell() - VideoCell? { let visibleCells tableView.visibleCells var bestCell: VideoCell? var bestArea: CGFloat 0 let tableRect tableView.bounds for case let cell as VideoCell in visibleCells { // 将Cell在tableView中的坐标转换为相对于tableView的bounds let rectInTable cell.convert(cell.bounds, to: tableView) let visibleRect rectInTable.intersection(tableRect) // 计算可见部分的面积 let area visibleRect.width * visibleRect.height if area bestArea { bestArea area bestCell cell } } // 阈值保护面积小于Cell自身面积一半时不播放 if let cell bestCell, bestArea cell.bounds.width * cell.bounds.height * 0.5 { return nil } return bestCell }逻辑说明遍历visibleCells把每个Cell的bounds先转换到tableView坐标系再和tableView.bounds求交集这样拿到的是真正“露出来”的那部分矩形。面积的单位不重要重要的是同一坐标系下的相对比较。参数说明0.5这个阈值是我调过的经验值。阈值太高会导致快速滑过时永远不触发播放阈值太低又会在露出一点点时就开始加载。对分辨率较高的视频源0.40.5比较合理。另外注意convert(_:to:)的方向——用cell.convert(cell.bounds, to: tableView)而不是tableView.convert方向反了会出现诡异坐标偏移。3.3 播放器管理器统一挂载与销毁管理器对外只暴露一个play(in:url:)接口内部做了三件事移除旧Layer、创建新Player、设置当前播放状态final class ListVideoPlayerManager { static let shared ListVideoPlayerManager() private var player: AVPlayer? private var playerLayer: AVPlayerLayer? private(set) var currentState: PlayState .idle private var timeObserver: Any? func play(in containerView: UIView, url: URL) { stop() // 先清理旧状态 let item AVPlayerItem(url: url) let newPlayer AVPlayer(playerItem: item) newPlayer.automaticallyWaitsToMinimizeStalling true newPlayer.volume 1.0 let layer AVPlayerLayer(player: newPlayer) layer.videoGravity .resizeAspectFill layer.frame containerView.bounds layer.masksToBounds true containerView.layer.addSublayer(layer) self.player newPlayer self.playerLayer layer self.currentState .preparing // 等ready再播放避免首帧黑屏 item.addObserver(self, forKeyPath: #keyPath(AVPlayerItem.status), options: [.new], context: nil) newPlayer.play() currentState .playing } func stop() { guard player ! nil || playerLayer ! nil else { return } player?.pause() playerLayer?.removeFromSuperlayer() playerLayer nil player nil currentState .idle } deinit { if let observer timeObserver { player?.removeTimeObserver(observer) } } }逻辑说明stop()是每次播放前的必经之路。很多坑都是从“反正正在播放的就是同一个player不清理直接换item”的侥幸心理里出来的。旧Layer逐帧残留与音量叠加都会在复用后出现这个方法的pause removeFromSuperlayer 置nil顺序不能换。参数说明automaticallyWaitsToMinimizeStalling true会在网络不佳时自动延迟startPlayback换取更流畅的首帧体验。这里还有个坑playerLayer的frame在绑定那一刻固定如果Cell在视频加载期间被重新布局如旋转Layer还是旧尺寸。所以我一般会在Cell的layoutSubviews里再刷一次Layer的frame。3.4 Cell侧的配合prepareForReuse必清Cell这边要做的就一件事让复用机制不干扰播放器。两个地方必须处理——prepareForReuse里把videoContainer上的旧Layer清掉以及layoutSubviews里同步Layer尺寸class VideoCell: UITableViewCell { let videoContainer UIView() private var currentPlayerLayer: AVPlayerLayer? override func prepareForReuse() { super.prepareForReuse() // 关键一把上一轮绑定的播放器Layer从容器上摘下来 currentPlayerLayer?.removeFromSuperlayer() currentPlayerLayer nil // 关键二清掉可能残留的封面图、进度条 videoContainer.subviews.forEach { $0.removeFromSuperview() } } func bind(url: URL, thumbnail: UIImage?) { // 设置封面 let thumbImageView UIImageView(image: thumbnail) thumbImageView.frame videoContainer.bounds videoContainer.addSubview(thumbImageView) self.videoUrl url } override func layoutSubviews() { super.layoutSubviews() // 布局变化时同步layer尺寸避免播放画面变形或裁切错误 currentPlayerLayer?.frame videoContainer.bounds } }逻辑说明currentPlayerLayer这个引用是Cell自己的“记忆”记住当前Layer是为了在复用瞬间立刻移除。如果不做这一步旧Layer会被加到新装的AVPlayerLayer后面导致画面上出现两层视频图片叠影。参数说明封面图的添加时机要放在视频第一帧没就绪之前。实际项目中如果封面图下载时间不确定建议把封面和播放器Layer做成两个独立层封面图在视频状态变为ReadyToPlay后隐藏。4. 性能优化预加载、资源占用与内存峰值控制4.1 预加载只预热相邻的2条视频列表视频最大的交互痛点就是滑过去等加载转圈。网易视频这类应用的做法是“预加载”——提前把相邻Cell的AVPlayerItem初始化好但不add到播放器上。我实现时在滚动停止后只预加载当前播放那条的上下2条func preloadAdjacentItems(at indexPath: IndexPath) { guard let datasource dataSource else { return } // 只预加载相邻两条再多会抢主播放的网络带宽 let preloadIndexPaths [IndexPath(row: max(indexPath.row - 2, 0), section: 0), IndexPath(row: min(indexPath.row 2, datasource.count - 1), section: 0)] .filter { $0.row ! indexPath.row } for ip in preloadIndexPaths { let url datasource[ip.row].videoUrl // 用AVAsset资源预加载只初始化不创建player let asset AVURLAsset(url: url) let item AVPlayerItem(asset: asset) // 缓存到字典里等真正播放时直接取 preloadCache[url.absoluteString] item } }逻辑说明预加载的边界不是越多越好。上下各2条是我测试下来性价比最高的组合——用户最多从当前位置滑到第三个位置就停了再远的视频预加载了也大概率是浪费。参数说明AVPlayerItem初始化会自行建立连接但不会真正解码视频流所以预加载的代价主要是网络连接和少量内存。如果进入后台或用户停留超过30秒应该清空预加载缓存避免出现“预加载了一堆视频但根本没被看”的白白消耗。4.2 复用池与播放器Layer的分离设计列表滚动时Cell不断进出复用池但播放器Layer的挂载目标是Cell的videoContainer这就产生了一个矛盾Layer在A cell上播得好好的A滚出屏幕后如果把Layer remove掉再滚回来又要重新add。处理思路是“Layer不动Cell动”——播放器Manager持有Layer本身当播放中的Cell滚出屏幕时不remove Layer而是把Layer从A cell的container上移到列表外的一个占位View上这样Layer可以继续渲染但用户看不见。等A cell滚回视野时再移回去。这个方案也有个隐患Layer一直挂着播放视频声音还在走内存和CPU不会被释放。所以我做了一层保护——离屏超过阈值时间默认1.5秒就强制调用stop()。从用户感知上短时间离开再滑回来视频接着放长时间离开就不再浪费资源。4.3 内存峰值控制限制缓冲与及时释放视频列表最容易爆内存的其实是AVPlayerItem的缓冲机制。默认播放器会尽量往后缓冲网速好的时候一条视频能缓存几百MB到内存里。要做两个限制// 限制音频和视频缓冲时长 playerItem.preferredForwardBufferDuration 10 // App进后台时强制降内存 NotificationCenter.default.addObserver( forName: UIApplication.didEnterBackgroundNotification, object: nil, queue: .main ) { [weak self] _ in // 暂停但不销毁保留状态 self?.player?.pause() // 对AVPlayerItem调用seek(to:)可以刷新内部缓冲池 self?.player?.seek(to: .zero, toleranceBefore: .zero, toleranceAfter: .zero) }逻辑说明preferredForwardBufferDuration 10的含义是播放器最多往后预载10秒内容超过这个阈值就要清掉更早的缓冲。这个参数不是越大约好在高清大视频场景设20以上虽然流畅但内存压力大设太小又会在弱网下频繁加载导致卡顿。参数说明seek(to:toleranceBefore:toleranceAfter:)这里的作用完全不是用来跳转位置而是强制刷新AVPlayer内部缓冲。进后台时调用它可以把已解码的视频帧和音频缓冲释放掉我实测能降低30%左右的内存占用。4.4 首帧等待与封面兜底即使有预加载真正点开播放时依然有可能出现黑屏——最典型的场景是视频源是网络弱网环境AVPlayerItem还没ReadyToPlay播放器已经在播放状态但没有任何画面输出。必须在status变为readyToPlay后再开始显示播放器Layer在这之前用封面图兜底func observeValue(forKeyPath keyPath: String?, of object: Any?, change: [NSKeyValueChangeKey: Any]?, context: UnsafeMutableRawPointer?) { if keyPath #keyPath(AVPlayerItem.status), let item object as? AVPlayerItem { if item.status .readyToPlay { // 隐藏封面显示layer DispatchQueue.main.async { self.placeholderImageView.isHidden true } } else if item.status .failed { // 加载失败时显示重试按钮并打印具体错误 print(视频加载失败: \(item.error?.localizedDescription ?? )) } } }逻辑说明这里有个系统行为需要注意——status的观察回调发生在任意线程所以UI更新必须丢回主线程。另外failed状态不是靠play()就能恢复的需要重置item或者直接回到Manager层重新play一个新的url。参数说明不要在这里把placeholderImageView藏在任何Layer层它会变成复用的残留物。建议给placeholder一个独立的tagprepareForReuse时通过viewWithTag定位并移除。5. 避坑手记列表视频播放的六个常见坑5.1 复用了Cell上一秒的画面还留在新Cell上现象上滑列表后新的Cell出现时就带着一个旧视频的最后一帧过一两秒才被新视频的内容替换。原因Cell被复用后旧的AVPlayerLayer还挂在videoContainer.layer上。新播放器是addSublayer所以旧Layer还在底层新Layer在上层首帧加载慢时旧画面就露出来了。解决Cell在prepareForReuse里强制移除所有和播放相关的Layer同时给Layer设一个特殊的名字比如videoLayerKey用layer.sublayers?.first(where:)按名字清除避免误删封面图的layer。5.2 播放的声音先响画面要等1-2秒才出现现象滑动停止后立刻有声音但是黑屏过一下才有画面。原因AVPlayerItem处于preparing状态时播放器就开始播放了此时没有视频轨道数据输出只有音频先到位。解决播放器管理器里把play()的调用移到status .readyToPlay回调之后而不是创建完播放器立刻play。注意保留一个“待播放URL”的字段避免readyToPlay和最新的播放请求不一致——比如用户在加载还没完成时又滚到了一个新Cell旧URL ready了反而抢了播放权。5.3 来回快速滑动几次后内存飙升现象FPS掉到十几内存警告Level 2出现。原因快速滑动时每次停止都触发一次play、初始化新AVPlayerItem旧的预加载缓存没有及时清理加上cell复用过程产生大量临时layer对象。解决在预加载方法里加一层清理逻辑——只保留当前play请求的前后各2条item的缓存其余的直接赋nil释放另外设置preferredForwardBufferDuration 10我这边测试内存峰值能降到原来的60%左右。5.4 播放画面和声音不在同一个视频上现象看到的是A视频的画面听到的却是B视频的声音。原因之前的播放器还没stop新的play请求来了旧的player还在后台走音频输出。如果在同一时间点存在两个AVPlayer实例其中一个没被完全停止就会导致声画不同步。解决在Manager里给AVPlayer加一个“唯一约束”——play()方法里第一步先stop()并且stop里要把player置nil后再创建新player。我踩过一次因为想省性能只重新绑定playerItem结果旧player的音频线程一直没释放。5.5 播放中的Cell滚出屏幕后视频还在继续播现象用户把播放中的Cell滑出屏幕后声音仍然持续了2秒以上。原因滚动停止检测里没处理“当前播放的Cell是否还在可见区域”。如果bestCell还是旧的那个而它早已离开Screen可见范围就会继续播。解决findBestPlayCell()里先判断最佳候选IndexPath是否已不在tableView.indexPathsForVisibleRows中如果不在就直接返回nil并触发stop()。注意要放在可见性计算之前减少无意义的坐标转换。5.6 页面推入下一级后列表播放器还在播放声音现象点击视频Cell进入全屏播放页后返回列表时发现列表视频又从头开始播了或者列表页声音还在响。原因全屏播放时列表的AVPlayer没有被stop或者全屏页自己也建了一个播放器实例两个player共用同一个音频Session导致冲突。解决在全屏页面push前统一调用Manager的stop全屏页用独立的播放器实例。返回列表时不恢复之前播放的那个而是通过scrollViewDidEndDecelerating重新触发一次handleScrollStopIfNeeded()让用户回到列表后视频自动接着播。6. 进阶交互把视频列表做出“资讯App”的味道6.1 全局静音开关网易视频和今日头条都有“列表自动播放时静音”的交互。实现思路不是在播放器层改volume而是在Manager层记录一个isMutedWhenAutoPlay的开关播放时统一套用func setMuted(_ muted: Bool) { player?.isMuted muted }每次自动播放触发时调用setMuted(GlobalConfig.shared.isListMuted)。注意不要单独存储每个Cell的静音状态——Cell是可复用的状态存到Cell上会造成复用错乱。6.2 滑出屏幕再回来时的微小恢复对于列表视频完全从头播放是很打断体验的。我习惯把播放进度归一化处理每个Cell在bind时记录当前播放item的秒数滚动回来后如果在1秒内就继续从这个位置播。实现上Manager维护一个lastPlayedTimeMap字典key是URLvalue是播放秒数。每次播放器处于playing状态时用时间观察者定时刷新这个map确保记录的是最新位置。恢复时的代码func play(in containerView: UIView, url: URL) { stop() let item: AVPlayerItem if let lastTime Self.shared.lastPlayedTimeMap[url.absoluteString] { // 先seek到上次的位置再创建player let asset AVURLAsset(url: url) item AVPlayerItem(asset: asset) item.seek(to: CMTime(seconds: lastTime, preferredTimescale: 600)) } else { item AVPlayerItem(url: url) } // ... 后续逻辑 }6.3 监控FPS和网络切换的自动降级做资讯类视频Feed弱网下的降级策略很影响留存。我一般添加两个监控进入弱网时降低preferredForwardBufferDuration到3秒同时切换cover图而不是模糊封面网络恢复后恢复10秒。监控依赖Network框架的pathUpdateHandler注意不要把视频加载的卡顿直接当成断网——弱网每秒能下载的数据率仍在几十KB量级时应该只是减速而不是停止。降级逻辑写在Manager里否则每个Cell去单独判断会把代码搞得很碎。6.4 从工具方法到项目习惯我拆完这个资源后最大的收获不是某段代码而是它逼着我养成了一个习惯任何列表内的多媒体需求先画状态机再写Manager。从那以后我每次在列表里接播放器都会强制走一遍“滚动停止事件 → 候选Cell计算 → 播放器复用唯一约束 → 内存回收”这条链路踩坑率直线下降。这份资源的视频demo已经把大部分链路代码都写好了拿过去改改URL就能在模拟器上跑起来对照着我的这些参数调一遍希望帮到你。本文还有配套的精品资源点击获取