原生Xposed服务集成指南

该文档适用于适配非Xposed标签的原生镜像，使用原生Xposed激活组件，避免开源Xposed库导致风控等问题。

一、适用范围

本文用于指导开发者在 FoxPhone 支持的原生镜像中集成 Xposed 服务预启或伴随能力。当前支持以下 Android 系统：

AOSP 10
AOSP 12

请勿同时引入其他开源 Xposed Bridge 依赖。本文提供的 AAR 使用平台适配后的接口命名空间，混用其他 Bridge 库可能造成类冲突、加载失败或引入额外风控特征。

二、下载集成依赖

下载平台提供的 AAR，并将文件名保持为 xposed-bridge-debug.aar：

xposed-bridge-debug.aar 264.87 KB

文件大小：271231 bytes（约 264.87 KB）
SHA-256：D9DC538315E875D83357B3986CC27D1F7535BE17D9F3F6E69C2F327C9A23FC98
最低 Android API：26

三、最佳安卓Demo实践案例

步骤一：创建 Android 工程

在 Android Studio 中创建一个 Android 项目。
模板选择 No Activity，避免生成与集成无关的页面代码。
示例可使用 Java；使用 Kotlin 时请按相同接口完成入口类实现。

Android Studio 创建 No Activity 项目

步骤二：引入 AAR

在 App 模块下创建 libs 目录。
将 xposed-bridge-debug.aar 放入 app/libs/。
在 app/build.gradle.kts 的依赖中以 compileOnly 方式引用，避免将 Bridge 实现重复打包进 APK。

dependencies {
    compileOnly(files("libs/xposed-bridge-debug.aar"))
}

如果项目使用 Groovy DSL，可在 app/build.gradle 中配置：

dependencies {
    compileOnly files('libs/xposed-bridge-debug.aar')
}

步骤三：配置模块入口

在 app/src/main/ 下创建 assets 目录。
在该目录中创建无扩展名文件 xposed_init。
文件中每行填写一个入口类的完整类名。示例：

com.example.myapplication.Main

xposed_init 中的包名和类名必须与源码完全一致，否则原生组件无法找到入口类。

步骤四：实现入口类

AAR 中的接口包名是 de.robv.android.examed，不是开源 Xposed 库常见的 de.robv.android.xposed。入口类示例：

package com.example.myapplication;

import de.robv.android.examed.IXposedHookLoadPackage;
import de.robv.android.examed.XposedBridge;
import de.robv.android.examed.callbacks.XC_LoadPackage;

public class Main implements IXposedHookLoadPackage {
    @Override
    public void handleLoadPackage(XC_LoadPackage.LoadPackageParam loadPackageParam)
            throws Throwable {
        // 必须先限制目标包，避免在所有应用进程中执行初始化逻辑。
        if (!"com.example.target".equals(loadPackageParam.packageName)) {
            return;
        }

        XposedBridge.log("Native Xposed module loaded: "
                + loadPackageParam.packageName);

        // 在此处实现经过授权的服务预启或伴随逻辑。
    }
}

请将示例中的 com.example.target 替换为实际目标应用包名，并将业务逻辑限制在已获授权的应用和场景内。

步骤五：检查工程结构

完成配置后，至少应包含以下文件：

app/libs/xposed-bridge-debug.aar
app/src/main/assets/xposed_init
app/src/main/java/.../Main.java 或对应 Kotlin 文件
app/src/main/AndroidManifest.xml
app/build.gradle.kts 或 app/build.gradle

原生 Xposed 模块工程结构

步骤六：配置混淆规则

如果发布构建启用了 R8 或 ProGuard，需要保留入口类，防止类名被修改或删除：

-keep class com.example.myapplication.Main { *; }

如果修改了入口类包名，请同步修改 xposed_init 和混淆规则。

步骤七：构建与验证

执行 Gradle Sync，确认 AAR 依赖可正常解析。
构建 APK，并确认 APK 中包含 assets/xposed_init。
将 APK 安装到符合要求的原生镜像实例。
通过 FoxPhone 原生 Xposed 激活组件启用模块。
启动目标应用，检查日志中是否出现入口类输出，并验证业务逻辑只在目标包中执行。

四、常见问题

1. 模块安装后没有执行

确认实例使用受支持的 AOSP 10 或 AOSP 12 原生镜像，检查模块是否已通过原生组件激活，以及 xposed_init 中的完整类名是否正确。

2. 编译时找不到 Xposed 接口

检查 AAR 是否位于 app/libs/，Gradle 文件中的路径是否正确，并确认导入的是 de.robv.android.examed 命名空间。

3. Release 包正常安装但入口没有执行

检查 R8 或 ProGuard 是否修改或删除了入口类，并核对混淆规则与 xposed_init 是否一致。

4. 运行时出现重复类或 Bridge 冲突

移除其他 Xposed Bridge 依赖，并确认平台 AAR 使用 compileOnly 引入，没有被重复打包进 APK。

5. 模块影响了非目标应用

应在入口方法最前面按 packageName 过滤目标包，非目标进程立即返回。