使用说明
NPatch 提供两个东西：
jar-v<verName>-<verCode>-release.jar— 跨平台修补工具，纯 Java，Windows / macOS / Linux 任一平台只要有 Java 就能跑manager-v<verName>-<verCode>-release.apk— Android 端的 NPatch 管理器，本地模式才需要
两者通常一起发布。建议先读 什么是 NPatch，理解两种模式的差别，再回来看怎么用。
获取方式
- 稳定版：GitHub Releases
- Canary 构建：开发者发布的测试版本，请在 Telegram 频道 获取
- Debug 构建：调试版本，仅在 GitHub Actions 上提供
- 官方频道：Telegram
文件名格式
Release 页面上看到的文件名长这样：
jar-v<verName>-<verCode>-release.jar
manager-v<verName>-<verCode>-release.apk对应规则 <artifact>-v<verName>-<verCode>-<variant>.{jar,apk}：
对应规则 `<artifact>-v<verName>-<verCode>-<variant>.{jar,apk}`：
- `verName` — 版本名称（例如 `1.0.5`）
- `verCode` — 版本号（例如 `639`）
- `variant` — 构建类型，`release`（稳定）或 `debug`（GitHub Actions 才有）
## 环境需求
| 项目 | 需求 |
|---|---|
| 修补工具运行环境 | Java（运行 `jar-v<verName>-<verCode>-release.jar`） |
| 平台 | Windows / macOS / Linux 任一即可 |
| Android 版本 | 修补后的应用需要 Android 9 (API 28) 以上 |
## 两种使用方式
### 方式一：用管理器 App（推荐）
把当前版本的 `manager-v<verName>-<verCode>-release.apk` 装到设备上，从界面选择要修补的应用，修补完成后直接安装，全程在设备上完成。对大多数用户来说这是最方便的方式。管理器界面默认使用 High（2）签名绕过。
更多管理器能做的事情看 [管理器与 Shizuku](/guide/manager)。
### 方式二：用 jar 修补
适合批量修补、自动化或 CI 场景。把目标 APK 丢给 jar，产出 `<原名>-<NPatch versionCode>-npatched.apk` 或 `<原名>-npatched.apks`。
```bash
java -jar jar-v<verName>-<verCode>-release.jar [options] <apks...>最小可用示例（本地模式；CLI 默认签名绕过为 Basic）：
java -jar jar-v<verName>-<verCode>-release.jar --manager target.apk修补 Split APK / App Bundle（同时传入 base 与所有 split apk）：
java -jar jar-v<verName>-<verCode>-release.jar --manager base.apk split_config.arm64_v8a.apk split_config.zh.apk集成模式（内嵌一个或多个模块）：
java -jar jar-v<verName>-<verCode>-release.jar --embed module1.apk --embed module2.apk target.apk下面示例中的 <verName> 与 <verCode> 请替换为你实际下载到的版本。
打包与 Split APK (APKS) 支持
NPatch 原生支持单包 APK 以及由多个分包组成的 Split APKs / APKS / App Bundles：
- 单包 APK：直接输出修补后的标准单包 APK。
- Split APKs / APKS：
- NPatch 会自动识别
base.apk与各个配置分包（如 ABI、语言、屏幕密度分包）。 - 在重命名包名（
-p）、版本号修改（-r/--allowdown）或覆盖 TargetSDK 时，自动同步更新全套分包的清单属性，确保分包与基包信息严格一致。 - 分包仅重新对齐并签名，不会嵌套冗余的原始核心包，保持体积轻巧。
- 输出标准化的
.apks归档（内部规范命名为base.apk与split_*.apk），全面兼容系统安装器、安装狮 (InstallLion)、SAI、Shizuku 及各类第三方安装工具。
- NPatch 会自动识别
CLI 选项
对应 top.nkbe.npatch.patch.NPatch 中的 @Parameter 声明。
| 选项 | 说明 | 默认 |
|---|---|---|
<apks> | 要修补的 APK 路径（位置参数，至少一个，可同时传入 base 与 split 分包） | — |
-h, --help | 显示说明 | — |
-o, --output | 输出目录 | .（当前目录） |
-f, --force | 覆盖已存在的输出文件 | 关 |
-p, --newpackage | 修补新包名（自动同步 base 与所有 split 分包） | 不改 |
-d, --debuggable | 应用可调试 | 关 |
-l, --sigbypasslv | 签名绕过等级 0–5（见下） | 1 |
--injectdex | 注入加载器 Dex（孤立进程需要，例如浏览器渲染引擎） | 关 |
--provider | 注入文件选择器（来自 MT 管理器），管理 data 目录文件 | 关 |
--installerSource | 设置原始安装来源字符串 | — |
--useMicroG | 强制启用 MicroG 支持，重定向 GMS 请求至社区版 MicroG | 关 |
--outputLog | 将 Legacy 与 API 101/102 模块 API 日志、框架日志及未捕获的 Java/Kotlin 崩溃异步写入 Media 目录（不阻塞主线程） | 开 |
--hidelibs | 隐藏部分 ART 与敏感系统库可见性，降低基础环境检测命中 | 关 |
-k, --keystore | 自定义签名密钥库，需要 4 个值：path storePass alias aliasPass | — |
-npa, --npatch-keystore | 用内建 NPatch 密钥库 | — |
-fpa, --fpa-keystore | 用内建 FPA 密钥库 | — |
--manager | 启用本地模式（与 --embed 互斥） | — |
-r, --allowdown | 覆盖版本号为 1，允许以后降级安装（自动同步 base 与所有 split 分包） | 关 |
--versioncode | 搭配 --allowdown 指定覆盖后的 versionCode | 1 |
-v, --verbose | 详细打包日志 | 关 |
-m, --embed | 启用集成模式并指定模块 APK，可重复（与 --manager 互斥） | — |
互斥规则
下列规则由 CLI 解析时直接拦截：
--manager与--embed不能同时使用-k不能与-npa或-fpa同时使用-npa与-fpa不能同时使用- Extreme（3）、Seccomp（4）和 Stealth（5）必须搭配
--manager；集成模式（--embed）下，sigbypass 上限为 High（2）
签名绕过等级
直接引用 NPatch 界面中的官方说明：
| 等级 | 名称 | 说明 | 集成模式可用 |
|---|---|---|---|
| 0 | None | 不进行任何处理 | 是 |
| 1 | Basic | 增加 Java IO 与 Native openat / openat64 重定向，让签名相关的文件读取改为访问原始 APK | 是 |
| 2 | High | 基于 Basic，恢复原始 AppComponentFactory，并 hook getPackageArchiveInfo 与 hasSigningCertificate 等更严格的校验路径 | 是 |
| 3 | Extreme | 基于 High，hook PackageInfo(Parcel) 构造函数，覆盖 Binder 反序列化获取签名信息的路径 | 否（需 --manager） |
| 4 | Seccomp | 在 ARM64 上启用 seccomp v2 过滤与 trusted thread 文件重定向，参考 FunPatchApp 的实现方案 | 否（需 --manager） |
| 5 | Stealth | 使用 xhook 重定向应用原生库的 GOT/PLT，同时保留 PackageInfo 签名伪装 | 否（需 --manager） |
实际使用：先试 1，不行再往上调。等级越高不代表越好，部分应用在高等级下反而会异常。
安装修补后的 APK / APKS
由于签名不同，安装前需要先卸载原应用。确保你已备份好个人数据。
WARNING
卸载会清掉应用数据。重要的东西先在原版里备份，或用 ADB 备份。
本地模式的后续步骤
- 安装
manager-v*-release.apk（包名top.nkbe.npatch，如果还没装） - 安装修补后的 APK 或 APKS
- 打开管理器，找到该应用，加入要加载的 Xposed 模块与作用域
- 启动应用，模块就会生效
集成模式的后续步骤
装完修补 APK / APKS 就可以直接用，模块已经放在 assets/npatch/modules/<package>.apk 里。要换模块需要重新修补。
签名方案与自定义密钥库
NPatch 内部采用了完整的 V1 (JAR 签名) + V2 (APK Signature Scheme v2) + V3 (APK Signature Scheme v3) 签名方案，并自动从目标应用提取真实的 minSdkVersion（自适应兼容 Android 5.0+ / minSdk 21+），无需担心因缺少 V1 或 minSdk 错位导致的系统安装失败。
默认会用内建密钥库（不指定时走 -npa 路径）。如果你有自己的密钥库：
java -jar jar-v<verName>-<verCode>-release.jar -k mykey.jks storePass myalias aliasPass --manager target.apk四个位置参数顺序：密钥库路径、密钥库密码、别名、别名密码。内部使用 BKS 格式加载并启用完整的 V1 + V2 + V3 签名。
管理器内也有自定义密钥库设置，界面里可以验证密钥库类型、密码、别名是否正确。