更新记录

1.0.1（2026-09-11）

首次发版

平台兼容性

uni-app(3.8.3)

uts-harden · APP 运行时自保护哨兵

一个基于 uni-app UTS 原生插件的 APP 运行时安全自检与加固 SDK。在应用运行阶段持续检测设备是否处于被调试、Root/越狱、模拟器、Hook 框架等风险环境，并支持 APK 签名校验与调试标志检测，帮助提升逆向与重打包成本。

重要声明：本插件提供的是运行时防护 + 提高逆向门槛，无法让 APK 达到“绝对不可反编译”。如需更高安全等级，请配合 ProGuard/R8 代码混淆、商业加固方案（梆梆/360/腾讯/网易易盾/爱加密等）以及将核心敏感逻辑放到服务端。

功能特性

• 反调试：检测 APP 是否正在被调试器附加（Android /proc/self/status TracerPid + Debug.isDebuggerConnected；iOS 进程父子关系）。
• Root / 越狱检测：检查常见 Root 管理器、su 路径、Magisk 包名与 test-keys 等特征（Android）；检查 Cydia、MobileSubstrate 路径与 URL Scheme（iOS）。
• 模拟器识别：覆盖主流模拟器指纹，包括 x86 架构、goldfish/ranchu、QEMU/VBox、特殊 Build.HARDWARE、IMEI 异常等。
• Hook 框架检测：识别 Frida、Xposed、LSPosed、Substrate 等常见 Hook 框架特征。
• 签名 / 重打包校验：将运行期 APK 证书 SHA-256 与预期值比对，发现重打包或签名异常。
• 篡改 / 调试标志检测：检查 release 包是否意外开启 android:debuggable。
• 定时持续监控：支持按设定周期轮询检测，命中风险时通过回调上报，并可配置自动退出。
• NDK 原生加固（Android）：核心检测下沉到 libharden.so（C/C++），增强对抗 Java 层 Hook 与反编译能力。

平台支持

iOS 当前为基础检测阶段，反调试、签名校验等完整能力将在后续版本深化。

安装

1. 将本插件导入到项目根目录的 uni_modules/ 下。
2. 在 manifest.json → App 模块配置 中确认已勾选对应原生模块。
3. Android 端已预置 4 个 ABI 的 libharden.so（armeabi-v7a / arm64-v8a / x86 / x86_64），无需额外配置即可使用。
4. 使用 自定义云基座 或 标准基座 真机运行验证。

快速开始

import { initHarden, hardenCheck, startMonitor, stopMonitor } from '@/uni_modules/uts-harden'

// 1. 初始化（expectedSignatureSha256 不传或为空则跳过签名比对）
initHarden({
  expectedSignatureSha256: '',   // 你的发布证书 SHA-256，去掉冒号、小写十六进制
  exitOnViolation: false,        // true=命中风险直接退出 App；false=仅回调/上报
  checks: {                      // 缺省全部开启，可按需关闭
    debug: true,
    root: true,
    emulator: true,
    hook: true,
    signature: true,
    tamper: true
  }
})

// 2. 一次性体检
const report = hardenCheck()
console.log('综合安全:', report.safe)
// report.safe 为 false 表示至少命中一项风险

// 3. 持续监控（按周期轮询，异常时回调）
startMonitor({
  intervalMs: 2000,
  onViolation: (v) => {
    console.warn(`风险项: ${v.item}, 详情: ${v.detail}`)
  }
})

// 4. 停止持续监控
// stopMonitor()

API 文档

initHarden(options?: HardenOptions): void

初始化插件。建议在整个应用生命周期内尽早调用（如 App.vue 的 onLaunch）。

type HardenOptions = {
  /** 期望的 APK 证书 SHA-256（去掉冒号、小写十六进制）。不传或为空则跳过签名比对 */
  expectedSignatureSha256?: string,
  /** 命中风险是否直接退出 App，默认 false */
  exitOnViolation?: boolean,
  /** 各检测项开关，缺省全部开启 */
  checks?: {
    debug?: boolean,
    root?: boolean,
    emulator?: boolean,
    hook?: boolean,
    signature?: boolean,
    tamper?: boolean
  }
}

hardenCheck(): HardenReport

执行一次性完整检测，返回结构化报告。

type HardenReport = {
  safe: boolean,           // 综合是否安全
  debug: HardenItemResult,
  root: HardenItemResult,
  emulator: HardenItemResult,
  hook: HardenItemResult,
  signature: HardenItemResult,
  tamper: HardenItemResult
}

type HardenItemResult = {
  passed: boolean,         // 是否通过（未命中风险）
  risk: boolean,           // 是否命中风险
  detail: string           // 检测详情说明
}

startMonitor(options?: HardenMonitorOptions): void

启动定时持续监控。命中风险时会触发 onViolation 回调；若 initHarden 时设置 exitOnViolation: true，命中后还会自动退出 App。

type HardenMonitorOptions = {
  /** 检测周期，单位毫秒，默认 2000 */
  intervalMs?: number,
  /** 命中风险时的回调 */
  onViolation?: (v: HardenViolation) => void
}

type HardenViolation = {
  item: string,   // 风险项，如 'debug' | 'root' | 'emulator' | 'hook' | 'signature' | 'tamper'
  detail: string  // 详情说明
}

stopMonitor(): void

停止持续监控，释放原生定时器与回调。

检测项说明

配置签名 SHA-256

在 HBuilderX 中打开项目 → manifest.json → App 常用设置 → 查看/设置签名证书。获取证书 SHA-256 后，去掉所有冒号并转为小写，填入 expectedSignatureSha256。

示例：

initHarden({
  expectedSignatureSha256: 'a1b2c3d4e5f6...', // 64 位小写十六进制，无冒号
})

最佳实践

1. 尽早初始化：建议在 App.vue 的 onLaunch 中调用 initHarden，再做一次性 hardenCheck。
2. 关键页面二次校验：在登录、支付、核心功能入口等位置再次调用 hardenCheck()。
3. 持续监控 + 埋点：startMonitor 用于高敏感业务场景，命中风险时上报服务端并记录上下文。
4. 不要硬编码敏感逻辑：本插件仅做环境检测，业务核心逻辑仍应放在服务端或配合商业加固。
5. 真机验证：检测项依赖原生能力，务必使用自定义云基座或真机包测试，不要只依赖模拟器/HBuilderX 内置调试。

常见问题

Q：为什么模拟器上检测全绿？ A：若你的测试目标是 x86 架构模拟器，请确保 utssdk/app-android/libs/ 下包含对应 ABI 的 libharden.so（x86 / x86_64）。同时注意部分模拟器会伪造 Build 指纹，插件已扩展 x86 架构与常见模拟器特征检测。

Q：签名一直不一致怎么办？ A：请确认 expectedSignatureSha256 已去掉冒号并转为小写。本插件内部使用 split(':').join('').toLowerCase() 做归一化比对。不同签名证书（测试证书 / 发布证书 / 云打包证书）的 SHA-256 也不同，请使用与运行包一致的证书。

Q：持续监控提示“回调函数已释放”？ A：请确保使用本插件最新版本，并正确调用 startMonitor 传入 onViolation 回调。插件内部已使用原生 Handler/Timer + @UTSJS.keepAlive 保持回调存活，旧版本使用 setInterval 会出现跨 tick 释放问题。

Q：iOS 支持哪些检测？ A：iOS 当前为基础阶段，支持越狱与模拟器基础识别；完整反调试、签名校验等将在后续版本完成。

隐私与权限

• 本插件仅在本地读取设备环境与 APK 元数据，不上传任何数据。
• 不需要额外系统权限。