鸿蒙 PC 适配报错速查大全——50+ 个真实错误 × 对症解法

欢迎加入开源鸿蒙 PC 社区：https://harmonypc.csdn.net/

用法：遇到报错 → Ctrl+F 复制粘贴关键字 → 跳到对应条目 → 抄解法
覆盖：Qt 移植 / Electron 适配 / 鸿蒙原生开发 / DevEco 工程 / 真机调试 / 上架审核 全流程

〇、使用说明

• 每条目用 5 段结构：「错误关键字 / 现象 / 根因 / 解决 / 一句话经验」
• 编号 #01 ~ #52 稳定不动——以后引用就用编号
• 按"出现频率从高到低"组织，头部 10 条覆盖 80% 场景

快速导航

模块	编号	覆盖
🟦 环境配置	#01-#08	第一周新手
🟨 CMake / qmake 配置	#09-#15	移植期
🟥 编译期错误	#16-#23	移植期
🟧 链接期错误	#24-#28	移植期
🟫 ELF 产物校验	#29-#32	移植期
🟪 HAP 打包 / 签名	#33-#38	集成期
🟥 真机启动 / 闪退	#39-#46	调试期
⬛ 真机 UI 渲染	#47-#49	调试期
🟫 上架审核	#50-#52	发布期

---

🟦 模块一：环境配置类（#01-#08）

#01 moc: command not found

• 现象：cmake configure 或 qmake 找不到 moc

• 根因：Qt-OHOS 自带 bin/moc.exe 是 Windows 二进制，Linux/Mac 主机执行不了

• 解决：装 host 端的 Qt5 工具

  # Linux
  yum install qt5-qttools-devel
  # Mac
  brew install qt@5 && brew link qt@5 --force
  

  toolchain.cmake 里指定：

  set(Qt5_MOC_EXECUTABLE /usr/bin/moc-qt5 CACHE FILEPATH "" FORCE)
  set(Qt5_UIC_EXECUTABLE /usr/bin/uic-qt5 CACHE FILEPATH "" FORCE)
  set(Qt5_RCC_EXECUTABLE /usr/bin/rcc-qt5 CACHE FILEPATH "" FORCE)
  

• 一句话经验：host 工具用系统包，目标产物用 OHOS clang 交叉编译——两套泾渭分明。

#02 ohpm install 卡死

• 现象：DevEco Sync 卡在 Resolving dependencies

• 根因：默认 OHPM 源访问慢

• 解决：

  ohpm config set registry https://ohpm.openharmony.cn/ohpm/
  ohpm config set strict_ssl false
  ohpm cache clean
  

• 一句话经验：换镜像源省几小时——新机第一件事就做。

#03 Bad CPU type in executable（Rosetta）

• 现象：Apple Silicon Mac 跑 OHOS SDK 工具报错
• 根因：darwin 子包是 x64，需要 Rosetta 翻译
• 解决：softwareupdate --install-rosetta --agree-to-license
• 一句话经验：Apple Silicon + OHOS SDK 必装 Rosetta，慢 15-30% 但能跑。

#04 hdc: command not found

• 现象：装完 DevEco 后命令行用不了 hdc
• 根因：DevEco 不自动加 PATH
• 解决：把 <sdk>/openharmony/<ver>/toolchains 加到 PATH
• 一句话经验：90% 新手第一周都踩——贴在显示器侧面提醒自己。

#05 brew qt@5 keg-only

• 现象：装完 qt@5 但 which moc 没结果

• 根因：keg-only 包不自动加 PATH（怕和 qt6 冲突）

• 解决：

  echo 'export PATH="/opt/homebrew/opt/qt@5/bin:$PATH"' >> ~/.zshrc
  

  Intel Mac 路径是 /usr/local/opt/qt@5/bin。

• 一句话经验：所有 brew keg-only 包都要手动 export PATH。

#06 brew node 抢 nvm 优先级

• 现象：DevEco 报 Unsupported engine: requires Node ^20，但 nvm use 20 还是不行
• 根因：PATH 顺序里 /opt/homebrew/bin/node 优先于 nvm
• 解决：brew unlink node，或把 nvm init 放 .zshrc 最后
• 一句话经验：装 DevEco 前先 nvm use 20.18.1，别让 brew node 干扰。

#07 git-lfs 缺失 .so 是 130 字节

