1508 字
8 分钟
让 Raspberry Pi Imager 对本地官方镜像重新启用 Customisation 自定义配置

距离上一次使用树莓派已经一年半多了,最近想要写一个脚本于是便找出来树莓派打算安装最新的系统

下载安装了新版本 Raspberry Pi Imager 发现 UI 已经大变样了

看起来比原来好看了一些,但是中文汉化仍然还是不完全的

按照烧录流程:选择设备型号 → 选择自定义镜像文件 → 选择SD卡 → 自定义配置 → 刷写镜像

但是这次却 没有弹出自定义配置的页面,各种重试也没有触发

搜了一堆资料也没有发现原因,只当是以为官方不再提供这个功能,需要烧录后自行配置

但是我在重新烧录中发现,Customisation 选项被自动跳过了

一开始没注意看界面左边的流程,现在一看这不就是自定义选项吗,但是为什么自动跳过了呢!!!

这不会和我选择了自定义镜像文件有关吧!!

经过多次测试发现 只有在烧录工具中下载的镜像文件才能配置Customisation

在官网下载的镜像文件是没办法配置 Customisation 选项的

一、不支持自定义配置的原因#

发现问题后我便打开了 Imager 的 GitHub 仓库,在仓库的根目录有一个 doc 文件夹

打开文件夹发现了一个名为 create_local_json.py 的脚本和它的 README.md 文件

读了一下便了解具体的原因,部分内容摘录

The latest version of Imager now supports several different methods of customising an Operating System disk image (OS image). To prevent things going awry when the wrong style of customisation is applied, Imager refuses to offer customisation options when it doesn't know what cusomisation method an image requires (the previous version of Imager would happily apply the "wrong" customisation method). When Imager starts up, it downloads a manifest file which tells it about all the online images available, as well as metadata about those images, including what customisation methods those images require. So when flashing an online image onto an SD card, Imager knows what OS customisation options to display.
However when selecting a locally downloaded image file in Imager (the Use custom option), this metadata isn't available, and so Imager won't offer any customisation options. The workaround for this is to create a JSON file for your local image file, containing the full path to your image file and any necessary metadata, and point Imager at this local JSON file. This process can be a bit cumbersome, so the create_local_json.py script has been created to make this a bit easier (for those OS images in Imager's current manifest file).
目的
最新版本的Imager现在支持多种不同的操作系统磁盘映像(OS映像)自定义方法。为了避免在应用错误的自定义风格时出现问题,当Imager不知道某个映像需要哪种自定义方法时,它会拒绝提供自定义选项(而Imager的上一版本则会欣然采用“错误的”自定义方法)。Imager启动时,会下载一个清单文件,该文件会告知它所有可用的在线映像,以及这些映像的元数据,包括它们所需的自定义方法。因此,当将在线映像烧录到SD卡上时,Imager会知道要显示哪些操作系统自定义选项。
然而,在Imager中选择本地下载的镜像文件(使用自定义选项)时,此元数据不可用,因此Imager不会提供任何自定义选项。解决此问题的方法是为本地镜像文件创建一个JSON文件,其中包含镜像文件的完整路径和任何必要的元数据,并将Imager指向此本地JSON文件。此过程可能有些繁琐,因此创建了create_local_json.py脚本,以使此过程变得更容易(针对Imager当前清单文件中的操作系统镜像)。

简单地说 Raspberry Pi Imager 需要相应的元数据才能对本地镜像文件执行 Customisation
create_local_json.py就是用于为本地镜像生成元数据的脚本
该脚本会拉取官方提供的镜像清单文件 os_list_imagingutility_v4.json 并在本地目录中匹配同名镜像文件
匹配成功后,脚本会记录文件信息,并生成包含本地镜像元数据的配置文件
因此需要保证镜像文件的名称是与官方保持一致未经过修改的
在 Raspberry Pi Imager 中加载此配置文件后,即可对本地镜像提供完整的自定义配置支持

二、生成元数据文件#

访问仓库 https://github.com/raspberrypi/rpi-imager/tree/main/doc/local_json 下载脚本文件

create_local_json.py 放入本地镜像文件所在目录,然后运行该脚本

脚本会扫描当前目录及其子目录下所有符合条件的镜像文件

Terminal window
python3 create_local_json.py
NOTE

此时脚本会自动下载 os_list_imagingutility_v4.jsoncache 文件夹中

cache目录已有该 JSON 文件,则优先使用本地版本(不会重新下载)

如果脚本运行于非本地镜像文件目录,可以用 --search-dir 可指定本地镜像文件目录位置

如果移动了镜像文件位置则需要重新生成元数据文件

运行完成将会生成 os_list_local.rpi-imager-manifest 文件
其包括所有在线镜像文件以及本地镜像文件的元数据

点击 App Options → Content Repository → Use custom file 选择创建的 os_list_local.rpi-imager-manifest 即可加载含有本地镜像文件信息的配置文件

三、进行自定义配置#

加载新的配置文件并完成重启后,即可正常操作本地镜像文件,Customisation 也将不再被跳过

Customisation 可以自定义以下配置:

  • Hostname:主机名
  • Localisation:时区、键盘布局、语言、Wi-Fi 国家
  • User:创建初始用户及密码
  • Wi-Fi:无线网络配置
  • Remote access:启用 SSH(密码或密钥方式)

这些配置都可以在刷写镜像文件以后进行单独配置,但是在刷写过程中进行配置可以节省很多繁琐的操作

完成配置并刷写镜像后启动树莓派即可,等待系统自动完成配置即可开始使用

让 Raspberry Pi Imager 对本地官方镜像重新启用 Customisation 自定义配置
https://www.self4m.com/posts/raspberry-pi-imager-local-image-customisations/
✍️作者
Self4m
📅发布于
2026-01-08
©️许可协议
CC BY-NC-SA 4.0

商业用途必须事先获得作者授权;
非商业用途可以使用,但必须注明出处;
若有改编需采用相同许可协议发布。