KernelSU 构建指南：从同步 GKI 内核源码到集成 KernelSU 的完整流程-二趣网

KernelSU 构建指南：从同步 GKI 内核源码到集成 KernelSU 的完整流程

【免费下载链接】KernelSUA Kernel based root solution for Android项目地址: https://gitcode.com/GitHub_Trending/ke/KernelSU

导读

本文以 KernelSU 官方构建文档为核心，完整讲解如何在 Android GKI（Generic Kernel Image）内核源码中集成 KernelSU：从同步内核源码、配置构建环境，到运行官方setup.sh一键集成并重新编译出带 KernelSU 的内核镜像。阅读完本文，你将掌握 GKI 内核的可复现构建方法、LTO=thin等关键构建参数的作用、setup.sh脚本的底层实现原理，以及 KernelSU 内核侧 Kconfig 配置选项的含义，从而能够独立为你的设备构建带 KernelSU 的内核。

文档状态与版本背景：GKI 镜像模式已归档，LKM 成为主流

在开始之前需要明确一个重要的版本背景：本文所依据的构建文档（英文原版，本文对应的俄文版本）仅作存档参考，已不再更新维护。自 KernelSU v3.0 起，官方出于更快的迭代与构建速度考虑，放弃了对 GKI 镜像模式（GKI image mode）的官方支持，官方推荐改用Ylarod/ddk构建 LKM（Loadable Kernel Module，可加载内核模块）使用。

根据安装文档的说明，KernelSU 在 GKI 设备上有两种运行模式：

LKM 模式：不替换设备原有内核，而是将可加载内核模块加载进设备内核。优点是无需替换原内核、升级与 OTA 更方便、适合临时 root 等特殊场景，且可临时卸载；
GKI 模式：用 KernelSU 提供的通用内核镜像替换设备原内核。优点是通用性强，只要 KMI 一致即可使用，不依赖官方固件更新。

本文沿袭原文档主题，聚焦 GKI 内核的源码集成与构建流程；对于老内核（非 GKI）设备，请参阅为非 GKI 内核集成 KernelSU。

前置准备：先熟悉 Android 官方内核构建体系

原文档明确要求，动手之前应先通读 Android 官方内核构建文档，重点是以下两份：

Building kernels（构建内核）：讲解使用build/build.sh脚本构建 Android 内核的完整流程；
GKI release builds（GKI 发布构建）：讲解如何获取与重建 GKI 发布版本内核，是下载构建清单（manifest）文件的官方来源。

这两份官方文档是本文后续所有命令的底层依据：repo同步、构建配置、构建清单的获取方式都源于此。如果你对 Android 内核构建体系还不熟悉，建议先完成这部分学习再继续。

构建内核（一）：同步内核源码

构建的第一步是同步与你的设备 KMI 匹配的内核源码。KMI（Kernel Module Interface，内核模块接口）是 GKI 中"通用"的基石——KMI 相同的内核版本相互兼容，KMI 不同则不能混用，刷入 KMI 不匹配的内核镜像可能导致 bootloop。版本号格式为w.x.y-zzz-k-something，其中w.x-zz-k即 KMI 版本；注意 SubLevel（y）并不属于 KMI 的一部分。

在内核源码根目录执行以下命令同步源码：

repo init -u https://android.googlesource.com/kernel/manifest mv <kernel_manifest.xml> .repo/manifests repo init -m manifest.xml repo sync

其中<kernel_manifest.xml>是能够唯一确定一次构建的清单文件，通过它你可以实现可复现（reproducible）构建——即任何人用同一份 manifest 都能得到完全一致的构建结果。该文件需要从 GKI 发布构建页面下载，下载后将其移动到.repo/manifests目录，再用repo init -m manifest.xml指定使用，最后repo sync拉取全部源码。

构建内核（二）：编译 aarch64 内核镜像

源码同步完成后，先查阅 Android 官方内核构建文档，然后开始编译。以构建aarch64内核镜像为例，在源码根目录执行：

LTO=thin BUILD_CONFIG=common/build.config.gki.aarch64 build/build.sh