• 现象：克隆 qt-ohos 后 .so 文件是文本指针不是二进制

• 根因：没装 git-lfs

• 解决：

  brew install git-lfs    # 或 yum install git-lfs
  git lfs install
  cd <repo> && git lfs pull
  

• 一句话经验：Qt-OHOS / KDE-OHOS 仓库必须先装 lfs 再 clone。

#08 DevEco 启动卡 / 缓存冲突

• 现象：同时装 IntelliJ IDEA + AS + DevEco，DevEco 偶尔挂

• 根因：JetBrains 系 IDE 共用部分缓存目录

• 解决：

  rm -rf ~/Library/Caches/DevEco-Studio
  rm -rf ~/Library/Application\ Support/DevEco-Studio
  

• 一句话经验：DevEco 卡到无解时先清缓存，比重装 IDE 快 10 倍。

---

🟨 模块二：CMake / qmake 配置类（#09-#15）

#09 CMAKE_SYSTEM_NAME unknown

• 现象：第一次 cmake configure 直接挂

• 根因：toolchain 文件缺关键变量

• 解决：toolchain.cmake 顶部必加

  set(CMAKE_SYSTEM_NAME OHOS)
  set(CMAKE_SYSTEM_PROCESSOR aarch64)
  set(CMAKE_C_COMPILER ${OHOS_NDK}/llvm/bin/aarch64-unknown-linux-ohos-clang)
  set(CMAKE_CXX_COMPILER ${OHOS_NDK}/llvm/bin/aarch64-unknown-linux-ohos-clang++)
  set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)
  set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)
  set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)
  

• 一句话经验：CMAKE_SYSTEM_NAME OHOS 是鸿蒙交叉编译的"咒语"，少这一行什么都不对。

#10 Could NOT find Qt5 (missing: Qt5_DIR)

• 现象：cmake 找不到 Qt5

• 根因：CMAKE_PREFIX_PATH 没指向 Qt-OHOS

• 解决：

  cmake -DCMAKE_PREFIX_PATH=/opt/qt-ohos/qt-5.12.12-ohos/qt-5.12.12-ohos ...
  

• 一句话经验：CMAKE_PREFIX_PATH 是 Qt5 寻路唯一锚点，记不住就 find . -name Qt5Config.cmake。

#11 qmake: unknown spec

• 现象：qmake -spec ohos-clang-aarch64 不认识
• 根因：用了系统 qmake 而不是 Qt-OHOS 自带的
• 解决：用 Qt-OHOS 自带的 qmake 指 Qt-OHOS 的 mkspec
• 一句话经验：用哪个 Qt 的 qmake 就指那个 Qt 的 mkspec，别混用。

#12 Cannot find moc.exe（qmake 路径）

• 现象：qmake 生成 Makefile 后 make 找不到 moc
• 根因：mkspec 的 host_bins.path 默认指向 bin/moc.exe
• 解决：改 mkspec 或软链

  ln -sf /usr/bin/moc-qt5 /opt/qt-ohos/.../bin/moc
  

• 一句话经验：qt-ohos 自带的 host 工具是 Windows 二进制，软链替身是最快解法。

#13 CONFIG 标志大量缺失（编 KDE/Jack 时）

• 现象：configure 时一堆 feature 报"missing required library"

• 根因：鸿蒙环境没有 KDE Frameworks / libjack / OpenSSL 等

• 解决：批量关闭：

  set(CONFIG_JACK_API 0 CACHE BOOL "" FORCE)
  set(CONFIG_ALSA_SEQ 0 CACHE BOOL "" FORCE)
  set(CONFIG_KF5 0 CACHE BOOL "" FORCE)
  add_compile_definitions(QT_NO_SSL=1)
  

• 一句话经验：先全关再按需开——比"逐个补依赖"快 10 倍。

#14 policy CMP0xxx unset 警告

• 现象：cmake 配置时大量 CMP00xx warning
• 根因：CMake 3.20+ 对旧策略行为变更
• 解决：CMakeLists 顶部：

  cmake_minimum_required(VERSION 3.16)
  cmake_policy(SET CMP0042 NEW)  # MACOSX_RPATH default
  cmake_policy(SET CMP0048 NEW)  # project version
  cmake_policy(SET CMP0077 NEW)  # option() honors variables
  

