本系列所有文章

你可以通过使用右下角的小齿轮，来开启黑夜模式和阅读模式。

如果你发现文章内容有错漏、你对文章内容有任何改进意见或者你阅读文章遇到了困难，都可以通过博客首页的邮箱联系我。

LineageOS GSI 构建指南（优化版）

📋 环境要求

操作系统: Debian 12（建议纯净安装）
CPU: 建议内核数至少8核心。
内存: 建议至少16GB RAM，并配置16GB以上swap空间
存储: 建议至少350GB+可用空间（SSD更佳）
网络: 稳定连接，建议使用代理或国内镜像加速

一、环境配置

1.1 更新系统并安装依赖

# 更新系统
sudo apt update && sudo apt upgrade -y

# 安装编译依赖包（适配Debian 12）
sudo apt install -y \
  bc bison build-essential ccache curl flex g++-multilib gcc-multilib \
  git git-lfs gnupg gperf imagemagick lib32ncurses-dev lib32z1-dev \
  liblz4-tool libncurses5-dev libsdl1.2-dev libssl-dev libwxgtk3.2-dev \
  libxml2 libxml2-utils lzop maven pngcrush python3 python-is-python3 \
  rsync schedtool squashfs-tools tmux unzip wget zip zlib1g-dev \
  openjdk-17-jdk android-sdk-platform-tools-common protobuf-compiler \
  python3-protobuf lib32readline-dev libdw-dev libelf-dev lz4 \
  xsltproc libncurses5 libtinfo5 p7zip-full

1.2 配置Git

# 请替换为你的实际信息
git config --global user.email "your-email@example.com"
git config --global user.name "Your Name"
git lfs install
git config --global trailer.changeid.key "Change-Id"

1.3 创建目录结构

mkdir -p ~/bin
mkdir -p ~/lineageos

1.4 安装和配置Repo工具

# 下载repo工具
curl https://storage.googleapis.com/git-repo-downloads/repo > ~/bin/repo
chmod a+x ~/bin/repo

# 添加到PATH
echo 'export PATH="$HOME/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

二、使用Tmux管理会话（推荐）

2.1 Tmux基本操作

# 创建新会话（建议在开始编译前执行）
tmux new -s lineage_build

# 分离会话（保持后台运行）：
Ctrl+b, 然后按 d

# 重新连接会话
tmux attach -t lineage_build

# 列出所有会话
tmux ls

# 结束会话（在会话内部）
exit
# 或从外部结束
tmux kill-session -t lineage_build

三、获取源代码

3.1 初始化仓库

cd ~/lineageos

*可选参数 --no-clone-bundle*
# LineageOS 23.0
repo init -u https://github.com/LineageOS/android.git -b lineage-23.0 --git-lfs

# LineageOS 21.0
repo init -u https://github.com/LineageOS/android.git -b lineage-21.0 --git-lfs --no-clone-bundle

# 如果需要LineageOS 22.2，使用：
# repo init -u https://github.com/LineageOS/android.git -b lineage-22.2 --git-lfs

3.2 添加GSI专用Manifest，不同的分支请自行替换为对应的los版本manifest分支

git clone https://github.com/MisterZtr/treble_manifest.git .repo/local_manifests -b lineage-23.0

3.3 同步aosp代码

# 建议使用较少线程
repo sync --force-sync --optimized-fetch --no-tags --no-clone-bundle --prune -j4

# 同步失败时可尝试清理后重试
# repo forall -c 'git reset --hard' && repo sync --force-sync

3.4 应用补丁

bash LineageOS_gsi/patches/apply-patches.sh .

四、配置编译环境

4.1 设置ccache缓存

# 编辑bash配置文件
vim ~/.bashrc

# 这是在 ~/.bashrc 文件末尾添加的内容：
export USE_CCACHE=1
export CCACHE_COMPRESS=1

# 设置缓存大小（建议50G以上），这是在命令行运行的指令
ccache -M 50G
ccache -o compression=true