这里有两点必须注意：

务必添加LTO=thin标志。如果省略，当你的电脑内存小于 24 GB 时，构建很可能会因内存不足而失败。thinLTO（链接时代码优化）相比全量 LTO 大幅降低内存占用，是 GKI 内核构建的标准配置；
BUILD_CONFIG指定了 aarch64 GKI 内核的构建配置文件路径。

从 Android 13 开始，内核构建改由bazel驱动，对应的构建命令为：

tools/bazel build --config=fast //common:kernel_aarch64_dist

此外，针对部分 Android 14 内核，为了让 Wi-Fi / 蓝牙正常工作，可能需要移除所有受 GKI 保护的导出符号文件：

rm common/android/abi_gki_protected_exports_*

这一步并非所有内核都需要，仅在你构建的 Android 14 内核出现无线功能异常时按需执行。

集成 KernelSU：一键 setup 脚本的三种用法

如果你已经能够成功构建内核，那么集成 KernelSU 会非常轻松。在内核源码根目录下，根据自己的需求从以下三种方式中选择任一执行：

方式一：最新 tag（稳定版）

curl -LSs "https://raw.githubusercontent.com/tiann/KernelSU/main/kernel/setup.sh" | bash -

方式二：main 分支（开发版）

curl -LSs "https://raw.githubusercontent.com/tiann/KernelSU/main/kernel/setup.sh" | bash -s main

方式三：指定 tag（例如 v0.5.2）

curl -LSs "https://raw.githubusercontent.com/tiann/KernelSU/main/kernel/setup.sh" | bash -s v0.5.2

三条命令的区别仅在于传给脚本的参数：不带参数时脚本会检出最新的稳定 tag；传main则切换到开发分支；传任意 tag 或 commit 哈希则检出对应版本。curl -LSs中的-L跟随重定向、-S显示错误、-s静默模式，确保脚本被正确下载并交由bash执行。

深入原理：setup.sh 脚本到底做了什么

仓库中的 kernel/setup.sh 就是上述命令实际执行的脚本，阅读其源码可以清晰理解"一键集成"背后的三个步骤：

1. 定位 drivers 目录并克隆 KernelSU 仓库

脚本会在common/drivers或drivers目录中定位内核的驱动目录（找不到则报错退出），然后在当前目录克隆 KernelSU 仓库，检出指定分支或 tag：

test -d "$GKI_ROOT/KernelSU" || git clone https://github.com/tiann/KernelSU cd "$GKI_ROOT/KernelSU" git pull if [ -z "${1-}" ]; then git checkout "$(git describe --abbrev=0 --tags)" # 默认检出最新 tag else git checkout "$1" # 检出指定分支/tag fi

2. 建立符号链接

将 KernelSU 的kernel目录软链接到内核驱动目录下，命名为kernelsu：

cd "$DRIVER_DIR" ln -sf "$(realpath --relative-to="$DRIVER_DIR" "$GKI_ROOT/KernelSU/kernel")" "kernelsu"

3. 改写 Makefile 与 Kconfig

脚本会检查并追加两处配置，把 KernelSU 挂入内核构建体系：

# Makefile 末尾追加：按 CONFIG_KSU 条件编译 kernelsu 子目录 printf "\nobj-\$(CONFIG_KSU) += kernelsu/\n" >> "$DRIVER_MAKEFILE" # Kconfig 的 endmenu 之前追加：引入 KernelSU 的 Kconfig sed -i "/endmenu/i\source \"drivers/kernelsu/Kconfig\"" "$DRIVER_KCONFIG"

此外，脚本还提供了--cleanup参数，可一键撤销上述所有修改（删除符号链接、还原 Makefile 与 Kconfig、删除 KernelSU 目录），方便在构建失败或不需要 KernelSU 时快速回滚；-h/--help显示用法。

内核侧构建配置：Kconfig 选项详解

集成之后，内核构建配置中会出现 KernelSU 的配置菜单。仓库中的 kernel/Kconfig 定义了以下选项：