• 一句话经验：warning 不致命但会污染日志——能消则消。

#15 find_package 找的是宿主库不是目标库

• 现象：找到的 zlib 在 /usr/lib 不在 OHOS sysroot
• 根因：toolchain 没限制 find_package 行为
• 解决：见 #09 的 CMAKE_FIND_ROOT_PATH_MODE_* 三行
• 一句话经验：交叉编译不限定 find_package 范围 = 编出来的库混了宿主库。

---

🟥 模块三：编译期错误（#16-#23）

#16 error: 'register' storage class specifier is deprecated

• 现象：编 KDiff3 / 老 GNU diff 代码报 register 关键字错

• 根因：C++17 把 register 列为保留字，不能再用作存储类

• 解决：编译选项加

  add_compile_options(-Wno-register -Dregister=)
  # 或者直接降到 -std=c++14
  set(CMAKE_CXX_STANDARD 14)
  

• 一句话经验：1990s 老 C 代码移到现代编译器必踩这条。

#17 error: ambiguous overload QStringList

• 现象：编 IronLog / 老 Qt 代码报 QStringList 构造歧义
• 根因：Qt 5.15 新增了 QStringList(const QString&) overload，老代码 QStringList list = something 二义
• 解决：显式声明：

  QStringList list = QStringList() << s;   // 不写成 QStringList list = s
  

• 一句话经验：Qt 5.12 → 5.15 跨版本最常见的"突然不编译"，改写法即可。

#18 error: undefined identifier 'utmpx'

• 现象：编一些老 C 项目报 utmpx.h 找不到
• 根因：OHOS 用 musl libc 不实现 utmpx（X/Open 标准里的登录状态）
• 解决：源码里 #ifdef __linux__ 包裹掉，或用 dummy 头替代
• 一句话经验：musl ≠ glibc，所有 utmpx / login.h / crypt.h 都要做 ifdef 隔离。

#19 error: 'Q_INIT_RESOURCE' undeclared in extern "C" scope

• 现象：把 main 改成 extern "C" 后，QjackCtl 等用到 .qrc 资源的项目编译挂

• 根因：Q_INIT_RESOURCE 宏内含 extern 声明，在 C 链接域里展开会找 mangled name 失败

• 解决：保留 main 为 C++ 链接，末尾追加 wrapper：

  int main(int argc, char* argv[]) { /* 原 C++ 逻辑 */ }
  extern "C" int cdrv_main(int argc, char* argv[]) {
      return main(argc, argv);
  }
  

• 一句话经验：HAP 加载器要 C 符号 main 或 cdrv_main——用 wrapper，不要把整个 main 暴露成 extern “C”。

#20 error: moc generated code references hidden meta-object

• 现象：用 host 的 moc-qt5 5.15 生成代码，编译时报 SuperData / qMetaObjectVersion 不匹配

• 根因：5.15 moc 输出和 5.12 Qt 头文件 ABI 不一致

• 解决：跑 perl 降级脚本把 SuperData → const QMetaObject*

  perl -pi -e 's/\.superdata = QMetaObject::SuperData::link<([^>]+)>\(\)/\.superdata = &$1::staticMetaObject/g' moc_*.cpp
  

• 一句话经验：moc ABI 差异跨小版本——脚本批量降级比换 host Qt 干净。

#21 error: chmod: argument list too long（make 时）

• 现象：编大项目时 ninja 报参数过长
• 根因：1256 个符号链接展开后超 shell ARG_MAX
• 解决：分批 link、或者用 sysroot 副本（拷贝代替软链）
• 一句话经验：超大 Qt 工程的 staging 别用海量软链，拷贝产物更稳。

#22 error: 'QSslConfiguration' was not declared

• 现象：编 NitroShare / 用 SSL 的 Qt 项目报 QSslConfiguration 找不到

• 根因：Qt-OHOS 5.12.12 编译时没启用 OpenSSL

• 解决：CMakeLists 排除 ssl.cpp 并加宏

  list(REMOVE_ITEM SOURCES src/network/ssl.cpp)
  add_compile_definitions(QT_NO_SSL=1)
  

• 一句话经验：Qt-OHOS 默认不带 SSL——任何用到 SSL 的代码要么剥要么 stub。

#23 error: 'visibility' attribute ignored

• 现象：用 __attribute__((visibility("default"))) 标 main 后没生效

