【OpenHarmony/HarmonyOs 】ArkTS 代码混淆实战属性、文件名与导出符号的风险边界前言Release 包中的 ArkTS 代码需要考虑体积和逆向成本但“把所有名字都混淆”并不一定安全。序列化字段、路由字符串、跨模块接口和平台回调一旦被错误改名可能只在 release 包中崩溃。本文结合 LinkOS 的混淆规则讲解启用方式、保留项和验证策略。一、项目当前规则-enable-property-obfuscation-enable-toplevel-obfuscation-enable-filename-obfuscation-enable-export-obfuscation它们分别针对属性名、顶层名称、文件名和导出符号。开启范围较广能增加静态阅读成本但也意味着必须认真审计动态访问边界。静态调用通常可以被工具链同步改名而通过字符串、JSON、配置文件或外部协议使用的名称构建工具未必知道它不能变化。这正是混淆问题往往只在 release 包出现的原因。二、先明确混淆能防什么风险混淆的实际作用普通静态阅读增加理解成本复制业务算法提高门槛但不能彻底阻止提取硬编码 API Key基本无法防御篡改客户端判断只能增加成本仍需服务端校验网络窃听无效应依赖 HTTPS云数据越权无效应依赖认证和访问规则三、混淆不等于加密混淆只能改变名称和结构可读性不能保护硬编码秘密。API Key、密码和固定 Token 即使经过混淆仍可能从包体或运行时提取。因此AI Key 放云函数环境变量用户凭据使用系统安全存储日志不打印敏感值HTTPS 与服务端鉴权不能由混淆替代。四、属性混淆最容易影响 JSON项目将自定义网址序列化JSON.stringify(list)并依赖固定字段读取constidtypeofraw.idstring? raw.id:; const title typeofraw.title string? raw.title :;如果属性名在一端变成短名而旧版本磁盘仍保存id/title/url升级后可能无法解析。云接口字段也必须保持协议稳定。需要保留的典型属性包括idtitleurl icon categoryIdsortcreatedAt updatedAt bundleName abilityName moduleName appId具体保留语法应以当前 SDK 的混淆文档为准并通过 release 包验证而不是只凭 debug 包判断。假设 1.0 版本已经保存{id:1001,title:GitHub,url:https://github.com}1.1 版本如果改变字段协议新安装用户可能正常升级用户却无法读取旧收藏。测试因此必须同时覆盖“全新安装”和“带旧 Preferences 升级”。更稳妥的结构是建立显式 DTO 映射让业务对象与持久化协议分离interface UrlItemDTO {id:string; title:string; url:string; } function toDTO(item: UrlItem): UrlItemDTO {return{id:item.id, title:item.title, url:item.url }; }DTO 字段仍需正确保留但协议边界会更清楚也便于增加schemaVersion和迁移函数。五、导出符号与跨模块协议StorageUtil、EntryManageService、RoleFactory等通过 export 被其他文件引用。构建工具通常能够跟踪静态引用但动态加载、反射、字符串查找和外部模块调用需要额外关注。凡是名称参与以下场景都要评估保留平台按固定名称查找 AbilityJSON 字段或数据库列名JS Bridge 暴露的方法第三方 SDK 回调接口跨模块公共 API测试或脚本通过字符串访问的成员。判断一个名称是否需要保留可以问它是否只存在于静态 ArkTS 引用中如果还出现在配置、数据库、网络响应、Want 参数或第三方文档中就应该进入协议审计清单。EntryAbility、EntryBackupAbility的路径通过配置与平台关联JS Bridge 或三方 SDK 还可能按固定方法名查找回调。此类边界比普通内部私有方法更敏感。六、文件名混淆与路由页面通过字符串注册和跳转router.pushUrl({url: pages/v2/WebViewPage });同时main_pages.json保存页面路径。开启文件名混淆后要确认构建系统能够同步处理页面映射。如果页面由运行时字符串拼接得到静态分析可能无法识别。建议路由集中为常量不动态拼接页面路径对所有入口执行 release 路由冒烟测试需要时为页面和 Ability 文件设置保留规则。项目至少需要逐个访问欢迎页、首页、元服务、AI、我的和 WebView不能只验证默认首页。动态拼接路由路径会降低静态分析能力最好使用集中常量和固定字面量。七、顶层名称混淆顶层类名和函数名缩短通常对静态内部引用影响较小但日志、错误分析和三方协议可能受到影响。生产崩溃定位需要 name cache 或符号映射否则堆栈只剩无意义短名。规则文件支持输出和复用 name cache。发布流水线应把映射文件作为对应版本的受控构建产物保存不能公开分发也不能在新版本中随意丢失。可以按发布版本归档release-artifacts/1.0.0/hap-checksum.txtobfuscation-namecache.txtbuild-metadata.json同一符号在不同构建中反复变化会增加补丁对比和崩溃定位难度。映射应与具体 HAP 一一对应并限制访问。八、日志处理规则注释中提供-remove-log。移除 console 日志可以减少泄露和体积但不能一刀切删除所有可观测性。推荐调试日志在 release 移除关键错误使用结构化 hilog不记录 Token、完整用户查询和对话错误日志携带匿名 requestId保留必要错误码不保留敏感参数。混淆后不要依赖函数名作为唯一诊断信息可以保留稳定业务标签与错误码hilog.error(DOMAIN,SiteRepository,SITE_PARSE_FAILED code%{public}s,INVALID_SCHEMA);完整 URL 查询参数、用户搜索词和 AI 对话不应直接进入日志。九、保留规则如何分类保留项不应无止境增加可以按边界归类平台入口Ability、ExtensionAbility、生命周期页面入口页面文件与路由路径 数据协议JSON字段、数据库列、云对象字段 跨端协议Want parameters、JSBridge方法 三方协议SDK 回调与反射读取成员每条规则最好注明原因和对应测试。若为了修复问题直接 keep 整个项目虽然功能恢复但混淆价值也几乎消失。十、渐进启用策略不要首次就开启所有选项然后直接发布。建议逐层启用先做压缩和顶层混淆构建 release 并跑完整主流程再启用属性混淆补齐协议字段保留再验证文件名和导出符号保存映射文件比较包体、启动、性能和崩溃情况。十一、CI 自动验证静态检查 →Release编译 → 安装测试设备 → 导入上一版本数据 → 运行首次启动、CRUD、路由、WebView 冒烟测试 → 保存 HAP 校验值和namecache流水线要能区分混淆、签名、资源压缩和环境配置错误。Release 出问题后直接关闭混淆只适合临时定位不应成为最终修复。十二、动态属性访问的隐藏风险静态访问容易被构建工具分析const titleitem.title;动态访问则把属性名变成运行时字符串const fieldNametitle;const title record[fieldName];如果title被混淆而字符串没有同步变化debug 正常、release 就可能得到 undefined。类似风险还包括Object.keys()后按字段名分支用字符串映射表单字段通用 JSON 转对象工具根据服务端字段名动态赋值JS Bridge 按方法字符串调用测试框架按成员名称查找方法。遇到这类代码优先改为显式映射而不是随意给整个类添加 keepfunctionreadUrlItem(raw: Recordstring,Object):UrlItem|null{constidValue raw[id];consttitleValue raw[title];consturlValue raw[url];// 对协议字段逐项验证再构造内部模型returnnormalize(idValue, titleValue, urlValue); }这里的字符串键属于外部协议需要稳定保留内部UrlItem的实现则仍可根据规则优化。十三、建立上一版本升级样本每次正式发布后应保存一份不含真实用户隐私的测试数据快照包括身份与兴趣Preferences自定义网址JSON快捷入口 ID 语言与视图模式 备份快照样例 云接口响应样例下一版本 release 构建完成后用旧样本执行覆盖升级。重点不是只看应用能否启动而是逐项比较数据数量、字段值、排序和更新时间。还可以先计算规范化数据摘要升级后再次计算快速发现静默丢字段。如果数据 Schema 发生变化则断言迁移后的目标结构而不是要求字节完全一致。这样混淆验证和数据迁移测试可以共享一套样本。十四、典型故障定位Release 中收藏全部消失优先检查属性混淆、JSON 字段和旧数据迁移而不是先怀疑 Preferences 权限。只有部分页面无法跳转检查文件名混淆、动态路由和页面清单对比成功页面与失败页面的路径写法。第三方 SDK 回调不执行检查 SDK 是否依赖固定类名、方法名或注解反射并按照官方接入要求设置精确保留。崩溃堆栈无法阅读检查是否保存了该 HAP 对应的 name cache以及构建版本是否匹配。十五、Release 验证矩阵 ✅首次启动与身份读取Preferences 旧数据升级自定义网址 JSON 解析和 CRUD所有路由页面可达WebView 参数正常Want 字段和目标 Ability 正常Axios 返回 JSON 可解析AGC SDK 初始化与云模型字段崩溃堆栈能用映射还原应用备份恢复后数据仍兼容。验证应同时比较 debug/release、全新安装/覆盖升级。只有四种组合都通过才能说明混淆没有破坏运行协议。十六、总结混淆的目标是增加分析成本和缩小产物不是改变业务协议。对 ArkTS 项目而言JSON 字段、路由路径、Ability 名称、Bridge 接口和云模型是最关键的保留边界。渐进启用、保存映射、用真实 release 包验证远比“规则越多越安全”更可靠。️