月光放映机：我给鸿蒙写了一个视频播放器

2025 年 2 月的一个晚上，我打开鸿蒙平板，想找部电影看。

片子就放在 NAS 上，WebDAV 也能连上，但把影片从 NAS 里放出来这件事，体验并不算好：格式不认识的打不开，字幕要手动找，看到一半切出去回个消息，回来还得重新拖进度条。

那天晚上我没看成电影，第二天开始写一个播放器。

它就是 月光放映机（MoonPlay）：一款运行在 HarmonyOS 上的原生视频播放器，目标很明确——多源聚合 + 电影剧集式元数据 + 干净克制的播放体验。它是一个免费的应用，官网是 moonplay.cn。

月光放映机是什么

一句话：把你散落各处的影片，聚合成一个漂亮的媒体库，然后用一个顺手的播放器看完。

不只是一个「能播视频的壳」，它想解决的是片源分散这件事：

• 本地存储 —— 设备本地媒体目录
• 网络存储 —— WebDAV、SMB、URL 直链
• 云盘存储 —— 115 网盘、百度网盘、阿里云盘（2026 年 8 月新增）、光鸭云盘（2026 年 8 月新增）
• 媒体服务器 —— Emby、Jellyfin、Plex、极空间

所有文件源走同一套接口，可以混着挂在同一个媒体库里。NAS 上的老电影、115 里的剧集、Emby 服务器上的动漫，全都汇到同一个首页，浏览时几乎感觉不到它们来自不同的地方。

常见的 MKV / MP4 / MOV / TS / M2TS 等封装与主流编码都能直接播放，冷门格式也有兜底方案，遇到不认识的格式会自动选用合适的解码方式，一般不用手动干预。

平台方面，目前是 HarmonyOS 原生应用，支持鸿蒙手机、平板与电脑（HarmonyOS PC），在华为应用市场搜「月光放映机」就能免费下载，没有账号体系，也不需要订阅。

如果你在找一个 Infuse 的鸿蒙替代，这就是我做它的原因。

那些「用起来爽」的细节

功能表可以列很长，但真正让一个播放器值得留下的，通常是几个很小的点。

进度条一拖就有画面。 拖动进度条时，会实时生成帧级缩略图预览，不用盲猜拖到哪儿了。这也是我花时间最多的体验优化之一：为了让快拖时也能稳定出图，最后是给它单独跑了一个轻量的播放实例。

上次看到哪，下次接着看。 断点续播，按「文件源 × 影片」维度记录。剧集更省心——点开自动选中最近播放的那一集，播完自动提示下一集。

手势跟手。 双击左右两侧 ±10 秒（秒数可自定义）、左右滑动调进度、长按倍速、上下滑动调亮度音量。亮度和音量是跟手式的，手指在哪，提示条就跟到哪；亮度还是播放页作用域的，在播放页调暗不会把整个系统一起调暗。

片头片尾自动跳过。 接入 TheIntroDB 社区片段时间戳库，以 TMDB ID + 季号 + 集号查询，片头、片尾、前情提要三种片段都能识别并弹出跳过按钮。

字幕音轨自由。 内封多音轨、多字幕轨自动识别切换，同目录外挂字幕自动发现（.srt/.ass/.ssa/.sub），字体、颜色、描边、位置、延迟都能调。

还有一些不说话但一直在的：画中画、睡眠定时、锁屏与蓝牙耳机的系统媒体控制、PC 端键盘快捷键、播放页顶栏的实时网速。

7 个月里最难的三件事

一、让「什么都能播」这件事变得无感

播放器的第一道门槛永远是格式兼容：用户手里的片子是十几年攒下来的，封装、编码、音轨、字幕五花八门，只要有一个打不开，其他做得再好也没用。

我要的结果是「拖进去就能播」——不弹格式不支持的提示，不让用户去查这个编码能不能解码，也不用关心字幕是内封还是外挂。听起来是一句体验描述，落到实现上全是兜底：不同来源、不同封装、不同编码的探测与回退，播放器状态的保存与恢复，失败时的降级路径。