• 根因：OHOS clang 默认 -fvisibility=hidden，逐个标只能挽救少数

• 解决：CMakeLists 加

  set(CMAKE_CXX_VISIBILITY_PRESET default)
  set(CMAKE_C_VISIBILITY_PRESET default)
  

• 一句话经验：OHOS clang 默认隐藏所有符号——CMAKE_*_VISIBILITY_PRESET default 是必备配置。

---

🟧 模块四：链接期错误（#24-#28）

#24 undefined reference to 'qInitResources_xxx'

• 现象：链接时报某 qrc 的 init 函数找不到
• 根因：rcc 生成的符号是 C++ mangled，但调用方在 extern “C” 块里
• 解决：见 #19 的 wrapper 方案；或者保证 Q_INIT_RESOURCE(xxx) 在 C++ 文件里调用
• 一句话经验：Q_INIT_RESOURCE 是链接性传染——一不留神就要重设计入口。

#25 undefined reference to 'main'（HAP 加载时）

• 现象：HAP 装上能装但启动 0 秒退出，hilog 报找不到 main

• 根因：业务库 lib<app>.so 默认隐藏所有符号，main 没被导出

• 解决：

  set_target_properties(<lib> PROPERTIES
      CXX_VISIBILITY_PRESET default
      C_VISIBILITY_PRESET default
  )
  

  验证：nm -D libXXX.so | grep " main" 必须看到 T main（大写 T 是已导出）。

• 一句话经验：HAP 加载器靠 dlsym("main") 入口——main 不导出 = 死。

#26 undefined reference: libqohos.so 缺失

• 现象：链接报找不到 qohos 库

• 根因：libqohos.so 没在 link 命令中，或路径不对

• 解决：

  target_link_libraries(myapp PRIVATE
      ${OHOS_NDK}/sysroot/usr/lib/aarch64-linux-ohos/libqohos.so
  )
  

• 一句话经验：libqohos.so 是鸿蒙 Qt 应用的"系统胶水"，不链 = 整个程序起不来。

#27 多个 undefined reference 一片红

• 现象：编译过了但链接时上百个符号找不到

• 根因：往往是 NEEDED 闭包不全——某个 .so 又依赖别的 .so 你没装

• 解决：用 readelf 反向查：

  readelf -d libXXX.so | grep NEEDED
  # 把 NEEDED 列出来的每一个 .so 都准备好
  

  写个 shell 反向闭包脚本：

  for so in $(find . -name "*.so"); do
      readelf -d "$so" | grep NEEDED | awk '{print $5}' | tr -d '[]'
  done | sort -u
  

• 一句话经验：链接红一片 90% 是 NEEDED 闭包缺一环——查 readelf -d 反向闭包。

#28 libffmpeg.so undefined symbol: av_xxx

• 现象：HAP 加载视频相关库报 av_ 符号找不到
• 根因：链了系统 ffmpeg-static，但 OHOS sysroot 里另有版本，符号集不一致
• 解决：统一用 libelectron 包自带的 libffmpeg.so，或者全部静态链接
• 一句话经验：ffmpeg 在 OHOS 上的"多版本符号冲突"是死路——只用一份。

---

🟫 模块五：ELF 产物校验（#29-#32）

#29 产物 file 显示是 x86_64

• 现象：编译出来的 .so 不是 aarch64

• 根因：toolchain 没设 CMAKE_SYSTEM_PROCESSOR aarch64，或 CXX_COMPILER 错了

• 解决：

  file libXXX.so
  # 期望：ELF 64-bit LSB shared object, ARM aarch64, dynamically linked
  

  错了就回到 #09 重新设 toolchain。

• 一句话经验：每次第一次编完都 file 一下——5 秒省 5 小时。

#30 not 4KB aligned

• 现象：HAP 安装到设备报 signature verification failed: not 4KB aligned

• 根因：so 的 LOAD segment 对齐到 64KB 或其他值，鸿蒙要求 4KB

• 解决：用 fix_elf_align.py 修复（仓库有该脚本）

  python3 fix_elf_align.py libXXX.so
  

  或者编译时加：

  target_link_options(<lib> PRIVATE "-Wl,-z,max-page-size=4096")
  

• 一句话经验：鸿蒙 HAP 强制 4KB 对齐——交叉编译产物必须校验。

#31 产物体积异常（10x 正常值）

