libxposed API XposedInterface 接口参考:hook、deoptimize 与 Invoker 完整 API 详解

原创2026-10-30 15:52:561,917 阅读

libxposed API XposedInterface 接口参考:hook、deoptimize 与 Invoker 完整 API 详解

XposedInterface 是 libxposed API 项目的核心接口,也是编写现代 Xposed 模块(Module)的主要编程入口。它用一套类型安全、设计清晰的 Java 接口替代了传统 XposedBridge API,让模块开发者能够以直观的方式实现 hook 拦截、deoptimize 去内联优化 与 Invoker 方法调用 三大核心能力。

本文带你从零读懂这份接口:每个方法做什么、参数怎么传、返回值怎么用,读完即可上手开发 Xposed 模块。

一、先认识 XposedInterface:接口全景一览

核心定义位于 XposedInterface.java,它声明了四类成员:

类别 内容 用途
常量 API_101、LIB_API、PRIORITY_*、PROP_CAP_* API 版本与框架能力标识
内部接口 Invoker、Chain、Hooker、HookHandle、HookBuilder hook 链路的各个角色
枚举 ExceptionMode 控制 hook 内异常的处理方式
实例方法 hook()、deoptimize()、getInvoker() 等 模块实际调用的功能

几个关键常量值得记住:

  • API_101 = 101:首个 API 版本,也是当前库版本 LIB_API。
  • PRIORITY_DEFAULT = 50:hook 的默认优先级;数值越大越先执行,PRIORITY_HIGHEST / PRIORITY_LOWEST 分别是拦截链的首尾。
  • PROP_CAP_SYSTEM / PROP_CAP_REMOTE:通过位标志判断框架是否支持 hook 系统进程、是否支持远程配置(见 getFrameworkProperties)。

💡 模块开发者的实际入口是 XposedModule.java,它继承 XposedInterfaceWrapper 并实现生命周期回调接口 XposedModuleInterface。框架启动时会调用 attachFramework() 自动接入底层实现,你不需要手动调用。

二、hook 完整流程:从 hook(Executable) 到 HookHandle

1. 发起 hook:hook() 与 hookClassInitializer()

hook(Executable origin) 接收一个 Method 或 Constructor(统称 Executable),返回一个 HookBuilder。另外还有一个姊妹方法:

  • hookClassInitializer(Class<?> origin):hook 类的静态初始化块 <clinit>。此时 Chain.getThisObject() 恒为 null,参数列表为空;注意如果类已经被初始化过,hook 将永远不会触发。

2. 配置 hook:HookBuilder 的三件套

HookBuilder 采用建造者模式,支持链式调用(源码 L318-L347):

方法 作用 默认值
setPriority(int) 设置优先级,数值大者先执行 PRIORITY_DEFAULT(50)
setExceptionMode(ExceptionMode) 设置 hook 内异常处理方式 DEFAULT
intercept(Hooker) 传入拦截器并完成 hook —

