libxposed API 生命周期回调深度解析:从 onModuleLoaded 到 onPackageReady 的 4 大时机

原创2026-10-30 11:05:151,814 阅读

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

⚠️ 两个易踩的坑:

  1. 一个进程可能加载多个包(如 sharedUserId 共享、或 createPackageContext 带 CONTEXT_INCLUDE_CODE),所以该回调对每个包名各触发一次,务必按包名过滤;
  2. 在 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。

八、快速上手清单:让回调真正跑起来

想让四大时机按预期触发,配置缺一不可:

  1. 引入依赖(模块开发用 compileOnly):
dependencies {
    compileOnly("io.github.libxposed:api:101.0.1")
}
  1. 注册入口类:Java 入口类全限定名写入 META-INF/xposed/java_init.list(每行一个),放在 src/main/resources/META-INF/xposed/ 下即可被自动打包;
  2. 声明版本:META-INF/xposed/module.prop 中必须包含 minApiVersion 与 targetApiVersion;
  3. 声明作用域: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 框架上写出稳定可控的模块。

登录后查看全文
api