• 现象：libXXX.so 几百 MB

• 根因：debug 信息没 strip

• 解决：

  ${OHOS_NDK}/llvm/bin/llvm-strip --strip-debug libXXX.so
  # 体积应该缩到 1/5 到 1/10
  

• 一句话经验：Release 包 strip 是基本动作——HAP 50MB+ 上传慢、占内存。

#32 NEEDED 列表不完整

• 现象：readelf -d 看到 NEEDED 6 行，但真机加载报缺某 lib

• 根因：构建产物里少了 NEEDED 显式依赖

• 解决：

  readelf -d libXXX.so | grep NEEDED
  # 每行 NEEDED 都要有对应 .so 在 libs/arm64-v8a/
  

• 一句话经验：NEEDED 闭包是 HAP 运行的硬约束——一行都不能少。

---

🟪 模块六：HAP 打包 / 签名（#33-#38）

#33 no signature file（安装失败）

• 现象：hdc install 报 “no signature file”
• 根因：HAP 没签名，或签名配置丢失
• 解决：DevEco → Project Structure → Signing Configs → 勾"Automatically generate signature"
• 一句话经验：调试阶段一律自动签——别用别人证书或者手动签。

#34 signature verification failed

• 现象：装包时签名校验挂
• 根因：证书过期、Profile 不匹配 bundleName、签名工具版本错
• 解决：
  1. 检查 bundleName 和 AGC 项目包名一致
  2. 重新生成 Profile
  3. 路径全英文（重要）
• 一句话经验：路径含中文 = hap-sign-tool 直接挂——签名文件夹放纯英文路径。

#35 error 9568322

• 现象：DevEco 上架/发布时报错码 9568322
• 根因：签名材料和 AGC 上的不匹配
• 解决：去 AGC 重新下载 .cer 和 .p7b，替换本地的
• 一句话经验：9568322 = “签名/证书材料对不上”——重新下载一遍 80% 解决。

#36 error 9568344

• 现象：调试模式上架时报 9568344
• 根因：调试 Profile 不能用于 release 签名
• 解决：在 AGC 新建 release 类型的 Profile
• 一句话经验：调试和发布是两套 Profile，别混用。

#37 bundleName conflicts

• 现象：上架时报包名已被占用 / 命名空间不允许
• 根因：用了 com.example / com.huawei / com.demo 等保留前缀
• 解决：bundleName 改成 com.<你的域>.<产品名>，避开保留命名空间
• 一句话经验：bundleName 一旦上架不能改——第一次取名要慎重。

#38 路径含中文 hap-sign-tool 崩

• 现象：签名时报莫名其妙的 NullPointer / parse error

• 根因：hap-sign-tool（Java 实现）解析中文路径有 bug

• 解决：把整个签名材料和工程移到纯英文路径

  ❌ /Users/dev/桌面/鸿蒙签名/
  ✅ /Users/dev/ohos-sign/com.xxx.app/
  

• 一句话经验：路径含中文是签名头号杀手——文件夹只用 ASCII。

---

🟥 模块七：真机启动 / 闪退（#39-#46）

#39 napi_unwrap fail（Electron 旧版包）

• 现象：旧版 libelectron 在 API 23 / HarmonyOS 6.1 设备上启动 0 秒退出，hilog 看到 napi_unwrap fail
• 根因：旧版 libelectron 用 XComponent 那条渲染路径，在新版 API 上协议不兼容
• 解决：换新版 libelectron（双模块包 = electron 主模块 + web_engine HSP）。新版用 WebAbility 基类继承，不走 XComponent
• 一句话经验：API 23+ 设备必须用新版 libelectron——旧版从根上跑不起。

#40 Unable to listen on port 40818（NitroShare 类）

• 现象：启动时 splash 一闪而过，慢动作录屏看到模态错误框 “Unable to listen on port”

• 根因：鸿蒙沙箱不允许 musl libc 路径 bind 任意端口；模态对话框 + setQuitOnLastWindowClosed = 假性闪退

• 解决：把启动期 QMessageBox::critical 全部降级成 qWarning() <<

  // 原来：
  QMessageBox::critical(nullptr, "Error", msg);
  // 改成：
  qWarning() << "App:" << msg;
  

• 一句话经验：启动期任何 critical 模态框 = 致命假性闪退——一律降级日志。

