OBS鸿蒙迁移21坑：GLES方言、沙箱与hvigor缓存

鸿蒙专家

OBS Studio 32.2.2 是二十万行级的 C/C++ 开源软件，把它迁到 HarmonyOS NEXT（API 26）并在真机上跑通预览、录制、推流全链路后，项目把技术实践批次的 21 个真机坑做了系统复盘；10-02 补齐对齐批次又追记 3 个，共 24 个。本文按原文的六分类方法重组成一份可带走的避坑清单，重点不是“学新 API”，而是把桌面时代积累的隐含假设逐条挖出来。

一、坑的分布：纯 API 用法少，桌面假设多

原文把 21 个坑按所在层分六类：类型系统与规范差异 6 个、驱动合规性 2 个、沙箱与安全模型 4 个、生命周期与所有权 5 个、构建链与工具链 2 个、环境与观测假象 2 个。一个反直觉的结论是：纯鸿蒙 API 用法坑其实很少，沙箱与安全类里占 4 个；更多坑来自“桌面假设不成立”，类型系统、驱动合规、生命周期三类合计 13 个。移植大型开源软件时，真正工作量往往在排查这些没有写进文档的假设。

二、六类问题与可复用教训

1. 类型系统与规范差异。GLES/GLSL ES 不是桌面 GL 的简单子集，而是另一门方言。手写补位的头文件常量必须逐值核对官方源，原文中 GL_TEXTURE_RECTANGLE=0x0DE1 撞车案一个数字卡了一天。移植图形代码前，应先通读目标规范中“与桌面不同”的章节，把隐式转换、保留字、接口块声明差异列成 checklist；常量不要手抄，应从 Khronos gl.xml 生成。

2. 驱动合规性。规范 Table 3.2 里合法的纹理格式组合，驱动仍可能返回 GL_INVALID_OPERATION；扩展 advertised 不等于全组合实现，原文记录 Maleoon 916B 上出现 BGRA 三连拒。GPU 相关功能必须真机试错，纸面规范只能当第一猜；试错时要保留完整失败矩阵，它比成功结论更有复用价值。

3. 沙箱与安全模型。SELinux 禁止 readdir bundle libs 时报 EACCES；linker namespace 拒绝对路径 dlopen 时报 check ns accessible failed；沙箱禁 fork/exec，使 ffmpeg muxer 子进程方案不可用；GPU-usage buffer 的 NativeBuffer 映射会返回全零视图。排查时要分层归因：EACCES 是文件系统层，ns failed 是链接器层，进程模型限制又是另一层，不能当同一个问题修两轮。任何带运行时扫描、动态加载、子进程隔离的框架，动手前都应画出“它假设文件系统与进程模型长什么样”的清单。

4. 生命周期与所有权。XComponent 回调给出的 OHNativeWindow* 是借用引用，不加 NativeObjectReference 会每帧出现 EGL_BAD_NATIVE_WINDOW；obs_output_set_service 不加引用计数，而同族的 set_video_encoder 加；config 释放后指针仍用于日志会造成 UAF；编码线程没有 GL context；gs_* 包装层守卫会挡住合法的跨线程元数据读取。跨语言、跨层边界处，每个句柄都要问谁创建、谁持有、谁释放。libobs 这类老代码库里 setter 语义不统一是历史事实，要逐函数读实现，别信命名。

5. 构建链与工具链。hvigor PackageHap 在时间戳相近时可能跳过重打包，HAP 里还是旧 .so；effect 资源修改后要手工同步源目录、rundir、rawfile 三处。多段构建链 cmake、stage、hvigor、install 的每一段都可能缓存，“改了没生效”的第一嫌疑人永远是缓存。对策是打包前移走旧产物强制重打，并在安装前用

2. unzip -p | strings | grep 新标记

复制代码

做进包验证，把“新代码确实到了设备”变成可证明的命题。

6. 环境与观测假象。libobs 的 blog() 写 stderr 在鸿蒙上会蒸发，接不上日志一切排查免谈；一晚吞掉 40 分钟的“假卡死”其实是熄屏、锁屏竞态。移植任何 C/C++ 库，第一个 commit 应是日志接线。设备端验证先鉴别环境再怀疑代码：白屏先查熄屏，卡死先查线程状态，用

2. pidof

复制代码

配合

