MediaBrowser 常见问题避坑指南：开发者最常踩的 8 个坑及解决方案

MediaBrowser 常见问题避坑指南：开发者最常踩的 8 个坑及解决方案

【免费下载链接】MediaBrowser🏞 A simple iOS photo and video browser with optional grid view, captions and selections written in Swift5.0项目地址: https://gitcode.com/gh_mirrors/me/MediaBrowser

MediaBrowser是一个用 Swift 编写的 iOS 图片与视频浏览框架，支持网格视图、字幕、多选、手势缩放等丰富功能，还内置了基于 SDWebImage 的图片缓存，是很多开发者快速搭建媒体浏览器的首选。不过在实际集成中，新手经常遇到白屏、图片不显示、莫名崩溃等问题。本文结合 MediaBrowser 源码与官方 Demo，整理了开发者最常踩的 8 个坑及对应解决方案，帮你少走弯路。

坑 1：进入页面一片空白 —— 忘记实现必需的代理方法

MediaBrowser 的一切数据都来自MediaBrowserDelegate，其中numberOfMedia(in:)和media(for:at:)是必需方法（见 MediaBrowserDelegate.swift）。如果没实现，或者返回的媒体数量为 0，浏览器自然一片空白。

解决方案：像 ViewController.swift 中的 Demo 那样，通过 extension 实现代理，并保证numberOfMedia返回的数量与实际数组一致，避免media(for:at:)越界。

坑 2：网络图片加载不出来 —— 被 ATS 明文传输限制拦截

Media支持直接传入 URL 加载网络图片（内部走 SDWebImage）。但 Demo 中的网络图片全部是 HTTPS 地址（见 DemoData.swift 的webPhotos()）。如果你换成 HTTP 链接，iOS 的 ATS 安全策略会默认拦截，导致图片一直加载失败，最终显示灰色错误占位图。

解决方案：在 Info.plist 中配置NSAppTransportSecurity，允许任意加载，或仅对特定域名设置例外，让 HTTP 图片也能正常展示。

坑 3：崩溃fatalError("MediaBrowser Instance Reuse")—— 实例被复用了

这是新手最容易吓一跳的崩溃。源码 MediaBrowser.swift 的willMove(toParent:)中明确写了：同一个 MediaBrowser 实例不能重复 push/present。

解决方案：每次进入浏览页都新建一个实例，例如：

let browser = MediaBrowser(delegate: self) navigationController?.pushViewController(browser, animated: true)

Demo 中 ViewController.swift 的didSelectRowAt每次都会 new 一个新的 browser，就是这个原因。

坑 4：网格视图缩略图空白 —— 没实现 thumbnail 代理

开启enableGrid后，网格页需要thumbnail(for:at:)返回缩略图。该方法是可选的，默认返回空的Media()，于是网格里全是空白或一直转圈。

解决方案：实现thumbnail(for:at:)，并尽量返回小尺寸图片；Demo 中用thumbs数组维护缩略图，代码同样可参考 ViewController.swift。

坑 5：初始页不对、预缓存失效 —— 顺序搞反了

在 MediaBrowser+Paging.swift 的setCurrentIndex(at:)中，注释特别强调：开启preCachingEnabled之前必须先调用setCurrentIndex(at:)。顺序反了，预缓存会从第 0 页开始，导致首屏体验变差。

解决方案：先设置索引再开启预缓存：

browser.setCurrentIndex(at: 2) browser.preCachingEnabled = true

坑 6：视频不自动播放

设置了autoPlayOnAppear = true却发现视频不播？源码中该逻辑只在第一次viewDidAppear且当前页是视频时触发。如果首次展示的不是视频页，或页面已出现过再返回，都不会自动播放。

解决方案：利用didDisplayMedia回调自行控制播放时机，或确保首次进入的就是视频页（Demo 的singleVideo场景即是如此）。

坑 7：相册图片加载慢或不显示 —— 权限与 iCloud

通过Media(asset:targetSize:)从相册加载时，必须在 Info.plist 配置NSPhotoLibraryUsageDescription，否则直接崩溃。另外，加载 iCloud 图片时虽然源码（Media.swift）已开启isNetworkAccessAllowed = true，但首次下载仍可能较慢，期间建议提供占位图。

坑 8：图片多导致内存压力大、画面闪烁

大量高清图时内存会飙升。MediaBrowser 提供了cachingImageCount控制两侧缓存页数量，并在didReceiveMemoryWarning中释放底层图片（见 MediaBrowser.swift 的releaseAllUnderlyingPhotos）。

解决方案：适当调小cachingImageCount（Demo 中设为 2），并为Media设置placeholderImage（可使用项目中的 mediaBrowserPlaceholder），同时让网络图走 SDWebImage 磁盘缓存，避免重复下载。

小结

这 8 个坑覆盖了 MediaBrowser 集成中最常见的白屏、加载失败、崩溃和内存问题。记住三个核心原则：数据源代理要齐全、实例要新建、网络地址要合规。如果想快速上手，直接运行仓库里的 Demo 工程（MediaBrowserDemo），几乎每一种场景都有现成示例可抄。

git clone https://gitcode.com/gh_mirrors/me/MediaBrowser

祝你顺利集成，告别踩坑 👋

【免费下载链接】MediaBrowser🏞 A simple iOS photo and video browser with optional grid view, captions and selections written in Swift5.0项目地址: https://gitcode.com/gh_mirrors/me/MediaBrowser