中间踩过的坑记了一整份文档。印象最深的一个：部分设备上初始化解码链路时会先抛一条表面错误、随后自动回退到可用路径，一开始我把它当成播放失败处理，其实只是探测过程中的正常噪声——这类「不报错、只是不生效」的问题最消耗人，最后只能靠一份一条条写下来的踩坑记录活着。

二、让刮削变准

播放器再强，媒体库要是海报全错，也没人愿意用。

刮削这条链路的活儿比想象中脏：遍历目录识别视频文件、从文件名剥离画质编码压制组噪声、提取片名和季集号、去 TMDB 搜索匹配、拉元数据落库。

真实世界的文件名远比规范复杂。Inception.2010.1080p.BluRay.x264.mkv 好办，难的是中文命名、双语片名、「第 1 季」「第一部」、只有集号没有剧名的文件、以及把年份误当成季号的边界情况。最后的做法是逐个堆细节：内置噪声词表、逐级向上用目录名兜底、季号限制 150、集号限制 1999，还支持 {tmdb-27205} / {imdb-tt1375666} 这种 ID 精确匹配——遇到翻拍片反复匹配错时，这是唯一可靠的手段。

但自动匹配不可能 100% 准确。所以我做了手动匹配：刮错了可以自己改写名称、年份、季号，单文件或整目录批量校正，改完立即重写条目。接受「一定会错」，然后给用户一条随手能改回来的路，比追求纯粹的自动化要实在。

三、学会克制

这一点最难，因为它跟「写代码」没关系。

功能是加不完的。播放器这类工具，越加越容易变成按钮堆——每个按钮单看都有道理，合起来就是找不到重点。

我拿 Infuse 和 IINA 当参照，把播放器控件重新排了一遍：播放按钮放到进度条正中、双击动作和快进秒数做成可配置、设置面板重新分组、连「上一集/下一集」在哪都调了几轮。

过程里做的最多的事其实是删：能靠手势完成的，就不放按钮；能用默认值合适的，就不给选项；只有真正会经常改的才进设置页。判断标准很简单——用户按下去的时候，画面是不是立刻就对了。

一路的时间线

回头看，这个项目并不是一条直线。

• 2025 年 2 月 动手，第一个 commit 是搭 Tabbar / Nav 结构
• 2025 年 5 月 首个版本发布（v1.0.0，WebDAV/本地 + TMDB 刮削）
• 2025 年 6 月 加入 Emby、Jellyfin、115 网盘
• 2026 年 6 月 重启高频迭代，解码能力升级、播放器界面重做
• 2026 年 7 月 上线进度条缩略图预览（实验性），拖拽找片更直观
• 2026 年 8 月 密集迭代的起点：SMB 支持、离线下载、画质识别、极空间与 Plex 接入、片头片尾跳过、字幕样式、音轨切换陆续补齐；云盘阵营继续扩员——阿里云盘接入并支持多盘符与原画清晰度，光鸭云盘新增支持，百度网盘接入授权登录
• 2026 年 9 月 从「加功能」转向「磨体验」：PC 端键盘快捷键、手动匹配影视信息、字幕延迟调节之外，还大幅优化了刮削扫描速度与识别准确率、云盘大目录加载速度、播放起播速度与流畅度；沉浸式全屏（窗口级）、播放错误提示与失效链接预检、播放页亮度与手势跟手、Emby 播放进度上报、详情页图库与缓存清理等一批细节陆续打磨到位

从第一行代码到现在，仓库里已经积累了 1242 次提交、约 7.2 万行 ArkTS。当前官网记录的版本是 v1.2.12，累计 19 个版本、127 条更新，完整更新日志在 moonplay.cn/changelog。

2026 年 9 月：把细节磨一遍

8 月一口气堆了很多功能，9 月做的事正好相反——不怎么加按钮，主要回头补体验。这个月连着发了 5 个版本（v1.2.8 ~ v1.2.12），基本都是在收拾前一个月的摊子。

