中文 | English

KernelSU Action

用 GitHub Actions 为 Android 内核集成 KernelSU（及其各种分支）、SUSFS 与常用补丁，并产出可刷入的 AnyKernel3 包。

需要一定的内核与 Android 基础知识。

警告 ⚠️

如果你不是内核作者，使用他人的劳动成果构建 KernelSU，请仅供自己使用，不要分享给别人，这是对原作者劳动成果的尊重。

支持范围

内核版本	状态
4.9 4.14 4.19 5.4	Non-GKI，完整支持
5.10 5.15 6.1 6.6 6.12	GKI 源码树，使用 make 构建

本仓库构建的是**源码内置（built-in）**内核。若你只想要 GKI 的 LKM 模块（kernelsu.ko），请直接用上游的 DDK 方案。

快速开始

1. Fork 本仓库。
2. 编辑 config.env，至少填好 KERNEL_SOURCE、KERNEL_SOURCE_BRANCH、KERNEL_CONFIG、KERNEL_IMAGE_NAME。
3. 打开 Actions → Build Kernel → Run workflow。
4. 在弹出的表单里选择 KernelSU 分支、是否启用 SUSFS 等，然后运行。
5. 构建完成后在 Artifacts 下载 AnyKernel3 压缩包，在 Recovery 中刷入。

表单里的下拉框默认都是 config，意思是"用配置文件里写的值"。只有你主动改成别的值时，它才会覆盖 config.env 中的同名配置——所以日常调参不需要提交任何改动，而直接点运行也一定是按你配置文件里的设定来构建，不会因为某个开关默认关着就把你配置里开启的功能悄悄关掉。

想给多台设备各留一份配置，就把 config.env 复制成 config/<设备名>.env，运行时在 Config file to build 里填该路径。

支持的 KernelSU 分支

用 KSU_VARIANT 选择：

取值	项目	说明
none	—	不集成 root，纯编译内核
kernelsu	tiann/KernelSU	官方原版。v1.0 起不再支持 Non-GKI，旧内核会自动锁定到 v0.9.5
kernelsu-next	KernelSU-Next	分支为 dev（默认）/ stable / legacy；旧内核请用 legacy
sukisu-ultra	SukiSU-Ultra	main 为 v4 模块化树（支持 KPM）；builtin 为源码内置树，且是唯一自带 SUSFS 的分支
resukisu	ReSukiSU	SukiSU-Ultra 的再分支，主打旧内核/Non-GKI 兼容与多管理器支持
rsuntk	rsuntk/KernelSU	即 RKSU
backslashxx	backslashxx/KernelSU	以手动 hook 为主

KSU_REF 填分支名、tag 或 commit。留空则按你的内核版本自动挑一个合适的引用。

为什么必须校验 KSU_REF

所有分支的 setup.sh 结尾都是 git checkout "$1" || echo "[-] Checkout default branch"。 也就是说，填一个不存在的分支名不会报错，只会悄悄留在默认分支上。 比如按旧文档给 SukiSU-Ultra 传 susfs-main（该分支实际上并不存在）， 构建会"成功"，但产出的内核根本没有 SUSFS。 本 Action 会在调用 setup.sh 之前校验引用是否存在，不存在就直接失败并列出可用分支。

SUSFS

ENABLE_SUSFS=true 即可。补丁来自 susfs4ksu，分支按内核版本自动选择：

内核	SUSFS 分支
4.9 / 4.14 / 4.19 / 5.4	kernel-<版本>
5.10	gki-android12-5.10
5.15	gki-android13-5.15
6.1	gki-android14-6.1
6.6	gki-android15-6.6
6.12	gki-android16-6.12

自动映射不对时用 SUSFS_BRANCH 手动指定（例如你的 5.10 树其实基于 android13）。

流程为：拷贝 fs/susfs.c 与 include/linux/susfs*.h → 打内核侧 50_add_susfs_in_*.patch → 打 KernelSU 侧 10_enable_susfs_for_ksu.patch。最后一步在所选分支自带 SUSFS 时会自动跳过（例如 SukiSU-Ultra 的 builtin）。

已知坑：susfs4ksu 的 Non-GKI 分支自 2025 年初就没再更新，仍然针对 KernelSU 的旧扁平目录结构。而多数分支此后都重构成了模块化的 kernel/ 目录，因此"旧内核 + 新分支 + SUSFS"这个组合的 KernelSU 侧补丁可能打不上。遇到这种情况，改用 KSU_VARIANT=sukisu-ultra + KSU_REF=builtin（自带 SUSFS，不需要那个补丁）最省事。构建失败时日志里会直接给出这段提示。

path_umount

path_umount() 是 Linux 5.9 才引入的。KernelSU 靠它在应用检测 root 前卸载自己的挂载，所以更旧的内核需要回移这个函数，否则"卸载模块挂载"会静默失效。

ENABLE_PATH_UMOUNT=true 即可，代码直接取自上游，插入到 fs/namespace.c 中 do_umount() 之后。在 5.9+ 的内核上会自动跳过；已经有该函数时也会跳过。

