很多人一提到“Flutter播放視頻”第一反應(yīng)就是去翻第三方庫(kù)但其實(shí)官方插件video_player已經(jīng)能覆蓋絕大多數(shù)業(yè)務(wù)場(chǎng)景。我這次在一個(gè)舊項(xiàng)目里用的是Flutter 2.8.1Dart版本還停留在2.15左右沒(méi)有空安全之外的新特性加持很多新版本插件根本不敢升。所以干脆把video_player在這個(gè)版本下從集成到踩坑完整走了一遍這篇就把整個(gè)過(guò)程記錄下來(lái)供同樣被老版本鎖住手腳的開(kāi)發(fā)者參考。先交代一下背景項(xiàng)目是一個(gè)帶視頻播放的資訊類(lèi)App不需要直播、不需要復(fù)雜的DRM核心訴求是能穩(wěn)定播放MP4和HLS流支持橫豎屏切換在列表頁(yè)能復(fù)用播放器實(shí)例。選video_player的原因很簡(jiǎn)單官方維護(hù)、API穩(wěn)定、2.8.1版本兼容性沒(méi)問(wèn)題而且它內(nèi)部是基于各平臺(tái)原生播放器封裝Android底層是ExoPlayeriOS底層是AVPlayer性能和系統(tǒng)適配都交給原生層處理Flutter層只做狀態(tài)同步這對(duì)一個(gè)維護(hù)成本不高的小團(tuán)隊(duì)來(lái)說(shuō)是最合理的選擇。1. 為什么2.8.1這個(gè)版本值得單獨(dú)聊老版本的典型困局先說(shuō)版本問(wèn)題。2.8.1是2021年底發(fā)布的版本放到現(xiàn)在看確實(shí)不算新但很多存量項(xiàng)目就是跑在這個(gè)版本上原因無(wú)非是業(yè)務(wù)代碼量大、不想冒險(xiǎn)升級(jí)或者第三方SDK還沒(méi)適配新版Flutter。這個(gè)版本有幾個(gè)特點(diǎn)直接影響視頻播放方案的選擇。第一個(gè)特點(diǎn)是Dart 2.15不支持最新的空安全語(yǔ)法演進(jìn)很多插件的最新版本已經(jīng)放棄了對(duì)它的支持。video_player目前最新的2.x版本需要更高的Flutter版本但2.8.1對(duì)應(yīng)的video_player版本大概在2.2.x左右這個(gè)版本號(hào)區(qū)間內(nèi)API基本穩(wěn)定功能足夠用。挑版本的時(shí)候不能無(wú)腦拉最新要看插件的pubspec.yaml里聲明的environment約束。第二個(gè)特點(diǎn)是2.8.1時(shí)代的熱重載對(duì)原生播放器狀態(tài)恢復(fù)并不完美。如果你在播放視頻時(shí)改了Dart層的代碼觸發(fā)熱重載經(jīng)常會(huì)出現(xiàn)畫(huà)面黑屏但音頻還在播放的詭異狀態(tài)。這不是你代碼的問(wèn)題是插件內(nèi)部的原生播放器實(shí)例沒(méi)有跟著Flutter框架一起重建導(dǎo)致的。后面我會(huì)專(zhuān)門(mén)講這個(gè)坑。第三個(gè)特點(diǎn)是你需要用apply方式在老版本里配Gradle插件?，F(xiàn)在新建Flutter項(xiàng)目默認(rèn)用pluginsDSL2.8.1的項(xiàng)目還是apply腳本式配置一旦要改Android端的構(gòu)建腳本很多新文檔里的寫(xiě)法直接抄會(huì)報(bào)錯(cuò)。所以這篇博文不是寫(xiě)給“最新版Flutter用戶(hù)”看的而是寫(xiě)給那批和我一樣被2.8.1鎖定、又想穩(wěn)定播放視頻的開(kāi)發(fā)者。如果你用的是3.x以上版本有些操作可以簡(jiǎn)化但整體思路依然通用。2. 從pubspec到第一個(gè)能出畫(huà)面的播放器完整搭建過(guò)程2.1 版本鎖定與依賴(lài)引入在pubspec.yaml里加依賴(lài)的時(shí)候我建議直接鎖版本不要用^符號(hào)放開(kāi)上限。因?yàn)镕lutter 2.8.1對(duì)video_player的具體兼容版本是有邊界的我用的是2.2.10這個(gè)版本在2.8.1上實(shí)測(cè)穩(wěn)定Android和iOS的端上都沒(méi)有出現(xiàn)編譯錯(cuò)誤。dependencies: flutter: sdk: flutter video_player: 2.2.10加了依賴(lài)之后執(zhí)行flutter pub get如果網(wǎng)絡(luò)環(huán)境不太好可能會(huì)卡在解析依賴(lài)階段。這里有個(gè)老版本的項(xiàng)目級(jí)小技巧優(yōu)先檢查本地的pubspec.lock里是否已經(jīng)有兼容版本緩存如果有可以用flutter pub get --offline快速完成拉取實(shí)測(cè)在CI環(huán)境里能省不少時(shí)間。2.2 Android端的必要配置video_player在Android上要求最低API 212.8.1默認(rèn)生成的項(xiàng)目模板里minSdkVersion是16如果不改編譯階段就會(huì)報(bào)錯(cuò)。必須在android/app/build.gradle里把minSdkVersion提到21。android { defaultConfig { minSdkVersion 21 // ... } }這個(gè)改動(dòng)不涉及業(yè)務(wù)代碼但漏掉的人特別多因?yàn)閳?bào)錯(cuò)信息往往要到flutter build apk的階段才會(huì)暴露出來(lái)而且錯(cuò)誤提示是Gradle構(gòu)建失敗第一眼根本想不到是minSdkVersion的問(wèn)題。另外AndroidManifest不需要額外加網(wǎng)絡(luò)權(quán)限因?yàn)関ideo_player的Android實(shí)現(xiàn)已經(jīng)在插件清單里聲明了INTERNET權(quán)限。但如果你的項(xiàng)目在release包里去掉了插件的清單合并就要自己確認(rèn)一下。2.3 iOS端的Info.plist配置iOS端只做本地視頻播放的話(huà)不需要特殊配置如果播放網(wǎng)絡(luò)視頻則需要確保App Transport Security允許HTTP明文請(qǐng)求。我在調(diào)試階段經(jīng)常用局域網(wǎng)內(nèi)的測(cè)試視頻源很多是HTTP協(xié)議的所以需要在ios/Runner/Info.plist里臨時(shí)加上NSAppTransportSecurity的NSAllowsArbitraryLoads。keyNSAppTransportSecurity/key dict keyNSAllowsArbitraryLoads/key true/ /dict上線前如果視頻源全部是HTTPS這段配置可以刪掉否則App Store審核會(huì)有風(fēng)險(xiǎn)提示。2.4 一個(gè)最小可用的播放器頁(yè)面下面這段代碼是能跑起來(lái)的最短實(shí)現(xiàn)包含創(chuàng)建控制器、初始化、播放、暫停、銷(xiāo)毀的完整生命周期。我用的是StatefulWidget因?yàn)榭刂破鞅仨毟鳶tate的生命周期走。import package:flutter/material.dart; import package:video_player/video_player.dart; class SimplePlayerPage extends StatefulWidget { final String url; const SimplePlayerPage({Key? key, required this.url}) : super(key: key); override StateSimplePlayerPage createState() _SimplePlayerPageState(); } class _SimplePlayerPageState extends StateSimplePlayerPage { late VideoPlayerController _controller; late Futurevoid _initializeFuture; override void initState() { super.initState(); _controller VideoPlayerController.network(widget.url); _initializeFuture _controller.initialize(); } override void dispose() { _controller.dispose(); super.dispose(); } Futurevoid _togglePlay() async { await _initializeFuture; if (_controller.value.isPlaying) { await _controller.pause(); } else { await _controller.play(); } setState(() {}); } override Widget build(BuildContext context) { return Scaffold( appBar: AppBar(title: const Text(視頻播放)), body: FutureBuilder( future: _initializeFuture, builder: (context, snapshot) { if (snapshot.connectionState ! ConnectionState.done) { return const Center(child: CircularProgressIndicator()); } if (snapshot.hasError) { return Center(child: Text(加載失敗: $snapshot.error)); } return GestureDetector( onTap: _togglePlay, child: Center( child: AspectRatio( aspectRatio: _controller.value.aspectRatio, child: VideoPlayer(_controller), ), ), ); }, ), ); } }這段代碼有一個(gè)細(xì)節(jié)很多人會(huì)忽略_togglePlay里必須先await _initializeFuture因?yàn)槿绻脩?hù)在網(wǎng)絡(luò)較慢時(shí)快速點(diǎn)擊畫(huà)面控制器還沒(méi)初始化完成就去調(diào)play()底層原生播放器會(huì)直接拋異常。把FutureBuilder和點(diǎn)擊事件里的await結(jié)合起來(lái)可以保證任何操作都在初始化完成之后執(zhí)行。3. 核心API的調(diào)用邏輯與播放器狀態(tài)機(jī)搞懂這幾個(gè)方法就夠用video_player的API其實(shí)不復(fù)雜核心對(duì)象就是VideoPlayerController它內(nèi)部通過(guò)一個(gè)VideoPlayerValue對(duì)象承載當(dāng)前播放狀態(tài)。你在頁(yè)面上做的所有操作本質(zhì)上都是修改這個(gè)Value然后觸發(fā)notifyListeners讓VideoPlayer控件重建渲染紋理。3.1 控制器的創(chuàng)建選型創(chuàng)建控制器有三條路network、file、asset。大部分業(yè)務(wù)場(chǎng)景用的是network它的初始化會(huì)異步完成視頻源的探測(cè)和首幀加載。這里有個(gè)關(guān)鍵點(diǎn)initialize()返回的Future一旦完成value.isInitialized就會(huì)變成true同時(shí)value.duration、value.aspectRatio才會(huì)被正確填充。所以在FutureBuilder里判斷初始化狀態(tài)是最穩(wěn)妥的做法。file模式用于本地文件播放比如下載到應(yīng)用沙盒里的視頻。注意file模式傳的是File對(duì)象路徑必須是應(yīng)用可訪問(wèn)的目錄asset模式打包在安裝包里適合放一些引導(dǎo)視頻、說(shuō)明視頻。3.2 播放控制與進(jìn)度監(jiān)聽(tīng)play()和pause()都是異步方法這也意味著調(diào)用后的狀態(tài)變化不是立即生效的。如果想要精確控制UI建議通過(guò)監(jiān)聽(tīng)VideoPlayerValue而不是在調(diào)用后立刻讀狀態(tài)。系統(tǒng)提供了addListener回調(diào)我一般會(huì)在頁(yè)面里加一個(gè)setState來(lái)刷新進(jìn)度條。_controller.addListener(() { if (!mounted) return; setState(() {}); });這里的mounted判斷極其重要因?yàn)榭刂破髟诓シ磐瓿珊笥锌赡芤呀?jīng)進(jìn)入dispose流程異步回調(diào)觸發(fā)的setState會(huì)導(dǎo)致“setState called after dispose”的運(yùn)行時(shí)錯(cuò)誤。我見(jiàn)過(guò)很多線上崩潰都發(fā)生在頁(yè)面已關(guān)閉但播放器的監(jiān)聽(tīng)還在回調(diào)的場(chǎng)景。進(jìn)度條通常需要當(dāng)前播放位置和總時(shí)長(zhǎng)從controller.value.position和controller.value.duration里取。position是Duration類(lèi)型長(zhǎng)時(shí)間播放后精確到毫秒直接顯示沒(méi)必要一般格式化成mm:ss。3.3 橫豎屏切換的正確姿勢(shì)視頻播放頁(yè)最常見(jiàn)的一個(gè)需求是旋轉(zhuǎn)屏幕時(shí)播放器跟隨旋轉(zhuǎn)。video_player本身不管屏幕方向它只管視頻紋理的寬高比。屏幕方向需要自己借助SystemChrome.setPreferredOrientations來(lái)控制。// 進(jìn)入全屏 await SystemChrome.setPreferredOrientations([ DeviceOrientation.landscapeLeft, DeviceOrientation.landscapeRight, ]); // 退出全屏 await SystemChrome.setPreferredOrientations([ DeviceOrientation.portraitUp, ]);這里有個(gè)體驗(yàn)細(xì)節(jié)切換方向之后播放器頁(yè)面的build方法會(huì)重新執(zhí)行如果你是用AspectRatio(aspectRatio: controller.value.aspectRatio)包裹視頻的畫(huà)面會(huì)自適應(yīng)新的屏幕寬高不會(huì)變形。但是如果你直接給VideoPlayer設(shè)置了固定寬高旋轉(zhuǎn)后就會(huì)出現(xiàn)黑邊或者拉伸。切換到全屏?xí)r還要注意隱藏系統(tǒng)UI我一般會(huì)用SystemChrome.setEnabledSystemUIMode(SystemUiMode.immersiveSticky)把狀態(tài)欄和導(dǎo)航欄一起隱藏掉退出全屏?xí)r再改回SystemUiMode.edgeToEdge。3.4 播放器的狀態(tài)監(jiān)聽(tīng)閉環(huán)完整的狀態(tài)機(jī)大概是下面這串初始化中 → 初始化完成 → 播放中 → 暫停中 → 播放完成 → 釋放。VideoPlayerValue里有一個(gè)isPlaying屬性標(biāo)識(shí)播放狀態(tài)還有一個(gè)isCompleted標(biāo)識(shí)是否播放到末尾。播放完成后如果想重新播放不能直接調(diào)用play()必須先seekTo(Duration.zero)再play()否則部分設(shè)備會(huì)無(wú)響應(yīng)。4. 雙端平臺(tái)適配里最容易栽的坑Android和iOS的差異實(shí)錄4.1 Android音頻焦點(diǎn)與后臺(tái)播放的沖突video_player在Android上默認(rèn)會(huì)請(qǐng)求音頻焦點(diǎn)。如果你正在播放視頻這時(shí)候來(lái)了一條系統(tǒng)通知或者另一個(gè)應(yīng)用開(kāi)始播放音頻你的視頻聲音會(huì)被系統(tǒng)壓低或者直接暫停。這是ExoPlayer的默認(rèn)行為不一定是你代碼里的問(wèn)題。處理方式是在初始化控制器時(shí)設(shè)置VideoPlayerOptions的mixWithOthers屬性。我實(shí)測(cè)過(guò)這個(gè)屬性在2.2.10版本里是可用的設(shè)置成true之后視頻聲音會(huì)和其它音頻混音輸出不會(huì)互相打斷。_controller VideoPlayerController.network( widget.url, videoPlayerOptions: VideoPlayerOptions(mixWithOthers: true), );但如果你的App定位是視頻播放器用戶(hù)一般期望在看視頻的時(shí)候暫停其它聲音那就不應(yīng)該開(kāi)這個(gè)選項(xiàng)。4.2 iOS靜音模式下的播放行為iOS端的坑更隱蔽。iPhone的靜音撥片默認(rèn)會(huì)同時(shí)讓AVPlayer的音頻輸出變成靜音但video_player插件的實(shí)際表現(xiàn)取決于AVAudioSession的配置。簡(jiǎn)單說(shuō)如果你希望用戶(hù)即便在靜音模式下也能聽(tīng)到視頻聲音就必須在播放前激活音頻會(huì)話(huà)。video_player官方文檔沒(méi)有直接暴露這個(gè)配置但可以通過(guò)在iOS原生工程里添加一段音頻會(huì)話(huà)配置來(lái)實(shí)現(xiàn)。我在AppDelegate.swift里加過(guò)下面這段let audioSession AVAudioSession.sharedInstance() try? audioSession.setCategory(.playback, mode: .moviePlayback) try? audioSession.setActive(true)加完之后靜音模式下視頻依然有聲音。如果你的業(yè)務(wù)場(chǎng)景更希望尊重系統(tǒng)靜音設(shè)置那就不動(dòng)這個(gè)只在普通模式下播放。4.3 頁(yè)面切后臺(tái)后的播放器行為實(shí)測(cè)發(fā)現(xiàn)2.8.1版本的video_player在App進(jìn)入后臺(tái)后視頻畫(huà)面會(huì)凍結(jié)但音頻不會(huì)立即停止Android和iOS的表現(xiàn)還不一致。這非?？简?yàn)生命周期管理。我的做法是監(jiān)聽(tīng)WidgetsBindingObserver的生命周期回調(diào)在AppLifecycleState.paused時(shí)主動(dòng)pause()在resumed時(shí)恢復(fù)播放。如果你確實(shí)需要后臺(tái)繼續(xù)播放聲音那不能靠這個(gè)插件要引入audio_service這類(lèi)專(zhuān)門(mén)的后臺(tái)音頻插件視頻畫(huà)面在后臺(tái)本來(lái)就是不可能繼續(xù)渲染的。5. 列表頁(yè)復(fù)用播放器實(shí)例不止一種姿勢(shì)單頁(yè)面播放沒(méi)有難度難點(diǎn)在于列表頁(yè)里做“點(diǎn)擊即播放”的體驗(yàn)。短視頻App那種無(wú)限滑動(dòng)自動(dòng)播放的效果用video_player也能做但有幾個(gè)架構(gòu)上的決策決定了后續(xù)維護(hù)是否順暢。5.1 多實(shí)例 vs 單實(shí)例我是怎么取舍的很多人在列表頁(yè)里給每個(gè)item創(chuàng)建一個(gè)VideoPlayerController滑動(dòng)離開(kāi)時(shí)再銷(xiāo)毀。這種做法在數(shù)據(jù)量小的時(shí)候沒(méi)毛病但一旦列表超過(guò)20個(gè)item每個(gè)item都持有原生播放器實(shí)例內(nèi)存會(huì)迅速飆升。我的方案是維護(hù)一個(gè)全局單例播放管理器整個(gè)列表頁(yè)只持有一個(gè)控制器實(shí)例。當(dāng)用戶(hù)點(diǎn)擊某個(gè)item時(shí)把播放器“綁定”到當(dāng)前item用戶(hù)滑走或者點(diǎn)擊下一個(gè)item時(shí)先釋放當(dāng)前控制器的視頻源再加載新的視頻源。class VideoPlayManager { VideoPlayManager._(); static final VideoPlayManager instance VideoPlayManager._(); VideoPlayerController? _controller; int? currentIndex; Futurevoid playVideo(String url, int index) async { if (_controller ! null) { await _controller!.pause(); await _controller!.dispose(); } currentIndex index; _controller VideoPlayerController.network(url); await _controller!.initialize(); await _controller!.play(); } }這個(gè)單例的好處是內(nèi)存占用可控切換視頻時(shí)的狀態(tài)管理集中在一個(gè)文件里排查問(wèn)題時(shí)思路清晰。缺點(diǎn)是切換視頻會(huì)先銷(xiāo)毀再創(chuàng)建中間存在一個(gè)短暫的空窗體驗(yàn)上會(huì)有一瞬間的停頓。5.2 用ValueNotifier驅(qū)動(dòng)列表UI刷新列表頁(yè)的每個(gè)item都不需要自己持有VideoPlayerController而是監(jiān)聽(tīng)播放管理器里的當(dāng)前播放索引。我用一個(gè)ValueNotifierint來(lái)標(biāo)記當(dāng)前正在播放的item序號(hào)item內(nèi)部通過(guò)ValueListenableBuilder決定自己是否顯示VideoPlayer控件。這樣列表刷新很干凈——正在播放的item重建一次其它item完全不參與重建滾動(dòng)性能影響很小。如果你用setState刷新整個(gè)列表那在低端安卓機(jī)上滑動(dòng)時(shí)會(huì)有肉眼可見(jiàn)的掉幀。5.3 滑動(dòng)列表時(shí)播放器失效的處理方案在ListView里直接放VideoPlayer控件有一個(gè)隱患item被回收或者移出視圖樹(shù)后播放器的紋理可能會(huì)失效。即使控制器還沒(méi)銷(xiāo)毀畫(huà)面也會(huì)變成黑屏。解決辦法是在ListView的itemBuilder里判斷當(dāng)前item是否可見(jiàn)不可見(jiàn)就移除VideoPlayer控件但保留控制器可見(jiàn)時(shí)重新掛載。重新掛載后VideoPlayer會(huì)從控制器當(dāng)前的position處繼續(xù)渲染不會(huì)跳回開(kāi)頭。這個(gè)特性對(duì)體驗(yàn)很重要我實(shí)驗(yàn)過(guò)多次只要不銷(xiāo)毀控制器重新掛載控件不會(huì)導(dǎo)致播放進(jìn)度丟失。6. 性能調(diào)優(yōu)與播放體驗(yàn)細(xì)節(jié)從卡頓到流暢的差距在哪兒6.1 視頻解碼的“隱形成本”和緩沖策略video_player底層是系統(tǒng)解碼器視頻流的編碼格式直接影響性能。H.264是兼容性最好的選擇H.265HEVC雖然壓縮率高但在老設(shè)備上解碼器可能不支持播放時(shí)會(huì)卡頓甚至黑屏。用網(wǎng)絡(luò)視頻源時(shí)建議后端優(yōu)先輸出H.264AAC的MP4格式保證2.8.1版本的播放器在絕大多數(shù)設(shè)備上都能流暢工作。緩沖策略上VideoPlayerController默認(rèn)的緩沖行為是“等到有足夠數(shù)據(jù)再開(kāi)始播放”網(wǎng)絡(luò)差時(shí)表現(xiàn)為進(jìn)度條轉(zhuǎn)圈很久才能出畫(huà)面。如果想盡快出畫(huà)面可以設(shè)置videoPlayerOptions里的httpHeaders配合服務(wù)端做分片請(qǐng)求不過(guò)這取決于你的視頻源是否支持Range請(qǐng)求。實(shí)測(cè)下來(lái)支持Range的MP4在弱網(wǎng)下起播速度明顯優(yōu)于不支持Range的源。6.2 畫(huà)面質(zhì)量與清晰度的控制VideoPlayer控件本身不做清晰度切換清晰度切換屬于業(yè)務(wù)邏輯不同的清晰度對(duì)應(yīng)不同的URL。實(shí)現(xiàn)方式是在頁(yè)面頂部或側(cè)邊欄放一個(gè)清晰度選擇按鈕點(diǎn)擊后重建一個(gè)指向新URL的控制器并從當(dāng)前進(jìn)度位置繼續(xù)播放。Futurevoid switchQuality(String newUrl) async { final position _controller.value.position; final wasPlaying _controller.value.isPlaying; await _controller.dispose(); _controller VideoPlayerController.network(newUrl); await _controller.initialize(); await _controller.seekTo(position); if (wasPlaying) { await _controller.play(); } setState(() {}); }這里要注意的是dispose后再initialize的間隙控制器是null狀態(tài)UI層需要加一個(gè)標(biāo)志位避免空指針崩潰。我在切換清晰度時(shí)會(huì)彈一個(gè)居中的加載圈等新控制器初始化完成再關(guān)掉。6.3 渲染層面的紋理更新機(jī)制VideoPlayer的實(shí)現(xiàn)原理是Flutter通過(guò)Texture控件把原生播放器的圖像幀傳到GPU渲染層。在2.8.1版本里紋理更新走的是TextureId的同步機(jī)制如果你在同一幀里同時(shí)操作多個(gè)播放器紋理有極小概率出現(xiàn)畫(huà)面撕裂。這屬于引擎底層的邊緣情況普通項(xiàng)目不會(huì)碰到但我在做“一個(gè)頁(yè)面同時(shí)畫(huà)中畫(huà)播放兩個(gè)視頻”時(shí)確實(shí)遇到過(guò)。如果業(yè)務(wù)上有同時(shí)播放多個(gè)視頻的需求建議限制為最多兩個(gè)實(shí)例并且錯(cuò)開(kāi)播放的啟停時(shí)間避免在同一幀里同時(shí)做控制器的狀態(tài)變更。7. 配合Provider做全局播放狀態(tài)從播放器到業(yè)務(wù)組件的通信很多項(xiàng)目里播放器不只是孤立的一個(gè)頁(yè)面它往往需要和評(píng)論區(qū)、分享按鈕、消息紅點(diǎn)等業(yè)務(wù)組件聯(lián)動(dòng)。這時(shí)候只靠頁(yè)面內(nèi)部的setState就不夠了需要把播放狀態(tài)提升到全局。Flutter 2.8.1時(shí)代最常用的方案是Provider配合ChangeNotifier可以很自然地實(shí)現(xiàn)跨頁(yè)面通信。我在這類(lèi)需求里的做法是定義一個(gè)VideoPlayerProvider持有控制器引用和播放狀態(tài)然后通過(guò)ChangeNotifierProxyProvider把它掛在頂層路由下。class VideoPlayerProvider extends ChangeNotifier { VideoPlayerController? controller; bool isMuted false; double playbackSpeed 1.0; void attachController(VideoPlayerController c) { controller?.removeListener(_onControllerUpdate); controller c; controller?.addListener(_onControllerUpdate); notifyListeners(); } void _onControllerUpdate() { notifyListeners(); } void toggleMute() { isMuted !isMuted; controller?.setVolume(isMuted ? 0 : 1); notifyListeners(); } void setSpeed(double speed) { playbackSpeed speed; controller?.setPlaybackSpeed(speed); notifyListeners(); } }列表頁(yè)、詳情頁(yè)、懸浮窗都可以通過(guò)context.readVideoPlayerProvider()拿到同一個(gè)播放狀態(tài)。有個(gè)優(yōu)點(diǎn)要說(shuō)清楚這個(gè)方案把“播放器”從“頁(yè)面”里徹底解耦了頁(yè)面銷(xiāo)毀播放器不一定銷(xiāo)毀。如果你想在App的迷你懸浮窗里繼續(xù)播放列表頁(yè)的視頻這個(gè)架構(gòu)是必須的。不過(guò)要提醒一點(diǎn)全局持有播放器意味著你要有等價(jià)全局的dispose時(shí)機(jī)。我是讓Provider的頂層ChangeNotifierProxyProvider隨著App退出時(shí)才銷(xiāo)毀不能隨頁(yè)面銷(xiāo)毀。否則頁(yè)面銷(xiāo)毀后想再播放就沒(méi)有控制器可用。8. 日志、異常與線上問(wèn)題的排查手段播放黑屏別慌視頻播放類(lèi)問(wèn)題很多是偶發(fā)性的在開(kāi)發(fā)機(jī)上復(fù)現(xiàn)不出來(lái)上線后用戶(hù)那邊就報(bào)黑屏。我的經(jīng)驗(yàn)是一定要在initialize()失敗時(shí)打出完整錯(cuò)誤信息并在VideoPlayerValue里記錄播放器狀態(tài)方便線上日志反推。8.1 初始化失敗的常見(jiàn)原因排查initialize()返回的Future如果拋出異常最常見(jiàn)的是網(wǎng)絡(luò)視頻地址無(wú)法訪問(wèn)、跨域問(wèn)題、視頻格式不被解碼器支持。在catchError里多打一層日志至少記錄URL、HTTP狀態(tài)碼、異常類(lèi)型。有一回我排查線上黑屏日志里只有一條PlatformException根本看不出是網(wǎng)絡(luò)問(wèn)題還是解碼問(wèn)題。后來(lái)我在initialize前先做一次http.Head請(qǐng)求確認(rèn)視頻文件是否存在、是否支持Range請(qǐng)求把這兩層信息拼在一起問(wèn)題立刻定位到源站沒(méi)有開(kāi)啟Range支持。8.2 用Flutter自帶工具觀察紋理狀態(tài)Flutter 2.8.1的WidgetInspector里可以看到Texture控件的textureId。如果播放器正常這個(gè)ID應(yīng)該是一個(gè)穩(wěn)定遞增的數(shù)字如果畫(huà)面黑屏可以先看這個(gè)ID是否變化。ID不變說(shuō)明原生播放器的幀沒(méi)有上新是解碼或渲染鏈路的問(wèn)題ID一直在變但畫(huà)面黑屏則可能是渲染層被其它控件遮擋并不是播放器的問(wèn)題。這個(gè)排查思路可以幫你快速區(qū)分前端布局問(wèn)題和后端播放問(wèn)題省去盲目改代碼的時(shí)間。8.3 常見(jiàn)異常與應(yīng)對(duì)速查下面整理這份異常速查表來(lái)自我項(xiàng)目里遇到的真實(shí)問(wèn)題。異?，F(xiàn)象可能原因處理辦法初始化超時(shí)進(jìn)度圈一直轉(zhuǎn)網(wǎng)絡(luò)源響應(yīng)太慢或URL失效給initialize()加超時(shí)包裹超時(shí)后提示用戶(hù)重試播放幾分鐘后畫(huà)面卡死視頻源服務(wù)端未正確響應(yīng)Range分片檢查源站是否緩存完整文件調(diào)整CDN配置音頻正常但畫(huà)面不動(dòng)紋理ID未刷新多為熱重載遺留狀態(tài)完全停止App重新啟動(dòng)避免在熱重載狀態(tài)下調(diào)試播放器iOS無(wú)聲音AVAudioSession未配置播放模式參考4.2配置session categoryAndroid閃退minSdkVersion低于21檢查build.gradle配置列表快速滑動(dòng)時(shí)卡頓多個(gè)控制器實(shí)例同時(shí)存活改用單例管理器銷(xiāo)毀不可見(jiàn)item的播放器9. 善用播放速率與控制邏輯不常見(jiàn)的但好用的功能video_player除了基礎(chǔ)播放暫停還有幾個(gè)被低估的能力。一個(gè)是setPlaybackSpeed可以控制倍速播放我用它做了“長(zhǎng)按加速預(yù)覽”的功能。另一個(gè)是setVolume音量控制范圍是0到1。還有一個(gè)是seekTo的毫秒級(jí)精確定位可以用來(lái)做視頻里的小節(jié)跳轉(zhuǎn)。倍速播放有一個(gè)隱藏坑iOS上AVPlayer對(duì)倍速的支持是通過(guò)rate屬性實(shí)現(xiàn)Android上ExoPlayer則會(huì)把播放速度應(yīng)用到音頻解碼器。兩者對(duì)倍速的邊界值限制不同iOS支持0.5到2.0Android部分設(shè)備最大只能到1.5超出范圍會(huì)靜默失敗。我在做快進(jìn)預(yù)覽時(shí)用了2.0倍速在部分Android設(shè)備上沒(méi)有效果后來(lái)統(tǒng)一封裝成1.5倍兼容性才穩(wěn)定。播放速率改變后VideoPlayerValue.isPlaying不會(huì)變化但實(shí)際播放進(jìn)度會(huì)變快進(jìn)度條如果用position / duration來(lái)計(jì)算會(huì)自動(dòng)正確顯示這一點(diǎn)不用額外處理。10. 從一個(gè)插件到一個(gè)基礎(chǔ)播放組件沉淀下來(lái)的通用封裝最后說(shuō)說(shuō)我把video_player封裝成團(tuán)隊(duì)通用組件的經(jīng)驗(yàn)。直接在每個(gè)頁(yè)面里寫(xiě)控制器和FutureBuilder代碼重復(fù)度太高而且很容易埋坑。我沉淀了一個(gè)AppVideoPlayer組件對(duì)外只暴露三個(gè)參數(shù)視頻地址、是否自動(dòng)播放、播放狀態(tài)回調(diào)。內(nèi)部邏輯包含控制器生命周期管理、生命周期觀察頁(yè)面進(jìn)入后臺(tái)自動(dòng)暫停、播放完成通知、網(wǎng)絡(luò)狀態(tài)兜底提示。這個(gè)組件本質(zhì)上是一個(gè)“帶殼的播放器”業(yè)務(wù)方拿到任何一個(gè)視頻URL都能播放不需要關(guān)心平臺(tái)差異和生命周期細(xì)節(jié)。組件里一個(gè)關(guān)鍵點(diǎn)是對(duì)外暴露provider對(duì)象而不是暴露一堆控制方法。這樣外層頁(yè)面可以拿到播放器實(shí)例做進(jìn)度條聯(lián)動(dòng)、清晰度切換但不會(huì)跳過(guò)組件內(nèi)部的生命周期管理。給團(tuán)隊(duì)用的時(shí)候還有個(gè)小細(xì)節(jié)命名空間和版本號(hào)要寫(xiě)清楚。video_player在2.x版本之間API有細(xì)微差別如果不同業(yè)務(wù)線用了不同的組件版本日志和調(diào)試信息會(huì)非常混亂。我建議在主項(xiàng)目的pubspec.yaml里統(tǒng)一鎖定版本號(hào)子模塊不要各自維護(hù)播放器依賴(lài)。從2.8.1這個(gè)稍微“過(guò)時(shí)”的版本出發(fā)把官方video_player吃透之后你會(huì)發(fā)現(xiàn)它比想象中可靠得多。大部分播放問(wèn)題不是因?yàn)椴寮恍卸羌煞绞?、生命周期控制、平臺(tái)差異適配這三層沒(méi)有處理干凈。我個(gè)人體會(huì)是視頻播放器的核心不是API調(diào)用而是狀態(tài)管理和平臺(tái)細(xì)節(jié)的兜底能力這兩塊做到位直播、點(diǎn)播、短視頻、長(zhǎng)視頻都能在一套架構(gòu)上自然擴(kuò)展。最后再分享一個(gè)小技巧調(diào)試視頻播放問(wèn)題的時(shí)候盡量用真實(shí)設(shè)備而不是模擬器模擬器上的解碼器表現(xiàn)和真機(jī)差距很大很多你以為的代碼問(wèn)題換到真機(jī)上根本不復(fù)現(xiàn)。這個(gè)習(xí)慣能幫你省掉至少一半的無(wú)用排查時(shí)間。