挑几个我比较在意的：

• 播放前先体检。 网络资源播放前会自动预检，失效链接提前拦掉，不再让人对着转圈等半天；播放出错的提示也重写了，无法恢复时自动隐藏重试按钮，不再给一个点了也没用的按钮。
• 亮度这件事终于顺了。 垂直滑动调亮度/音量不跟手、亮度还会泄漏到首页，都是实测反馈出来的问题；现在改成进度条展示，并且亮度是播放页作用域，调暗播放页不会把整个系统一起调暗。
• 全屏更像全屏。 升级为窗口级沉浸式全屏，PC 端还能用空格、方向键这些快捷键操作。
• 刮削更准也更稳。 增强了目录名容错与命名解析能力，大幅优化扫描性能；扫描时单个文件源出错不再影响其他源，百集以上的剧集信息也显示得下了。
• 云盘体验补齐。 115 网盘拖拽进度条不精准、Emby 部分源播不了、云盘大目录加载慢，这几类问题都在这个月逐个修掉。

还有个偏「长期主义」的小功能：详情页新增剧照 / 海报 / Logo 图库，设置里也能看到各项缓存占用并一键清理。

说「夜间施工」不夸张。白天要上班，绝大部分功能是晚上十一二点之后写的。也是这个节奏让我养成了一些习惯：小步提交、改完就跑测试、所有踩过的坑当场记下来——否则过两周自己都不记得为什么那么写。

接下来：电视和大屏

手机、平板、PC 之后，下一个要补的是大屏。

鸿蒙 TV 端的适配已经在路上，同时会继续打磨 PC 端的播放体验——大屏上的遥控器操作、键鼠与遥控的混合交互、超长距离的进度条拖动，都是和手机上完全不同的手感，需要单独做一遍。

另一件更长期的事是跨设备同步：播放进度、媒体库与观看记录在不同设备之间保持一致。手机上看到一半，回到客厅的电视上能接着看——这是「一个媒体库」这件事最自然的延伸，也是我个人最想要的能力。

这两块都在规划里，有进展会第一时间在社区和更新日志里同步。

一些用户反馈

用的人一直在提意见，这些声音也一直在改产品：

• 设置页新增意见反馈入口——不用去别的地方找，直接在 App 里提交（v1.2.9）
• 手动匹配影视信息——有人反馈剧集刮削错了没法改，于是加了单文件/整目录批量校正（v1.2.10）
• 字幕延迟调节——双语字幕对不齐是最常见的抱怨，于是加了高级选项浮层（v1.2.9）
• 沉浸式全屏 + PC 端键盘快捷键——平板和外接屏用户提得最多（v1.2.10）
• 115 网盘设置扫描目录、关闭自动扫描——网盘目录太乱，不想全量扫（v1.2.2 / v1.2.8）
• 播放页亮度不再泄漏到首页——垂直滑动调亮度不跟手、亮度影响全局，都是用户实测反馈（v1.2.9）
• 多选批量手动匹配——单条校正还不够快，于是支持一次多选批量改（v1.2.12）
• 详情页图库 + 缓存清理——有人想要剧照海报，也有人想知道 App 到底占了多少空间（v1.2.11）

想看别人在聊什么，或者自己也提一条，社区在这：community.moonplay.cn（使用技巧、经验分享与问题反馈）。更早的需求投票和路线图仍在 功能请求 / 路线图。

如果它刚好解决了你的问题，欢迎去应用市场下载试试；用起来有任何问题，可以直接在 App 的设置页提交反馈，或去社区发帖，也可以加入交流群（官网联系页面有 QQ 群与微信群入口）。

Windows 上有 PotPlayer，macOS 上有 IINA 和 Infuse，iOS 上有 nPlayer——鸿蒙上总得有一个自己的。 这就是我做月光放映机的原因。

官网：moonplay.cn ｜ 社区：community.moonplay.cn ｜ 帮助中心：moonplay.cn/help ｜ 更新日志：moonplay.cn/changelog ｜ 华为应用市场搜索「月光放映机」