intercept() 是最后一步,它会返回 HookHandle;若目标不可 hook(如 Constructor#newInstance 本身),抛出 IllegalArgumentException;框架内部错误则抛出 HookFailedError。

3. 实现 Hooker 与操作 Chain

Hooker 只有一个方法 intercept(Chain chain),所有拦截逻辑都写在这里。Chain 提供了操作调用现场的全部工具:

方法 说明
getExecutable() / getThisObject() / getArgs() / getArg(int) 读取被 hook 的方法、this 指针、参数列表(参数列表不可变)
proceed() 以相同参数继续调用下一个拦截器或原方法
proceed(Object[] args) 以新参数继续(实现参数篡改)
proceedWith(Object thisObject) / proceedWith(this, args) 替换 this 指针继续(静态方法拦截器不要调用)

返回 proceed() 的结果即可透传返回值;想直接改写返回值,只需返回自定义值。void 方法与构造函数的返回值会被框架忽略。

4. 取消 hook:HookHandle

HookHandle 是 hook 的"句柄",getExecutable() 可查目标,unhook() 用于取消——该方法幂等,重复调用安全。

5. 三种异常模式:ExceptionMode 怎么选?

ExceptionMode 决定 hooker 自身抛出的异常如何被框架处理:

模式 行为 适用场景
DEFAULT 跟随 module.prop 中的全局 exceptionMode,未配置时按 PROTECTIVE 处理 常规默认选择
PROTECTIVE hook 内异常被捕获并记录日志,调用像"没有 hook"一样继续 生产环境推荐,防止模块 bug 搞崩宿主应用
PASSTHROUGH 异常原样抛给调用方 调试期快速定位问题

⚠️ 注意:无论哪种模式,proceed() 抛出的异常(即原方法自己的异常)始终会正常传播。

三、deoptimize:hook 不生效时的"去内联"大招

这是很多新手踩坑的地方:方法 B 已被 hook,但调用方 A 对 B 的调用却"没反应"。原因通常是 ART 虚拟机把 B **内联(inline)**进了 A 的方法体,导致 B 的 hook 链路根本没被走到。

deoptimize(Executable executable) 就是用来解决这个问题的:把它对某个方法的优化降级掉,运行时会回退为"老老实实逐个调用",hook 随之生效。

使用建议(源自官方注释):

  • 你需要对被 hook 方法的调用方调用 deoptimize,返回值 boolean 表示是否成功。
  • 定位所有调用方很困难,如果只确认了一部分调用点,宁可换 hook 点,或者干脆整体去内联——最简单的方式是卸载重装应用而不卸载(reinstall without uninstall)。

四、Invoker 体系:绕过访问检查的方法调用器

在 hook 拦截器里想反向调用目标方法时,普通反射会受访问权限限制。getInvoker() 提供两种重载(Method 版 / Constructor 版),返回的 Invoker 绕过访问检查执行调用。

1. Invoker 的两个调用方法

方法 用途
invoke(Object thisObject, Object... args) 按 Invoker 类型走对应 hook 链调用方法;静态方法传 null 作为 this
invokeSpecial(Object thisObject, Object... args) 类似 JNI 的 CallNonVirtual<type>Method,直接调用指定类中定义的方法、绕过子类重写。典型场景:在被 hook 的构造函数里调用 super.xxx()

2. 用 setType 控制走哪段 hook 链

Invoker.Type 决定调用时执行哪部分拦截链:

类型 行为
Type.ORIGIN(Origin) 跳过所有 hook,直接执行原始方法
Type.Chain.FULL 走完整 hook 链(默认值)
new Type.Chain(maxPriority) 从链中间开始,只包含优先级 ≤ maxPriority 的 hook——可避免自己刚注册的 hook 造成无限递归

3. CtorInvoker:构造函数的专属能力

CtorInvoker 在 Invoker 基础上增加:

  • newInstance(Object... args):走 hook 链创建并初始化新实例。
  • newInstanceSpecial(Class<U> subClass, Object... args):用父类构造函数初始化子类对象(等价于 new 子类() 但跳过 super() 链上的子类构造逻辑)。对象可能处于"部分初始化"状态,适用于你需要自己补全子类字段的场景。

五、实用辅助 API:日志与远程配置

方法 说明
log(int, String, String) / 带 Throwable 重载 写入 Xposed 日志,priority 同 android.util.Log 级别
getFrameworkName() / getFrameworkVersion() / getFrameworkVersionCode() / getApiVersion() 查询当前框架与 API 版本,建议用 getApiVersion() 做运行时版本判断
getRemotePreferences(String group) 读取存放在框架侧的远程 SharedPreferences(被 hook 的应用内只读)
listRemoteFiles() / openRemoteFile(String) 列出 / 只读打开模块共享数据目录中的文件

💡 远程配置与远程文件依赖 PROP_CAP_REMOTE 能力;嵌入式框架会抛 UnsupportedOperationException。

六、错误处理:见到 XposedFrameworkError 该怎么办

框架级错误统一由 XposedFrameworkError(继承自 Error)表示。其中最关键的是 HookFailedError:

  • 含义:hook 因框架内部错误失败,属于致命的框架级 bug;
  • 官方设计立场:模块开发者不应该捕获它做降级兜底,而应上报给框架维护者,从根源修复。

七、关键文件速查表

文件 内容
XposedInterface.java 核心接口:hook / deoptimize / Invoker / 日志 / 远程配置
XposedModule.java 模块入口基类
XposedModuleInterface.java 生命周期回调:onModuleLoaded、onPackageLoaded、onPackageReady、onSystemServerStarting
XposedInterfaceWrapper.java 屏蔽框架实现细节的包装类
error/HookFailedError.java 致命 hook 失败错误
package-info.java 包级文档:模块注册(META-INF/xposed/)、module.prop 配置、scope 规则等

八、新手上手清单

  1. 入口类继承 XposedModule,在 onModuleLoaded() 之后再做初始化;
  2. 用 hook(method).setPriority(...).setExceptionMode(...).intercept(chain -> ...) 完成一次 hook,牢记"想透传就 return chain.proceed()";
  3. hook 不触发时优先怀疑内联,对相关调用方调用 deoptimize();
  4. 需要反射调用目标方法时,用 getInvoker() 而不是裸反射,并用 setType() 防递归;
  5. 生产环境默认 PROTECTIVE 异常模式,HookFailedError 不要吞掉,直接反馈给框架方。

按照这份接口参考,你已经掌握了 libxposed API 的全部核心能力——现代 Xposed 模块开发,从这里开始。

登录后查看全文
api