libxposed API XposedInterface 接口参考:hook、deoptimize 与 Invoker 完整 API 详解
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 规则等 |
八、新手上手清单
- 入口类继承 XposedModule,在
onModuleLoaded()之后再做初始化; - 用
hook(method).setPriority(...).setExceptionMode(...).intercept(chain -> ...)完成一次 hook,牢记"想透传就return chain.proceed()"; - hook 不触发时优先怀疑内联,对相关调用方调用
deoptimize(); - 需要反射调用目标方法时,用
getInvoker()而不是裸反射,并用setType()防递归; - 生产环境默认
PROTECTIVE异常模式,HookFailedError不要吞掉,直接反馈给框架方。
按照这份接口参考,你已经掌握了 libxposed API 的全部核心能力——现代 Xposed 模块开发,从这里开始。