amlogic-s9xxx-armbian编译教程：在Ubuntu 22.04环境下构建自定义系统镜像
项目地址: https://gitcode.com/GitHub_Trending/am/amlogic-s9xxx-armbian 前言：为什么需要自定义编译？
你是否曾遇到官方镜像驱动缺失、内核版本过旧，或需要为Amlogic S905X3/S922X等设备添加专属功能的情况？本文将带你在Ubuntu 22.04环境下，通过12个步骤完成从环境搭建到镜像生成的全流程，最终得到可直接刷写的Armbian系统镜像。读完本文你将掌握：内核定制编译、驱动模块集成、设备树优化、镜像打包全流程，解决90%以上的编译报错问题。
一、环境准备：构建编译工作站
1.1 系统要求
- 硬件：x86_64架构CPU（4核8线程以上）、16GB内存、200GB SSD（编译过程需大量临时空间）
- 系统：Ubuntu 22.04 LTS（必须64位，建议全新安装以避免依赖冲突）
- 网络：稳定网络环境（需拉取GitHub源码及外部资源）
1.2 基础依赖安装
# 更新系统并安装基础工具
sudo apt update && sudo apt upgrade -y
sudo apt install -y $(cat compile-kernel/tools/script/ubuntu2204-build-armbian-depends)
# 验证关键依赖版本
gcc --version | grep "11.4.0" || echo "GCC版本需≥11.4.0"
docker --version || echo "建议安装Docker以加速编译环境配置"
依赖列表解析（关键包说明）：
binutils-aarch64-linux-gnu：ARM64交叉编译工具链device-tree-compiler：设备树编译工具（Amlogic设备必须）llvm lld：Clang/LLVM编译套件（可选，用于LTO优化）qemu-user-static：ARM64模拟器（用于生成initrd镜像）
二、源码获取与项目结构解析
2.1 克隆项目仓库
git clone https://gitcode.com/GitHub_Trending/am/amlogic-s9xxx-armbian
cd amlogic-s9xxx-armbian
2.2 核心目录功能说明
amlogic-s9xxx-armbian/
├── compile-kernel/ # 内核编译核心目录
│ ├── tools/config/ # 预定义内核配置模板（支持5.4~6.12版本）
│ ├── tools/patch/ # 设备专属补丁（Amlogic/Rockchip/Allwinner）
│ └── tools/script/ # 自动化编译脚本
├── rebuild # 系统镜像重建脚本
└── recompile # 内核重编译入口脚本
⚠️ 注意：项目默认使用unifreq维护的内核源码（https://github.com/unifreq/linux-5.15.y），已针对Amlogic设备优化，不建议替换为上游主线内核。
三、编译参数配置：定制你的系统
3.1 核心编译参数速查表
| 参数 | 含义 | 示例 | 适用场景 |
|---|---|---|---|
-k | 内核版本 | -k 5.15.100_6.1.50 | 指定单个/多个版本 |
-a | 自动升级内核 | -a true | 编译同系列最新版本 |
-m | 编译目标 | -m dtbs | 仅编译设备树文件 |
-n | 内核签名 | -n -mycustom | 生成个性化内核名称 |
-p | 应用补丁 | -p true | 启用tools/patch目录下的补丁 |
3.2 常用编译命令模板
# 基础编译：默认参数构建5.15.y内核
sudo ./recompile -k 5.15.y -a true
# 高级编译：多版本+自定义签名+补丁
sudo ./recompile -k 5.15.100_6.1.10 -n -ophub -p true -s false
# 仅更新设备树：适用于硬件外设调整
sudo ./recompile -k 6.1.y -m dtbs -d true
💡 技巧：使用
-s false关闭静默模式可查看完整编译日志，便于定位错误；-d true在编译完成后删除源码，节省磁盘空间。
四、内核编译全流程解析
4.1 编译流程图解
4.2 关键步骤详解
4.2.1 内核配置自定义（可选）
# 基于现有配置模板修改
cd compile-kernel/kernel/linux-5.15.y
make menuconfig ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu-
推荐配置项：
- 启用
CONFIG_USB_NET_DRIVER（USB网卡支持）- 启用
CONFIG_BTRFS_FS（Btrfs文件系统支持）- 禁用
CONFIG_DEBUG_INFO（减少镜像体积）
4.2.2 执行编译过程
# 返回项目根目录执行编译
cd ../../../../
sudo ./recompile -k 5.15.y -a true -n -mykernel
编译过程监控：
- 内存占用峰值约8~12GB（建议关闭其他应用）
- 耗时：单版本约40分钟（8核CPU），多版本按比例增加
- 中间产物位于
compile-kernel/kernel/，最终镜像在compile-kernel/output/
五、系统镜像打包与优化
5.1 生成完整系统镜像
# 使用rebuild脚本整合内核与根文件系统
sudo ./rebuild -b s905x3 -k 5.15.100-mykernel -t ext4
参数说明：
-b：指定设备型号（s905x3/s922x/a311d等，完整列表见model_database.conf）-t：根文件系统类型（ext4/btrfs，推荐ext4兼容性更好）
5.2 镜像优化技巧
- 减小体积：删除
/usr/share/doc和/usr/share/man目录 - 预安装软件：修改
armbian-files/common-files/添加自定义包 - 设置默认密码：调整
armbian-files/common-files/etc/passwd
六、常见问题解决（FAQ）
6.1 编译失败错误码速查
| 错误信息 | 原因分析 | 解决方案 |
|---|---|---|
No rule to make target 'Image' | 源码未同步或Makefile损坏 | rm -rf compile-kernel/kernel && ./recompile |
cc1: error: invalid option '-march=armv8.2-a' | GCC版本过低 | 升级gcc至11+：sudo apt install gcc-11-aarch64-linux-gnu |
dtb-amlogic-*.tar.gz not found | 设备树编译失败 | 检查tools/patch目录是否有对应设备补丁 |
6.2 编译后无法启动排查流程
- 检查设备树匹配：确认
-b参数与设备型号一致（如s905x3需对应 meson-sm1-s905x3.dtb） - 内核版本兼容性：5.4.y支持旧设备，6.12.y仅支持新机型（如Amlogic S922X）
- 串口调试：通过UART查看启动日志，重点关注
Kernel panic和dtb parse error
七、成果验证与部署
7.1 编译输出文件说明
compile-kernel/output/
├── 5.15.100-mykernel/ # 按内核版本分类的输出目录
│ ├── boot-*.tar.gz # 内核镜像与启动脚本
│ ├── dtb-amlogic-*.tar.gz # Amlogic设备树文件
│ ├── modules-*.tar.gz # 内核模块
│ └── sha256sums # 文件校验和
└── Armbian_*.img # 完整系统镜像（由rebuild生成）
7.2 写入SD卡/EMMC
# 使用dd命令写入SD卡（替换/dev/sdX为实际设备）
sudo dd if=Armbian_22.02.0_amlogic_s905x3_jammy_5.15.100-mykernel_server_2025.09.07.img \
of=/dev/sdX bs=4M status=progress
⚠️ 警告：错误指定设备会导致数据丢失！使用
lsblk确认目标设备，确保未挂载。
八、高级进阶：自动化与定制化
8.1 GitHub Actions自动编译
# .github/workflows/compile.yml示例
name: Compile Armbian
on: [push]
jobs:
build:
runs-on: ubuntu-22.04
steps:
- uses: actions/checkout@v4
- name: Compile kernel
run: |
sudo ./recompile -k 6.1.y -n -github -a true
- name: Upload artifact
uses: actions/upload-artifact@v3
with:
name: armbian-image
path: compile-kernel/output/*.img
8.2 集成自定义驱动
- 将驱动源码放入
compile-kernel/tools/patch/common-kernel-patches - 编写补丁文件（.patch），使用
git diff > mydriver.patch生成 - 编译时添加
-p true参数应用补丁
结语
通过本文教程，你已掌握在Ubuntu 22.04环境下构建amlogic-s9xxx-armbian自定义镜像的完整流程。从依赖配置到内核编译，再到问题排查，这套方法可帮助你为Amlogic设备打造专属的Armbian系统。建议定期同步项目源码以获取最新驱动支持，同时关注unifreq的内核更新日志（https://github.com/unifreq/linux-5.15.y/commits/main）。
下一步行动：
- 尝试为你的设备添加专属驱动模块
- 优化内核配置以提升性能或降低功耗
- 参与项目贡献：提交设备支持补丁至https://gitcode.com/GitHub_Trending/am/amlogic-s9xxx-armbian
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