# 使配置生效
source ~/.bashrc

# 验证ccache配置
ccache -s

五、开始编译

5.1 初始化编译环境

cd ~/lineageos
source build/envsetup.sh

# 确认缓存设置
ccache -M 50G -F 0

5.2 编译选项说明

目标命名规则解释：
- bvNE: VANILLA版（无GApps）+ erofs文件系统
- bvN4: VANILLA版（无GApps）+ ext4文件系统  
- bgNE: GAPPS版（包含GApps）+ erofs文件系统
- bgN4: GAPPS版（包含GApps）+ ext4文件系统

5.3 编译命令

- 推荐erofs文件系统版本【但是erofs文件系统要求启动内核5.4+及相应的fstab条目】

# VANILLA版本（erofs文件系统） 
breakfast lineage_arm64_bvNE-bp2a-userdebug
make systemimage -j$(nproc --all)

# VANILLA版本（ext4文件系统）
breakfast lineage_arm64_bvN4-bp2a-userdebug
make systemimage -j$(nproc --all)

# GAPPS版本（erofs文件系统）
breakfast lineage_arm64_bgNE-bp2a-userdebug
make systemimage -j$(nproc --all)

# GAPPS版本（ext4文件系统）
breakfast lineage_arm64_bgN4-bp2a-userdebug
make systemimage -j$(nproc --all)

5.4 编译过程监控

# 查看ccache命中率
watch -n 5 ccache -s

# 查看系统资源使用
htop

六、编译后处理

6.1 定位生成的镜像文件

# 通常路径为（根据实际编译目标可能不同）
cd out/target/product/tdgsi_arm64_ab

# 验证文件存在
ls -lh system.img

# 检查镜像信息
file system.img

6.2 压缩镜像（可选）

# 使用7z压缩
7z a  system.img.xz system.img

# 验证压缩文件完整性
7z t system.img.xz

七、常见问题与解决方法

7.1 同步失败

# 方案1：重试同步
repo sync --force-sync -j2

# 方案2：清理并重新同步
rm -rf .repo/project-objects
repo sync --force-sync --no-clone-bundle -j2

7.2 编译失败

# 1. 清理编译环境
make clean
# 或
mka clean

# 2. 检查错误日志
cat out/error.log | tail -100

# 3. 重新开始编译
source build/envsetup.sh
breakfast [你的目标]
make systemimage -j4  # 先用较少线程测试

7.3 内存不足

# 创建交换文件，这里的范例创建了24G的交换文件（如果内存不足）
sudo dd if=/dev/zero of=/mnt/swap bs=1M count=24576
sudo mkswap /mnt/swap
sudo chmod 0600 /mnt/swap
sudo swapon /mnt/swap

# 永久添加（重启后生效）
echo '/mnt/swap none swap sw 0 0' | sudo tee -a /etc/fstab

# 卸载和删除swap
卸载swap文件： sudo swapoff /mnt/swap
删除swap文件：  rm -rf /mnt/swap

7.4 磁盘空间不足

# 清理ccache缓存
ccache -C

# 清理编译中间文件
make clean

# 查看磁盘使用
df -h
du -sh ~/lineageos/

7.5 应用补丁失败

请尝试手动应用补丁。

八、高级技巧

8.1 使用国内镜像加速，请参考修改指南（可选）

8.2 增量编译

# 修改代码后重新编译
make systemimage -j$(nproc --all)

8.3 编译时间预估

首次编译：4-8小时（取决于硬件）
后续编译：30分钟-2小时（使用ccache）

📝 使用建议

要想使用erofs系统，要求系统启动内核5.4+及相应的fstab条目
编译和同步源码过程中建议保持网络稳定，避免中断
记得定期同步aosp源码，
记录编译日志便于问题排查
如果发现本文内容有严重的事实错误或内容上的错漏、过时，可以通过博客首页的邮箱联系我取得帮助或让我及时修改文章内容。