其它补丁

选项	作用
ENABLE_HIDE_STUFF	额外清除内核中的 KernelSU 痕迹
ENABLE_KPM	SukiSU-Ultra 的 Kernel Patch Module 支持，编译后对 Image 执行 patch_linux。仅 sukisu-ultra + arm64
KSU_HOOK_MODE	hook 方式：auto（5.10+ 用 kprobes，更旧的用 manual）/ kprobes / manual / tracepoint / syscall / none

旧内核上 kprobes 经常是"KernelSU 装上了但 su 没反应"的元凶，此时用 manual。

工具链

AOSP 的 clang 预编译仓库有个陷阱：每个 kernel-build 分支都会列出所有版本目录，但其中只有一两个真的有工具链，其余是空占位符——而空目录生成的 tar 包能以 HTTP 200 正常下载，只是解开后是空的。所以版本写错不会 404，只会在几十分钟后报 clang: not found。

已验证可用的组合（2026-07）：

CLANG_BRANCH	CLANG_VERSION
main-kernel	r596125（最新）
main-kernel-2026	r584948c
main-kernel-2025	r547379
main-kernel-build-2024	r510928
master-kernel-build-2022	r450784e

新版 clang 在 4.x 树上经常编不过，4.9–4.19 建议用 r450784e，5.10+ 用 r547379 或更新。构建脚本会校验解压结果里确实有 bin/clang，并对不在上表中的组合发出警告。

也可以用第三方 clang：USE_CUSTOM_CLANG=true + CUSTOM_CLANG_SOURCE（支持 git 仓库或 zip/tar 直链）。

完整配置项

见 config.env，每一项都有注释。几个常用的：

选项	说明
KERNEL_IMAGE_NAME	需要刷写的内核二进制名，与设备树里的 BOARD_KERNEL_IMAGE_NAME 一致，常见 Image.gz-dtb / Image.gz / Image
EXTRA_CMDS / CUSTOM_CMDS	追加到每次 make 的参数，值里可以带 =
USE_LLVM	全 LLVM 构建（LLVM=1 LLVM_IAS=1），适合 5.10+
ADD_OVERLAYFS_CONFIG	为 KernelSU 模块与 system 读写提供支持
DISABLE_LTO	LTO 会优化内核，但有时会导致编译错误
DISABLE_CC_WERROR	修复某些内核把 KernelSU 的告警当错误的问题
EXTRA_DEFCONFIG	任意追加 defconfig 行，如 CONFIG_TMPFS_XATTR=y
BUILD_BOOT_IMG + SOURCE_BOOT_IMAGE	重新打包 boot.img，需要提供同设备同 ROM 的可开机镜像直链
KSU_EXPECTED_SIZE / KSU_EXPECTED_HASH	自定义管理器签名，用 ksud debug get-sign <apk> 获取

兼容旧配置

旧版 config.env 无需修改即可继续使用，以下键会自动转换并给出提示：

旧键	新键
ENABLE_KERNELSU=true	KSU_VARIANT=kernelsu
KERNELSU_TAG	KSU_REF
APPLY_KSU_PATCH=true	KSU_HOOK_MODE=manual
DISABLE-LTO	DISABLE_LTO

仓库结构

.github/workflows/
  build-kernel.yml   构建入口（workflow_dispatch + workflow_call）
  ci.yml             shellcheck / actionlint / 配置校验 / 上游链接探活
scripts/
  lib.sh             日志、重试、Kconfig 读写、补丁、引用校验等公共函数
  config.sh          配置解析、输入覆盖、校验
  toolchain.sh       clang / gcc / mkbootimg
  source.sh          拉取内核源码
  kernelsu.sh        KernelSU 分支注册表与安装
  patches.sh         SUSFS / path_umount / hide_stuff / hooks / KPM
  build.sh           defconfig 注入与编译
  package.sh         AnyKernel3 / boot.img
patches/
  legacy_ksu_hooks.sh  旧版 sed hook 脚本（manual 模式的兜底）

build-kernel.yml 也可以被 workflow_call 复用，方便你为每台设备写一个极短的工作流。

排错

现象	原因
clang: not found / 工具链目录是空的	CLANG_BRANCH 与 CLANG_VERSION 组合无效，见上表
ref '...' does not exist	KSU_REF 填了不存在的分支，日志会列出可用分支
SUSFS 内核补丁打不上	SUSFS_BRANCH 与内核版本不匹配，或该树已被改动过
KernelSU 装上了但 su 无反应	旧内核的 kprobes 不可靠，改 KSU_HOOK_MODE=manual
模块挂载卸载不掉	5.9 以下内核需要 ENABLE_PATH_UMOUNT=true
找不到 defconfig	KERNEL_CONFIG 写错，日志会列出可用的 defconfig

感谢

• AnyKernel3
• AOSP
• KernelSU
• KernelSU-Next
• SukiSU-Ultra
• ReSukiSU
• susfs4ksu
• SukiSU_patch
• xiaoxindada