企业官网建设流程全解析

pi-gen 是树莓派官方用于批量构建 Raspberry Pi OS（Raspbian）系统镜像的自动化工具。它用一个build.sh主脚本按"阶段（stage）"流水线方式拼装系统：每完成一个阶段，就产出一份可用的 rootfs，最终打包成 SD 卡镜像。对新手来说，理解它的编排机制，是定制自己专属 Pi 系统镜像的第一步。

本文带你看懂三件事：

• build.sh如何按顺序驱动各阶段；
• prerun.sh在阶段之间干了什么；
• 子目录里的 5 类控制文件（debconf、packages、packages-nr、patches、run 脚本）分别如何被执行。

一条流水线：build.sh 的主循环

整个构建流程可以从 build.sh 的run_stage/run_sub_stage两个函数概括为：

1. 读取配置：执行时 source 当前目录下的config文件（也可以用-c myconfig指定），核心变量是必填的IMG_NAME，以及WORK_DIR、DEPLOY_DIR等；
2. 按字母序遍历stage*目录：默认是stage0 → stage1 → stage2 → stage3 → stage4 → stage5，也可以用STAGE_LIST自定义顺序甚至插入自己的阶段目录；
3. 跳过控制：如果某阶段目录里存在SKIP文件，整个阶段被跳过；存在SKIP_IMAGES则不产出镜像；
4. 执行prerun.sh（如果存在且可执行）：负责准备本阶段的 rootfs；
5. 按字母序执行每个子目录中的控制文件（详见下文），子目录名必须是两位数字开头（如01-sys-tweaks），子目录内的SKIP文件可单独跳过它；
6. 导出镜像：阶段目录里含EXPORT_IMAGE文件的，构建结束后会依次运行 export-image/ 流水线生成.img镜像；含EXPORT_NOOBS的还会额外跑 export-noobs/ 生成 NOOBS 安装包。

每个阶段的官方定位（来自 README.md 的 "Stage Anatomy"）：

下面这张图就是 stage4 桌面镜像内置的 Raspbian 桌面首次启动时的欢迎幻灯片之一，由export-noobs阶段的营销素材打包而来：

prerun.sh：阶段之间的"接力棒"

prerun.sh是每个阶段目录下的可选脚本，在子目录执行之前运行，典型作用是"把上一阶段成果搬进本阶段"。它只有两种常见写法：

• 引导阶段（stage0）：rootfs 还不存在时用bootstrap创建，例如 stage0/prerun.sh 调用 debootstrap 拉出 stretch 最小系统；
• 后续阶段（stage1 及以后）：rootfs 不存在时调用copy_previous，用 rsync 把上一阶段的 rootfs 完整复制到${ROOTFS_DIR}，例如 stage3/prerun.sh。

bootstrap与copy_previous这些公共函数都定义在 scripts/common 中，build.sh启动时会将其 source 进来。copy_previous会排除 apt 缓存目录以节省空间，同时保留了硬链接（-aHAXx参数），使各阶段共享未修改的文件，这也是 pi-gen 能在有限磁盘上构建几十 GB 阶段副本的关键。

配合SKIP机制，官方推荐的开发流程是：只改最后一个阶段，用CLEAN=1 ./build.sh单阶段重建，避免从头跑完整条流水线。

5类控制文件：子目录里的执行规则

build.sh对每个子目录会循环00到99，逐位数字检查下列 5 类控制文件并执行（同一编号内按此顺序：debconf → packages-nr → packages → patches → run 脚本）：

1.NN-debconf— 预配置 debconf

文件内容直接管道给 chroot 内的debconf-set-selections，用于静默预置区域、键盘布局等交互选项。实例：stage1/01-locale/00-debconf。

2.NN-packages— 常规安装包

空格分隔的包名列表（支持#注释），在 chroot 内执行apt-get install -y。实例：stage2/01-sys-tweaks/00-packages，其中包含sudo、raspberrypi-sys-mods等基础组件。

3.NN-packages-nr— 精简安装包

与NN-packages相同，但使用apt-get install --no-install-recommends -y，只装必需依赖、不装推荐包，用来控制镜像体积。

4.NN-patches/— quilt 补丁目录

目录内放.diff补丁和series清单，构建时用 quilt 依次push到 rootfs 上修改文件；如果目录里额外放了EDIT文件，构建会中断进入交互式 bash 会话，方便你现场创建/修订补丁。实例：stage2/01-sys-tweaks/00-patches/series 中排布着01-useradd.diff、02-swap.diff等系统调优补丁。

5.NN-run.sh/NN-run-chroot.sh— 自定义脚本

• NN-run.sh：在宿主机侧执行的 shell 脚本，必须赋予可执行权限（-x检查），典型用途是把files/下的配置安装进 rootfs，例如 stage2/02-net-tweaks/01-run.sh 写入 WiFi 配置并响应WPA_ESSID等环境变量；
• NN-run-chroot.sh：内容直接作为 chroot 内的 shell 执行，不需要可执行权限，适合在目标系统内部跑命令，例如 stage2.5/01-susi/01-run-chroot.sh。

chroot 环境由 scripts/common 里的on_chroot函数负责搭建：临时挂载 proc/dev/sys 后以capsh降权进入。

导出阶段：EXPORT_IMAGE 与 EXPORT_NOOBS

阶段标记文件本身只是一小段 shell 片段（被build.shsource 进来），用来设置镜像后缀等元信息。例如 stage2/EXPORT_IMAGE 设置IMG_SUFFIX="-lite"，stage2/EXPORT_NOOBS 则声明 NOOBS 包名称为 "Raspbian Lite"。

真正干活的是导出版本目录：

• export-image/prerun.sh：计算 boot/rootfs 大小 →truncate出镜像文件 →fdisk划分两个分区 → 挂载后把 rootfs 写进去；
• export-image/01-set-sources/ 用 quilt 补丁替换镜像内的 apt 源，04-finalise/做收尾；
• export-noobs/00-release/00-run.sh：把 rootfs 压成boot.tar.xz/root.tar.xz，填入partitions.json的分区大小，生成 NOOBS 可识别的 OS 包。

下面这张 NOOBS "Welcome to Raspberry Pi" 安装等待画面，正是export-noobs打包进镜像的启动幻灯片：

快速上手：从 config 到 deploy 四步走

1. 安装依赖：depends文件列出了所有工具，例如apt-get install coreutils quilt parted qemu-user-static debootstrap ...（完整列表见 depends）；
2. 创建配置：echo "IMG_NAME='MyPi'" > config；
3. 构建：sudo ./build.sh（或用 build-docker.sh 在容器里构建）；
4. 取镜像：成果输出到deploy/目录，可直接刷入 SD 卡。

常用调试技巧：某步失败后编辑对应脚本，再用CONTINUE=1（docker 构建）或CLEAN=1 ./build.sh从断点阶段重建，不必推倒重来。

小结

pi-gen 的设计精髓在于"目录即代码、文件即指令"：build.sh只负责按字母序执行，所有构建逻辑都沉淀在stage*/prerun.sh和子目录的 5 类控制文件中。想定制镜像时，你只需新增一个两位数字开头的子目录、放入对应的00-packages或01-run.sh，流水线就会自动把它编排进构建流程——这正是它被社区二次开发（如本仓库的 stage2.4/stage2.5 SUSI 阶段）所喜爱的原因。