libxposed API 生命周期回调深度解析:从 onModuleLoaded 到 onPackageReady 的 4 大时机
libxposed API 生命周期回调深度解析:从 onModuleLoaded 到 onPackageReady 的 4 大时机
libxposed API 是 Xposed 生态中的现代模块开发接口(当前 API 版本 101),用类型安全的设计取代了传统 XposedBridge。它通过 onModuleLoaded、onPackageLoaded、onPackageReady、onSystemServerStarting 四大生命周期回调,把"模块加载进目标进程"的全过程切成清晰的时机——选对时机,你的 Hook 才能稳稳生效。这篇文章帮你把每个回调何时触发、带什么参数、适合干什么一次讲透。
一、libxposed API 是什么?为什么需要生命周期回调?
简单来说:
- 📦 模块入口:你的模块入口类继承 XposedModule,它会继承 XposedInterfaceWrapper 并实现 XposedModuleInterface 接口。
- ⏱️ 每个进程只实例化一次:入口类在每个目标进程中只会被创建一次,框架在合适的时机依次回调你的生命周期方法。
- 🚫 不要在回调前做事:源码明确要求,模块不应在
onModuleLoaded()被调用之前做初始化(此时框架接口可能尚未绑定)。
注意行为变化:从 API 101 开始,模块不能再注入 zygote,只会被加载进作用域(scope)声明的目标进程中,见 XposedInterface.java 中的 API 说明。
二、4 大回调时机总览
先看一张总览表,建立整体认知(定义见 XposedModuleInterface.java):
| 回调 | 触发时机 | 参数对象 | 最低要求 |
|---|---|---|---|
onModuleLoaded |
模块加载进目标进程后,每进程仅一次 | ModuleLoadedParam |
API 101 |
onPackageLoaded |
默认 ClassLoader 就绪,但 AppComponentFactory 实例化之前 |
PackageLoadedParam |
Android 10(API 29) |
onPackageReady |
ClassLoader 已创建,即将创建 Application |
PackageReadyParam |
API 101 |
onSystemServerStarting |
system server 准备启动关键服务时 | SystemServerStartingParam |
API 101 |
四个回调按进程启动顺序大致为:
onModuleLoaded → onPackageLoaded / onSystemServerStarting → onPackageReady
(每进程1次) (每个被加载的包1次,多包会多次) (每个被加载的包1次)
三、onModuleLoaded:进程级初始化的起点
onModuleLoaded 保证在每个进程中被且仅被调用一次,适合放全局初始化逻辑。它的参数 ModuleLoadedParam 提供了进程级信息:
isSystemServer():当前是否是 system server 进程;getProcessName():当前进程名。
✅ 适合做什么:打日志确认模块已加载、读取远程配置、按进程名过滤、决定本次进程要执行哪些功能。
四、onPackageLoaded:默认 ClassLoader 就绪的瞬间
这是 Android 10(API 29)+ 才有的回调,发生在默认 ClassLoader 已就绪、AppComponentFactory 实例化之前(见 onPackageLoaded 定义)。参数 PackageLoadedParam 包含:
| 方法 | 说明 |
|---|---|
getPackageName() |
当前加载的包名 |
getApplicationInfo() |
该包的 ApplicationInfo |
isFirstPackage() |
是否是进程中第一个加载的主包 |
getDefaultClassLoader() |
加载该包代码/资源的默认 ClassLoader |
⚠️ 两个易踩的坑:
- 一个进程可能加载多个包(如
sharedUserId共享、或createPackageContext带CONTEXT_INCLUDE_CODE),所以该回调对每个包名各触发一次,务必按包名过滤; - 在 system server 中,第一次回调会被
onSystemServerStarting取代,因此那里isFirstPackage()永远不会是true。
五、onPackageReady:写 Hook 的黄金时机
onPackageReady 在 AppComponentFactory 已实例化 ClassLoader、即将创建 Application 时触发(见 onPackageReady 定义)。参数 PackageReadyParam 在 PackageLoadedParam 基础上多两个方法:
getClassLoader():该包真正的 ClassLoader(若自定义了AppComponentFactory,可能与默认的不同);getAppComponentFactory():该包的AppComponentFactory。
此时目标 App 的代码已经可被加载、但业务逻辑尚未开始运行,是查找目标类、挂接 Hook 的最佳位置:
public class MyModule extends XposedModule {
@Override
public void onModuleLoaded(ModuleLoadedParam param) {
log(Log.INFO, "MyModule", "已加载进进程: " + param.getProcessName());
}
@Override
public void onPackageReady(PackageReadyParam param) {
if (!"com.example.app".equals(param.getPackageName())) {
return; // 只处理目标应用
}
ClassLoader loader = param.getClassLoader();
// 在这里查找目标类,用 hook(method).intercept(chain -> { ... }) 挂接
}
}
libxposed 采用类似 OkHttp 的拦截器链模型:hook(executable) 返回构建器,可设置优先级(PRIORITY_DEFAULT 为 50)与异常模式,再交给 intercept() 挂接,详见 package-info.java 的 Hook Model 说明。
六、onSystemServerStarting:面向 system server 的特殊时机
当模块作用域包含虚拟包名 system 时,system server 会调用 onSystemServerStarting。它的参数 SystemServerStartingParam 提供 system server 的 ClassLoader。
关键点:它取代了第一轮 onPackageLoaded / onPackageReady——所以如果你的模块要覆盖 system server 场景,需要单独处理这条分支。
七、异常与错误处理:回调挂了也不会崩掉目标 App
- 🛡️ 回调异常被安全接住:每个生命周期回调的 Javadoc 都写明"回调抛出的所有 RuntimeException 都会被捕获并记录日志",不会导致目标应用崩溃。
- 🚨
HookFailedError不是让你兜底的:HookFailedError 继承自Error(而非RuntimeException),表示框架内部错误。设计文档明确建议:模块开发者不应捕获它做降级处理,而应上报给框架维护者。其父类为 XposedFrameworkError。 - ⚙️ 异常模式可配置:Hook 级别的
ExceptionMode(DEFAULT/PROTECTIVE/PASSTHROUGH)可在module.prop中用exceptionMode指定,默认为protective,定义见 ExceptionMode。
八、快速上手清单:让回调真正跑起来
想让四大时机按预期触发,配置缺一不可:
- 引入依赖(模块开发用
compileOnly):
dependencies {
compileOnly("io.github.libxposed:api:101.0.1")
}
- 注册入口类:Java 入口类全限定名写入
META-INF/xposed/java_init.list(每行一个),放在src/main/resources/META-INF/xposed/下即可被自动打包; - 声明版本:
META-INF/xposed/module.prop中必须包含minApiVersion与targetApiVersion; - 声明作用域:
META-INF/xposed/scope.list中列出目标包名。注入后,该进程中每个被加载的包都会触发回调,所以模块必须按进程名 + 包名双重过滤。
更多约定(如 staticScope、system 虚拟包名等)见 package-info.java。
九、最佳实践总结
| 时机 | ✅ 推荐 | ❌ 避免 |
|---|---|---|
onModuleLoaded |
日志、全局状态、按进程过滤 | 查找目标 App 的类 |
onPackageLoaded |
提前准备类查找、读包信息 | 假设 isFirstPackage() 必为 true |
onPackageReady |
查找类、挂接 Hook | 不做包名过滤就 Hook 一切 |
onSystemServerStarting |
system 场景专用初始化 | 与普通 App 逻辑混在一起 |
一句话记住这条主线:先认进程(onModuleLoaded)→ 再看包(onPackageLoaded / onSystemServerStarting)→ 最后动手 Hook(onPackageReady)。掌握了这 4 大时机,你就能在任何 libxposed 框架上写出稳定可控的模块。