树莓派镜像写入工具，如何发现和列出操作系统镜像？

您是图像供应商还是希望通过树莓派镜像写入工具发布自定义树莓派操作系统镜像的爱好者？如果是，那么本指南是适合您的。在本文中，我们将深入、技术性地探讨树莓派镜像写入工具如何发现和列出操作系统镜像，以及存储库JSON格式的内部工作原理。

随着树莓派镜像写入工具2.0版本的发布，用户界面、镜像写入流程和内部配置处理方面均进行了多项改进（更多详细信息，请参阅树莓派镜像写入工具2.0发布公告）。https://www.raspberrypi.com/software/

其中一个较为有趣的变化是，用于定义可用操作系统镜像的JSON架构更新了。此次更新与树莓派操作系统引入云初始化（cloud-init）支持尤为相关，其中包括一个全新的cc_raspberry_pi模块，该模块支持自动启用SPI等配置功能。

树莓派镜像写入工具如何识别镜像

树莓派镜像写入工具和树莓派操作系统的发布周期并不相同。操作系统在发布新版本的镜像写入工具之前可能会收到多次更新。为每个操作系统更新发布新的镜像写入工具版本效率低下，也会给用户带来不便。

为解决这一问题，树莓派镜像写入工具不会附带固定的操作系统镜像列表。相反，它会从远程JSON文件（称为“存储库JSON”）动态获取此信息。这使我们能够与镜像写入工具的发布分开更新受支持的设备列表和可用操作系统镜像列表。用户无需重新安装或更新应用程序即可自动获取最新选项。

当前版本（镜像写入工具2.0及更高版本使用）的格式正式编码为存储库JSON V4。

https://github.com/raspberrypi/rpi-imager/blob/main/doc/schema-notes.md

为什么要将存储库分开？

外部托管镜像元数据提供了一些强大的可能性。例如，您可以维护多个存储库，一个用于官方稳定版本，另一个用于每日构建或测试镜像，甚至可以为内部部署或课堂环境维护一个私有存储库。

为使这一功能更易于使用，镜像写入工具2.0在应用设置中引入了一个新选项，允许您在官方存储库和自定义JSON文件之间切换，自定义JSON文件可以从本地文件或URL加载。

更改此设置后，镜像写入工具将重置当前会话，并使用所选存储库JSON的内容重新加载界面。此功能面向高级用户和维护者，普通用户通常无需更改此设置。

对于高级用户或自动化场景，经典方法仍然可用：您可以使用--repo命令行选项传递自定义存储库。此选项可以指向URL或本地JSON文件，非常适合脚本化工作流程或配置设置。

了解存储库JSON结构

树莓派镜像写入工具存储库文件遵循可预测的结构，并围绕四个主要配置元素构建：

最新镜像写入工具版本

用户可下载更新的URL

受支持的设备配置文件列表

可用操作系统条目列表

以下是基本结构：

{  "imager": {    "latest_version": "2.0.0",    "url": "https://www.raspberrypi.com/software/",    "devices": [      /* Device objects go here */    ]  },  "os_list": [    /* OS objects go here */  ]}

imager.latest_version和url

镜像写入工具使用latest_version字段来确定是否有更新的版本可用。当用户启动应用程序时，它会将自己的版本与此字段进行比较。如果存储库指示有更新的版本，镜像写入工具将显示更新提示，并链接到url字段中提供的URL。

devices列表

devices数组包含受支持的硬件配置文件列表。这些配置文件允许镜像写入工具根据所选的树莓派型号过滤操作系统条目。例如，某个镜像可能仅限于树莓派5使用，或标记为与所有板卡兼容。

您还会看到一个名为“无过滤”的特殊条目。选择此选项时，将显示所有操作系统镜像，而不应用任何设备兼容性过滤器。此模式通常用于测试或使用通用镜像时。它就像一个支持所有功能的虚拟设备配置文件。这意味着即使未选择特定的树莓派型号，所有配置选项也均可用。

os_list

这是实际发挥作用的地方。os_list包含镜像写入工具向用户显示的所有操作系统条目。每个条目可以代表一个完整的操作系统、一个包含多个变体的子组，甚至可以引用嵌套的JSON文件以构建模块化存储库。

如果您正在构建自己的自定义存储库，这通常是您唯一需要编辑的部分。顶级imager块（包括设备元数据和更新信息）由树莓派管理，并与官方应用程序的工作方式紧密集成。

JSON设备对象——定义硬件配置文件

在树莓派镜像写入工具决定为哪个设备显示哪些操作系统之前，它需要一种方法来了解每个树莓派型号的身份和功能。这就是设备对象的作用。

devices数组中的每个条目代表一个设备配置文件，不一定是单个板卡，而通常是兼容型号的组。例如，可能只有一个配置文件代表“树莓派4/400”，而不是为每个板卡变体分别设置条目。

以下是设备对象可以包含的内容：

name

string：镜像写入工具中显示的名称（例如“树莓派5”）

tags

string[]：操作系统对象可以引用的一组标识符，用于声明兼容性

default

boolean (默认值: true)：只有一个设备应设置此值；当未应用手动过滤器时，镜像写入工具将自动选择它