#41 cppcrash 无栈信息

• 现象：应用秒退，hilog 只看到 cppcrash 三个字

• 根因：没装 faultlog 抓取

• 解决：

  hdc shell ls /data/log/faultlog/faultlogger/
  hdc file recv /data/log/faultlog/faultlogger/cppcrash-<pid>-<time> ./
  cat ./cppcrash-*
  # 一般能看到 backtrace + module 偏移
  

• 一句话经验：cppcrash 无栈 = 你没去 faultlog 目录捞——所有 native 崩溃都在那。

#42 GPU 进程白屏崩溃（Electron）

• 现象：Electron 应用启动后整个窗口白屏

• 根因：鸿蒙 PC 上 chromium GPU 子进程在某些机型上挂

• 解决：main.js 加

  app.disableHardwareAcceleration()
  app.commandLine.appendSwitch('disable-gpu')
  app.commandLine.appendSwitch('disable-software-rasterizer')
  

• 一句话经验：Electron 鸿蒙白屏第一招——禁 GPU。99% 都能立即解决。

#43 Cannot find module 'electron'

• 现象：Electron 应用启动报找不到 electron 模块
• 根因：把 "electron" 写进了 package.json 的 dependencies，鸿蒙运行时不需要也不允许
• 解决：package.json 里 electron 字段一律删掉——运行时由 libelectron.so 提供
• 一句话经验：鸿蒙 Electron 是宿主提供的——npm install electron 是错的。

#44 dlopen undefined symbol

• 现象：HAP 启动时报某 .so 加载失败，undefined symbol
• 根因：交叉编译的 .so 引用了运行时不存在的符号
• 解决：

  nm -D libXXX.so | grep "U " | head -20  # 看 undefined 符号
  # 对照 OHOS sysroot 看哪个没提供
  

• 一句话经验：undefined symbol 是"我引用了平台没有的 API"——查 OHOS sysroot 决定 stub 或剔除。

#45 应用启动时 Cannot find resource 'main.js'

• 现象：Electron 应用启动找不到入口

• 根因：web 应用没放在 web_engine/src/main/resources/resfile/resources/app/

• 解决：

  # 把 main.js / preload.js / index.html / package.json 放到：
  web_engine/src/main/resources/resfile/resources/app/
  

• 一句话经验：新版 libelectron 入口固定在 resfile/resources/app/——别放错位置。

#46 EntryAbility 启动失败（ArkTS 工程）

• 现象：原生 ArkTS 应用启动报 EntryAbility onCreate 异常

• 根因：往往是 module.json5 里 deviceTypes / abilities 配置错

• 解决：

  "deviceTypes": ["phone", "tablet", "2in1"],   // 鸿蒙 PC 必加 2in1
  "abilities": [{
    "name": "EntryAbility",
    "srcEntry": "./ets/entryability/EntryAbility.ets",
    "launchType": "singleton"
  }]
  

• 一句话经验：deviceTypes 不含 “2in1” = 鸿蒙 PC 不认这个应用。

---

⬛ 模块八：真机 UI 渲染（#47-#49）

#47 QSS .qrc 不生效（IronLog 类）

• 现象：在 .qrc 里打包的 .qss 文件 setStyleSheet 后没效果

• 根因：Qt-OHOS 5.12 对 .qrc 内 QSS 解析路径有 bug

• 解决：改成 C++ 内联 QSS

  const QString STYLE = R"(
    QPushButton { font-size: 14pt; padding: 8px; }
  )";
  qApp->setStyleSheet(STYLE);
  

• 一句话经验：鸿蒙 Qt 上 QSS 走 .qrc 不稳——直接 R"(…)" 内联最可靠。

#48 font-size 用 px 不生效

• 现象：QSS 里写 font-size: 14px 但真机上没变化

• 根因：鸿蒙 Qt-OHOS 对 px 单位计算有 bug

• 解决：改成 pt 或 em

  font-size: 14pt;   /* ✅ */
  font-size: 14px;   /* ❌ 鸿蒙忽略 */
  

• 一句话经验：鸿蒙 Qt QSS 字号一律用 pt，px 当不存在。

#49 QPainter 字号偏大

• 现象：QPainter::drawText 渲染的字号比 QSS 里同值大 1.5 倍

• 根因：QPainter 默认 DPI 和 QSS 不一致