配置项	类型	默认值	说明
`CONFIG_KSU`	tristate	`y`	内核级 root 功能总开关，依赖`CONFIG_KPROBES`（内核挂钩）与`CONFIG_EXT4_FS`（`ext4_unregister_sysfs`）；选`M`可编译为名为`kernelsu`的内核模块
`CONFIG_KSU_DEBUG`	bool	`n`	开启 KernelSU 调试模式
`CONFIG_KSU_DISABLE_MANAGER`	bool	`n`	禁用管理器 APK 检测与管理器专属处理，root 功能由纯 root 方式替代
`CONFIG_KSU_DISABLE_POLICY`	bool	`n`	禁用按应用的自定义 root/非 root 配置（profile），提权始终使用默认全量 root profile
`CONFIG_KSU_X86_PATCH_SYSCALL_DISPATCHER`	bool	`n`	依赖`KSU && X86_64`，在运行时动态修补 x86_64 加固后的 syscall dispatcher 以支持系统调用挂钩，是 x86_64 LKM 模式下替代内核源码补丁的方案

其中CONFIG_KSU_X86_PATCH_SYSCALL_DISPATCHER对应 x86_64 支持文档中介绍的机制：新版内核为缓解投机执行漏洞加固了系统调用表路径，导致 KernelSU 的 syscall_hook 失效，启用该选项后 KernelSU 会在运行时动态修补加固后的 dispatcher。需要注意：该方案会有意绕过或削弱针对投机执行漏洞的缓解措施，仅适用于测试环境，生产服务器等对侧信道安全要求严格的场景不应使用。

重新构建并验证：得到带 KernelSU 的内核镜像

完成上述集成后，按第一节的命令重新构建内核。此时CONFIG_KSU默认为y，KernelSU 会被编译进内核镜像。

如果你选择将 KernelSU 构建为可加载模块（CONFIG_KSU=M），可以参考仓库中的 kernel/Makefile 进行外部模块构建：它通过KDIR指向内核源码树，执行$(MAKE) -C $(KDIR) M=$(MDIR) modules编译出kernelsu.ko，并用 kernel/tools/check_symbol.c 编译出的check_symbol工具校验模块与vmlinux的符号一致性。

从 kernel/Kbuild 的源码还可以看到两个构建期细节：

版本号自动计算：若 KernelSU 目录是独立 git 仓库，KSU_VERSION会按30000 + git commit 数自动生成并注入-DKSU_VERSION；否则回退到默认值；
管理器签名校验：KSU_EXPECTED_SIZE/KSU_EXPECTED_HASH会在编译期嵌入管理器 APK 的签名信息，内核据此校验管理器身份；需要更换管理器包名时可传入KSU_MANAGER_PACKAGE覆盖。

重新构建完成后，你将得到带有 KernelSU 的内核镜像，可参考安装指南将其刷入设备。

非 GKI 内核用户的替代路径

本文针对 GKI 设备。如果你的设备使用的是老内核（非 GKI），请不要套用本文的构建流程，而应参阅如何为非 GKI 内核集成 KernelSU：该文档介绍了通过kprobe自动集成与手动修改内核源码（在fs/exec.c、fs/open.c、fs/read_write.c、fs/stat.c中插入 KernelSU 挂钩调用）两条路径，但需注意自 KernelSU v1.0 起官方已放弃对非 GKI 设备的官方支持，相关内容同样仅作存档参考。

总结

KernelSU 的内核集成本质上是"三步走"：同步与设备 KMI 匹配的内核源码 → 以LTO=thin或 bazel 完成一次基线构建 → 运行setup.sh集成后重新构建。本文同时从 setup.sh、Kconfig、Kbuild 源码层面解释了脚本的一键集成原理与内核侧配置项含义。需要注意，该 GKI 镜像模式构建流程自 KernelSU v3.0 起已归档，新项目建议优先采用Ylarod/ddk构建 LKM 的方案。

【免费下载链接】KernelSUA Kernel based root solution for Android项目地址: https://gitcode.com/GitHub_Trending/ke/KernelSU

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析