HAP SO 符号冲突扫描工具

工具简介

用于检测鸿蒙应用(HAP包)中 Native SO 文件的符号冲突问题,帮助开发者发现并解决运行时可能出现的符号解析错误。

前置条件

必须

• llvm-nm:用于解析 SO 文件符号表 本脚本优先使用环境变量中设置的工具路径,其次是C盘用户缓存OpenHarmony路径中的程序如: C:\Users\xxx\AppData\Local\OpenHarmony\Sdk\26.0.0\native\llvm\bin\llvm-nm.exe 用户缓存中的程序路径实质是DevEco Studio设置中下载的OpenHarmony SDK安装路径,因脚本无法读取DevEco Studio 的路径设置,如不安装在C盘,可安装在其他地方后通过设置环境变量来使用,亦可在cmd中通过--nm-tool参数指定路径使用

可选

• llvm-readelf:用于检测编译器版本(使用 --check-compiler 时需要,需与 llvm-nm 同一目录)
• llvm-cxxfilt:用于符号demangle(需与 llvm-nm 同一目录)

环境变量

• OHOS_SDK：指向包含 llvm-nm 和 llvm-readelf 的目录
  • Windows 示例：set OHOS_SDK=D:\OpenHarmony\Sdk\native\llvm\bin
  • macOS/Linux 示例：export OHOS_SDK=~/Library/OpenHarmony/Sdk/ohos-toolchains/llvm/bin

命令行参数

参数	说明	默认值
--hap <path>	单个 HAP 文件路径	-
--hap-dir <path>	包含多个 HAP 的目录路径	-
--app <path>	.app 包路径(自动解析内部 HAP)	-
--output <path>	输出 HTML 报告路径	symbol_conflict_report.html
--merge	启用跨 HAP 合并扫描	关闭(独立扫描)
--check-compiler	启用编译器版本检测	关闭
--nm-tool <path>	指定 llvm-nm 工具路径	自动从 SDK 查找
--open	扫描完成后自动打开报告	关闭
--show-info	显示弱符号重复的详细信息	关闭
--check-system	启用应用与系统库的符号冲突检测	关闭
--sysroot <path>	手动指定系统库 sysroot 路径(覆盖自动检测)	自动从 HAP 的 SDK 版本检测

使用方法

# 单 HAP 扫描
python scan_hap_symbols.py --hap ./app-entry-release-signed.hap

# 扫描目录下所有 HAP(独立扫描模式)
python scan_hap_symbols.py --hap-dir ./haps

# 扫描目录下所有 HAP(合并扫描模式,适用于同一应用的多 HAP)
python scan_hap_symbols.py --hap-dir ./haps --merge

# .app 包扫描(自动解析内部所有 HAP)
python scan_hap_symbols.py --app ./MyApplication.app

# 指定llvm-nm工具路径 (支持相对路径或绝对路径)
python scan_hap_symbols.py --hap ./app-entry-release-signed.hap --nm-tool "D:\xxx\llvm-nm.exe"

系统库冲突检测

使用 --check-system 启用应用与系统库的符号冲突检测(基于 HAP 的 SDK 版本自动查找 sysroot):

# 启用系统库冲突检测(自动检测 SDK 版本)
python scan_hap_symbols.py --hap ./entry.hap --check-system

# 手动指定 sysroot 路径
python scan_hap_symbols.py --hap ./entry.hap --check-system --sysroot "C:\SDK\26.0.0\native\sysroot\usr\lib\aarch64-linux-ohos"

完整示例

# 独立扫描 + 启用编译器检测 + 自动打开报告
python scan_hap_symbols.py --hap-dir ./build/outputs/ --check-compiler --open --output report.html

# 启用系统库冲突检测
python scan_hap_symbols.py --hap ./entry.hap --check-system --open

报告说明

风险等级

等级	含义
HIGH	发现严重冲突(如 C++ STL 静态链接符号冲突)
MEDIUM	发现警告(如业务符号重复定义)
LOW	无符号冲突
NONE	HAP 不包含 Native 代码
ERROR	扫描异常(如 HAP 解压失败)

扫描模式

• 独立模式(默认):每个 HAP 单独扫描,只检测 HAP 内部的 SO 冲突
• 合并模式(--merge):合并所有 HAP 的 SO 后统一扫描,检测跨 HAP 冲突