• 解决：QPainter 字号 = QSS pt × 0.6 经验值

  Widget 类型	QSS pt	QPainter pt
  标题	16pt	10pt
  正文	14pt	9pt
  标签	12pt	8pt

• 一句话经验：QPainter ≠ QSS——同一字号视觉差 1.5×，要分别调。

---

🟫 模块九：上架审核（#50-#52）

#50 审核打回：3.5 项 功能不完整

• 现象：AGC 审核被打回，理由是"应用应该具备完整的功能"
• 根因：某个按钮在鸿蒙 PC 上点了无反应，或有 TODO / coming soon 字样
• 解决：
  1. 真机逐个按钮自测
  2. 未完成功能的按钮 disabled + tooltip "暂不支持"
  3. 全工程搜过 “TODO” / “待开发” / “敬请期待”
• 一句话经验：3.5 项是 Electron/Qt 适配上架头号打回理由——有缺陷的功能宁可禁用别留着。

#51 审核打回：隐私说明缺失

• 现象：审核报 “未提供隐私说明”
• 根因：哪怕应用完全不联网也要填隐私说明
• 解决：在 AGC 应用信息里填一行即可：“本应用不收集任何用户数据”
• 一句话经验：隐私说明是必填项——一句话也行，但不能空。

#52 审核打回：截图不规范

• 现象：审核报截图分辨率/数量/方向问题
• 根因：鸿蒙 PC 是横屏设备，要求：
  • 5 张截图
  • 分辨率 ≥ 1920×1080
  • 横屏（不接受手机竖屏截图）
  • 不带水印/调试条
• 解决：用真机或模拟器全屏截图，PS 裁到 1920×1080，最少 5 张
• 一句话经验：截图不够 5 张直接打回——准备阶段一次截 8-10 张备用。

---

一、4 条带回家的经验

读了这么多条目，真正能记住的就这 4 条：

经验 1：90% 的报错都有现成解法——别自己造轮子

鸿蒙 PC 适配的"坑库"已经积累了 2 年——你撞的几乎所有问题都有人撞过。先 Ctrl+F 这种速查表，再 Google，最后才自己 debug。

经验 2：hilog 是真机调试的唯一可靠手段

DevEco Console / Chrome DevTools 在鸿蒙真机上经常拿不到完整输出。养成习惯：

hdc shell hilog -x | grep <your-bundle-name>

长期开着这条命令——比任何 IDE 都靠谱。

经验 3：每次第一次编完产物先体检 5 项

每个项目第一次编完跑一遍这 5 个体检：

file libXXX.so                          # 1. aarch64？
readelf -d libXXX.so | grep RUNPATH     # 2. RUNPATH 对吗？
readelf -d libXXX.so | grep NEEDED      # 3. NEEDED 闭包齐吗？
nm -D libXXX.so | grep " main"          # 4. main 导出了吗（T main）？
readelf -lW libXXX.so | grep LOAD       # 5. 4KB 对齐吗？

5 项过了再装 HAP——省你后面 2 小时无头排查。

经验 4：报错速查表是社区财富——撞到新的就贡献回来

这份大全有 52 条。但实际坑远不止 52 个。遇到没列出来的新报错，按下面模板留个邮件 / Issue / PR：

### #XX `<错误关键字>`
- **现象**：
- **根因**：
- **解决**：
- **一句话经验**：

社区一起共建——后来者就不用每个人都从头撞。

---

二、配套资源

• 错误码对照（华为云）：developer.huawei.com/consumer/cn/doc/
• OHPM 国内镜像：ohpm.openharmony.cn
• hilog 完整命令参考：hdc shell hilog -h
• faultlog 路径：/data/log/faultlog/faultlogger/

---

写在最后

这份速查大全的真正价值不是"50+ 条目"，而是它让你节省自己重新撞墙的时间。

如果你今天遇到一个报错，Ctrl+F 一搜就找到解法 → 30 秒解决，比起自己 debug 3 小时——这就是这篇文章的意义。

不需要从头到尾读。当你下次遇到 napi_unwrap fail 或 not 4KB aligned，就回到这里查。

它是一份工具书。
工具书不需要漂亮，需要的是真的有用。

更新约定：本表会持续维护。如果你撞到了不在表上的新报错，按上面"经验 4"的模板留一条，下一个版本我会补进来。