2. /proc/<pid>/task/*/status

复制代码

查看，若全为 S 是在睡不是死了；行为没变先查进包。

三、开工前可带走的 checklist

开工前：列出目标库的平台假设清单，包括文件系统布局、进程模型、动态加载方式、线程与 GPU 资源耦合假设；若涉及图形，列目标方言与源方言差异 checklist；预演依赖库交叉编译，区分哪些要改构建脚本、哪些要改源码。

第一周：日志接线 commit 先行；构建链每段加进包验证钩子；把唤醒、解锁、安装、启动、点弹窗、抓日志、截图做成一条命令的自动化。

排查期：报错先分层归因到文件系统层、链接器层、API 语义层、驱动层；做环境假象三查，熄屏、进包、线程状态，然后才怀疑代码；确诊的修复攒批验证，未确诊的探索一次只动一个变量并全量撒探针；黑盒渲染问题优先设计答案唯一的合成实验，例如红帧、渐变，不要急着读驱动源码。

收尾期：每个坑按现象、排查、根因、修复、教训五段式落文档；找“目标无关”的修复拆独立上游 PR，判据是对其他平台也有价值或至少无害；大 port 用 draft PR 台账公开跑，RFC 先问形状不问合否。

四、追记与工程纪律

10-02 对齐批次新增三坑后共 24 个。原文还强调一条纪律：错误归因要公开更正。§5.7 的“驱动坏状态”误判用 A/B 旧构建实验证伪后，以 correction commit 明确改判为自家布局回归；以 PR 为轨道时，诚实的更正记录本身就是贡献。

五、这次迁移真正验证了什么

把 OBS 搬上鸿蒙，技术上是 24 个坑，认知上是同一件事：所有跨平台承诺的兑现程度，取决于你愿意多深地怀疑自己的隐含假设。libobs 假设了 stderr、假设了目录可扫描、假设了 setter 加引用、假设了编码线程没有 GL 需求，这些假设没有一行写在文档里。鸿蒙做的不是简单回答支持或不支持 OBS，而是把这些假设摊到桌面上重新问一遍。对生态而言，平台成熟度的证明不只在官方 demo，也在于第三方大型开源软件迁移进来后还能站起来。项目仓库为 qingkouwei/obs-studio@harmonyos-port，工程文档在 docs/harmonyos-{migration,session-log,port-journey,feature-alignment}.md；验证机为 HUAWEI MatePad Edge，HarmonyOS 7.0.0.109，API 26，Maleoon 916B，PC/2in1 模式。

热心网友6

这篇复盘看下来最有价值的其实是那个分类视角：把坑按“桌面时代的隐含假设失效”来归类，而不是按 API 罗列。大部分迁移文档都在教你新接口怎么调，但真正耗时间的确实是那些文档里根本没写的东西。GL_TEXTURE_RECTANGLE 撞上 0x0DE1 那个案子太典型了，那个值正好是 GL_TEXTURE_2D，手抄常量基本就是等着踩雷，从 gl.xml 生成这个做法应该直接写进移植规范里。 日志接线放第一个 commit 这条深有同感，stderr 蒸发这种事在没有串口、没有终端的环境里属于灾难级，先能看见再谈排查。进包验证那个 unzip -p | strings | grep 新标记 也很实用，多段构建链的缓存问题靠肉眼判断基本判断不了，只能让设备自己证明。 两个好奇的地方想请教一下： 一是 fork/exec 被禁之后，ffmpeg muxer 子进程那套方案你们最后是怎么替的？是改成同进程调用还是换了别的封装，这里会不会牵扯到 libavformat 的线程和中断回调重入问题？ 二是 hvigor PackageHap 跳过重打包那个，除了打包前移走旧产物强制重打，有没有更稳的办法，比如把某个源文件的哈希塞进去当日志标记，让它天然没法跳过？感觉靠时间戳判断的构建工具，长期还是得靠内容哈希兜底。 最后那句“诚实的更正记录本身就是贡献”说得挺好，把自家布局回归误判成驱动坏状态然

热心网友6

这篇复盘看得挺过瘾，尤其是“纯 API 坑少、桌面假设坑多”这个结论。我以前也踩过图形头文件常量的坑，手抄一个数值撞车，排查一整天都不一定能发现问题。你说从 gl.xml 生成常量，这个思路比我当时靠记忆补值靠谱太多了。 另外几个点印象很深： - “改了没生效，先怀疑缓存”，以及打包前移走旧产物、再用进包字符串验证。这套做法不只适用于鸿蒙，任何多段构建链都能用，把“新代码真的到设备上了”变成可验证的命题，这个说法很到位。 - 沙箱那几条分层归因的提醒很实在。EACCES、ns failed、进程模型限制确实是三个层，混在一起当同一个问题修，很容易白烧两轮。 - 熄屏导致的“假卡死”太真实了，我自己也遇到过类似情况，查了半天线程，最后发现设备在睡觉。把熄屏、进包、线程状态做成三查清单，成本很低但很省事。 - 还有一个比较少见但很值得提倡的做法：错误归因公开更正，用 A/B 旧构建实验证伪后明确改判。很多迁移记录只写成功路径，这种诚实的 correction 反而对后来者更有价值。 想请教两个问题：一是 24 个坑里，你觉得哪一类最容易被低估、实际耗时最长？二是第一周那套“唤醒、解锁、安装、启动、抓日志、截图一条命令”的自动化，是针对 MatePad Edge 这套 2in1 环境定制实现的，还是用通用脚本做的？如果是通用做法，想借鉴一下思路。

热心网友6

这篇复盘很有价值，尤其是把问题从“学新 API”拉回到“桌面假设不成立”，比单纯列坑更能复用。六类里我最有共鸣的是沙箱分层归因和缓存验证：EACCES、linker namespace、进程模型限制确实不能混在一起修，hvigor 进包验证也很关键，“新代码确实到了设备”比“构建成功”可靠得多。日志接线先行、熄屏/锁屏造成的假卡死、以及错误归因公开更正这几条，都很像真正踩过坑之后才会留下的经验。 想请教一下，文中提到的失败矩阵和开工前平台假设清单，后面有没有整理成可直接套用的模板？对准备迁移其他大型 C/C++ 库的人会很有帮助。