鸿蒙平板变身Mac第二块屏：ArkTS与NDK零拷贝上屏实战全记录

想让旧平板发挥余热，最实用的去处之一就是给电脑当第二块屏。但把鸿蒙平板变成Mac的扩展屏，走官方API这条路行不通——开发者用VivLink这个App完整趟了一遍坑：官方投屏接口方向相反、解码器必须走NDK、1080p画面底部永久马赛克、macOS凭空造屏还得靠私有API。这篇实战记录把这些坑一次讲清。

为什么官方路线走不通

鸿蒙官方文档里有《扩展屏投播开发指导》，看起来正是要找的东西，但细读会发现三条硬约束：

1. 平板端在这套API里是投屏源，把自己镜像到远端——而需求恰恰相反，是要接收外部画面；
2. 远端设备必须支持Cast+或Miracast，而macOS默认只做AirPlay接收端，本身不是Cast+/Miracast sink；
3. 系统需先发起投屏才有有效返回，且文档标注为手机设备。

实测也印证了这一点：MatePad的无线投屏扫描列表里根本不出现这台Mac。结论只能是放弃官方路线，走自研方案——Mac端自研虚拟屏加传输协议，鸿蒙端自研客户端。

还有一个决定工程形态的事实：AVCodec Kit只提供C接口，纯ArkTS没有低时延解码送显的API。于是整个项目变成ArkTS UI加NDK C++媒体层的混合工程：收流、解码、送显全在native层，ArkTS只负责UI与路由，页面把XComponent的surfaceId交给native。

1080p花屏：一个极具迷惑性的坑

零拷贝上屏的链路本身很短：把surfaceId交给native，创建解码器，设好Surface，之后解码器直接往这块缓冲里写数据，没有中间的格式转换和上传环节。

坑就出在缓冲几何上。真机1080p下，画面底部出现一条永久马赛克，而且换关键帧也刷不掉；更误导人的是，文件解码路径完全正常，只有真机实时1080p出问题。

排查时本能会指向解码器——NAL切分错了？丢包？驱动bug？都不是。真正的原因是：XComponent的surface可能协商出一个非16:9的默认缓冲几何，1920×1080的帧按16:9写进去就溢出到底部，而720p恰好匹配那个默认值，所以720p一切正常。

解决办法是在创建解码器时用SET_BUFFER_GEOMETRY把缓冲几何钉死成码流尺寸。钉死之后，1080p连续运行92秒零错误，文件解码段稳定60fps。

这里的教训值得记住：某个档位正常、另一个档位坏的bug，第一分诊点应该是两端的尺寸契约，而不是解码能力本身。

12字节定长头的自研协议

媒体传输走UDP，为避开IP分片，载荷上限设为1200字节，前面加一个12字节定长头：1字节标志位、2字节分片序号、2字节分片总数、4字节帧号、2字节载荷长度。

这五个字段缺一不可：裸UDP既没有序号也没有重传，没有帧号、分片序号和分片总数，接收端就无法区分「这帧还没收完」和「这帧丢了」。标志位里的奇偶校验片用于简易前向纠错——实测在剧烈拖拽的码率尖峰下基本无效，但保留它至少明确了「这类丢包已试过、救不了」。

控制面走TCP，用2字节长度前缀加JSON，输入回传也复用这条通道。断线恢复实测：强杀Mac端进程后，平板侧在4到6秒内自动重连到新进程，状态不损坏。

在macOS上凭空造一块系统承认的屏

产品要成立，Mac上得真的多出一块屏。但macOS公开API里没有「创建显示器」这一条，唯一的路是私有ObjC类CGVirtualDisplay——苹果自家的Sidecar和AirPlay走的正是同一套机制。

用私有接口有两个代价：没有官方文档，只能靠开源先例和运行时自省摸索方法签名；Mac端因此无法上架Mac App Store，只能官网直链分发。

两个典型坑也值得记录：一是applySettings并不会切换当前模式，它只是把请求的分辨率加入可用模式表，虚拟屏总是以默认1280×720启动，必须在显示注册完成后再显式切换，而且只有owner进程内切换才生效；二是在编码回调线程里直接退出进程会死锁，收尾必须整体搬回主线程。

写在最后

VivLink现已在华为应用市场上架，Mac端可在其官网免费下载。回头看整个项目，最花时间的不是写代码，而是证明每一步是对的：判据必须落在被测对象自己身上，文档里「已接受」的结论要敢于复核，现象和原因有时完全不搭。这几条经验，比任何具体API的用法都更经用。