icon

string (URL)：设备选择对话框中名称旁边显示的小PNG图标

description

string：列出支持型号或提供额外上下文的可选文本

matching_type

"inclusive" | "exclusive"：定义未声明设备标签的操作系统条目应如何表现：

• inclusive →无论如何都显示它们

• exclusive →隐藏它们，除非明确为此设备标记

capabilities (镜像写入工具2.0中的新增功能)

string[] (e.g. “usb_otg“)：作为功能标志——用于根据所选设备是否支持来隐藏或启用用户界面选项

设备功能特别有用，因为它们允许镜像写入工具仅显示有意义的配置选项。例如，仅当所选设备和所选操作系统在其功能中均列出usb_otg时，才会显示USB外设模式切换开关。这避免了向用户显示在其硬件上无法工作的选项，从而避免用户困惑。

os_list中的对象：类别与操作系统

os_list部分可以包含两种不同类型的对象，每种对象服务于不同的目的：

1.类别对象

类别是一个容器，用于组织多个操作系统条目甚至子类别。它不能被选择下载，也不包含url或镜像元数据。

类别对象仅支持以下键：

name

string：用户界面中显示的类别标题

description

string：名称下方显示的可选文本

icon

string (URL)：类别名称旁边显示的图标

random

boolean (optional)：如果为true，则随机排列subitems中条目的顺序

subitems

array：包含操作系统对象和/或嵌套类别对象

将类别视为用户界面中的一个文件夹——您点击它以显示其中的内容。

2.操作系统对象

操作系统对象定义了一个可选择的镜像。这些是可安装的条目。它们不包含random或subitems。

操作系统条目支持的键如下：

name

string：Display name of the OS操作系统的显示名称

description

string：简短说明或变体信息

icon

string (URL)：条目旁边显示的图标

url

string (URL)：压缩镜像文件的直接链接（.img.xz、.img.zip等）

extract_size

int：未压缩镜像的大小（用于用户界面空间估算）

extract_sha256

string：提取后的镜像的SHA256哈希值

image_download_size

int：压缩下载的大小

image_download_sha256

string：压缩文件的SHA256哈希值

release_date

string (date)：用于版本/构建标识的显示日期

init_format

"none" | "systemd" | "cloudinit" | "cloudinit-rpi"：Declares 声明镜像写入工具可以提供何种类型的自定义设置；cloudinit-rpi启用树莓派特定的；cc_raspberry_pi模块

devices

string[]：此操作系统支持的设备标签（来自设备对象）列表A list of device tags (from device objects) that this OS supports

capabilities

string[]：指示此操作系统镜像支持的功能（例如usb_otg或rpi_connect）

提示：对于开发或内部测试，您可以省略校验和和大小字段。然而，对于公共存储库，提供这些信息有助于镜像写入工具提供准确的进度信息，并允许进行校验和验证。

经验法则：

如果它包含其他项 → 它是类别对象

如果它下载某些内容 → 它是操作系统对象

功能——功能匹配

以下是适用于设备和操作系统对象的功能的更清晰解释：

usb_otg

设备和操作系统：仅当所选设备和操作系统均支持USB外设功能时显示（要求操作系统中包含rpi-usb-gadget且硬件支持OTG）

rpi_connect

仅操作系统镜像：指示在用户界面中支持树莓派连接功能

镜像要求

如果您希望镜像在树莓派镜像写入工具中提供自定义选项，特别是使用新的云初始化集成时，您的镜像必须满足一些技术要求。

支持云初始化自定义设置

要启用基于云初始化的配置（如在首次启动时设置主机名、Wi-Fi凭据或SSH密钥），您的镜像必须：

支持云初始化的网络配置版本2——通常通过Netplan实现，并使用正确的网络渲染器

包含云初始化，并通过bootfs分区支持NoCloud数据源（镜像写入工具将配置文件写入bootfs，操作系统必须在首次启动时检测到它们）

cloudinit-rpi——高级树莓派集成

如果您在操作系统条目中声明init_format: "cloudinit-rpi"，镜像写入工具还将暴露树莓派特定的选项，例如自动启用SPI或I2C。要支持此模式，您的镜像必须：

启用cc_raspberry_pi云初始化模块

包含raspi-config-vendor软件包（针对您的发行版进行了修改），该软件包在首次启动时为云初始化模块提供集成钩子

更多详细信息，包括模板设置，请参见此处。

https://github.com/raspberrypi/raspi-config-vendor-template

其他初始化模式

init_format 值：镜像写入工具行为

"none"：不向用户提供自定义选项——简单的下载和写入工作流程

"systemd"：启用基于bootfs的遗留firstrun.sh自定义机制

"cloud-init"：启用标准云初始化（NoCloud）和通用选项

"cloud-init-rpi"：通过cc_raspberry_pi启用扩展的、树莓派特定的选项

如果您的镜像不支持任何自定义机制，请使用init_format: "none"以在用户界面中显式禁用自定义步骤。

官方网站：https://edatec.cn/zh/cm0

淘宝店铺：https://edatec.taobao.com/