1. 项目概述为树莓派计算模块刷写系统镜像如果你手头有一块树莓派计算模块无论是用于工业控制、嵌入式网关还是定制化硬件产品第一步往往就是给它“装系统”。与普通的树莓派单板计算机不同计算模块没有SD卡槽它的“硬盘”是一颗焊接在板载的eMMC存储器。这意味着你不能像给树莓派4B那样直接把镜像烧录到SD卡里插上就用。这个过程我们称之为“刷写”或“烧录”。我经手过从初代Compute Module到最新的CM5也遇到过各种稀奇古怪的报错。这篇文章就是把我这些年给不同型号计算模块刷写系统镜像的完整流程、核心原理以及那些官方文档里没写的“坑”和技巧系统地梳理一遍。无论你是第一次接触计算模块的开发者还是需要批量部署的工程师这篇指南都能帮你绕过弯路高效、稳定地完成系统部署。2. 核心思路与硬件准备解析给计算模块刷写系统核心思路是让它暂时“忘记”自己的eMMC转而从一个临时的USB设备启动一个极简的引导程序。这个引导程序会扮演一个“USB大容量存储设备”的角色将计算模块的eMMC暴露给你的电脑此时你的电脑会把它识别为一个普通的U盘或移动硬盘。接下来你就可以像往U盘里拷贝文件一样使用标准的镜像烧录工具如dd或Raspberry Pi Imager将系统镜像写入eMMC。2.1 硬件清单与选型考量要完成这个操作你需要以下几样东西每一件的选择都有讲究计算模块本体这是你的目标设备。需要特别注意计算模块有标准版和Lite版之分。标准版内置eMMC是我们本次操作的对象。Lite版没有eMMC需要通过SD卡或NVMe接口启动刷写流程完全不同不在本文讨论范围内。在购买或确认型号时务必看清后缀。对应的IO板计算模块本身只有金手指接口必须搭配专用的IO板才能供电和连接外设。不同代际的计算模块需要匹配的IO板Compute Module 1/3/3使用通用的Compute Module IO Board。Compute Module 4使用Compute Module 4 IO Board。Compute Module 5使用Compute Module 5 IO Board。 IO板不仅是载体其上的跳线帽是控制启动模式的关键。切勿混用物理接口和供电设计都不同强行插入会损坏设备。一台主机电脑用于运行刷写工具和提供镜像文件。它可以是Linux电脑推荐树莓派本身Raspberry Pi 4或5运行64位Raspberry Pi OS就是绝佳的主机兼容性最好。Ubuntu等主流发行版也可。macOS电脑操作稍复杂需要从源码编译工具。Windows 11电脑有官方安装包相对方便。 我的经验是Linux环境尤其是树莓派本身是最稳定、问题最少的平台后续的命令行操作也最为直接。连接线缆CM4及更早型号的IO板需要一根Micro USB数据线连接IO板上的“USB Slave”端口到主机。CM5 IO板需要一根USB-C数据线同样连接“USB Slave”端口。重要提示务必使用数据线而非仅能充电的电源线。很多廉价的USB线内部只有电源引脚无法传输数据。如果你发现主机无法识别设备首先应怀疑线缆。电源为IO板供电。通常IO板有桶形插座或USB-C电源接口使用官方推荐规格的电源适配器即可。注意很多用户反馈识别失败的问题根源在于使用了USB集线器。USB协议在枚举设备时对时序要求严格一些质量不佳或芯片兼容性差的集线器会导致通信失败。最稳妥的做法是将IO板直接连接到主机电脑的USB端口上尤其是USB 2.0端口兼容性通常更好。2.2 理解启动模式与跳线设置这是整个流程中最关键的一步设置错误会导致计算模块无法进入刷写模式。其原理是通过物理跳线改变计算模块上某个GPIO引脚的电平告诉芯片“这次不要从内部的eMMC启动请等待来自USB的指令。”CM4/CM5 IO板关键跳线是J2 (nRPI_BOOT)。刷写模式需要插上跳线帽连接两个针脚。此时nRPI_BOOT信号被拉低Enable禁用了从eMMC启动迫使芯片进入USB启动等待状态。正常启动模式拔掉跳线帽。此时nRPI_BOOT信号被拉高Disable芯片会尝试从eMMC启动你刚刚刷入的系统。CM1/CM3 IO板关键跳线是J4 (USB SLAVE BOOT ENABLE)。刷写模式将跳线帽设置在引脚1-2上标记为USB BOOT ENABLED。正常启动模式将跳线帽设置在引脚2-3上标记为USB BOOT DISABLED。实操心得在操作前花一分钟对照IO板丝印图确认跳线位置。很多匆忙中的失败都是跳线设错导致的。完成刷写后务必记得将跳线改回正常启动模式否则下次上电它又会傻等着你去刷机。3. 主机环境配置与rpiboot工具详解主机电脑需要安装一个名为rpiboot的工具。这个工具的作用是当计算模块处于USB启动模式并连接主机时rpiboot会向计算模块发送一个极小的引导程序第二阶段的bootloader和固件。计算模块的芯片内置的ROM程序第一阶段的bootloader接收到这些数据后会将其运行起来这个引导程序随后会将计算模块的eMMC配置成一个USB大容量存储设备。3.1 Linux主机配置以树莓派OS为例这是最推荐的路径步骤简洁明了。安装rpiboot打开终端一行命令即可。系统会从仓库中下载并安装预编译好的rpiboot工具及其依赖。sudo apt update sudo apt install rpiboot -y安装完成后可以通过rpiboot --version查看版本号以确认安装成功。连接与上电用数据线将IO板的USB Slave口连接到树莓派主机的USB口上。然后再给IO板接通电源。这个顺序有时有影响先连接数据线可以确保主机能捕获到设备插入的整个枚举过程。运行rpiboot在终端中执行sudo rpiboot此时终端会挂起并显示类似Waiting for BCM2835/6/7/2711...的信息。这表明rpiboot正在等待计算模块连接并进入可引导状态。触发计算模块启动确保IO板上的跳线已设置为刷写模式。然后短按一下IO板上的“RUN”或“RESET”按钮如果有或者直接给IO板重新上电。这个操作是告诉计算模块“现在开始启动流程”由于跳线设置为USB启动它就会响应主机的rpiboot工具。识别设备如果一切顺利几秒钟后rpiboot会输出一系列信息最后可能显示Loading: mass-storage-gadget...并退出。此时计算模块的eMMC应该已经作为存储设备挂载到了主机。 你可以通过lsblk命令来查看。你会看到多出来一个块设备比如/dev/sda或/dev/sdb其容量正好对应你的计算模块的eMMC大小例如8GB、16GB、32GB。lsblk输出示例NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINTS sda 8:0 0 14.9G 0 disk mmcblk0 179:0 0 29.7G 0 disk ├─mmcblk0p1 179:1 0 256M 0 part /boot └─mmcblk0p2 179:2 0 29.5G 0 part /在这个例子中mmcblk0是主机树莓派自己的SD卡而sda(14.9G) 很可能就是刚刚连接的计算模块eMMC。重要排查点如果rpiboot运行后长时间等待无反应或提示超时首先检查跳线设置是否正确。检查USB数据线是否可靠尝试更换端口或线缆。尝试重新给IO板上电在rpiboot运行的情况下。对于CM4有时需要先按住IO板上的“BOOT”按钮如果有再上电进入一种更底层的恢复模式。3.2 Windows主机配置Windows用户可以使用官方提供的安装包相对省心。下载安装包前往rpiboot项目的 GitHub Releases 页面下载最新的.exe安装程序。以管理员身份运行安装右键点击安装程序选择“以管理员身份运行”。安装过程中Windows可能会弹出“驱动程序安装”的警告窗口务必选择“始终安装此驱动程序软件”或类似选项。这是安装计算模块USB设备所需驱动关键一步。重启电脑安装完成后按照提示重启电脑。这不是可选项驱动生效需要重启。连接设备并运行将计算模块跳线设为刷写模式通过IO板连接到Windows主机并上电。在开始菜单中找到并运行 “rpiboot - Mass Storage Gadget”。一个命令行窗口会弹出并执行成功后窗口会自动关闭。此时你可以在“我的电脑”或“磁盘管理”中看到一个新的可移动磁盘。Windows常见坑驱动安装失败是最常见的问题。如果设备管理器中出现带黄色感叹号的“未知设备”可以尝试手动指定驱动。在设备管理器里右键点击该设备 - “更新驱动程序” - “浏览我的电脑以查找驱动程序” - 指向rpiboot安装目录通常为C:\Program Files\Raspberry Pi\rpiboot\或类似路径下的drivers文件夹。3.3 macOS主机配置macOS没有预编译的安装包需要从源码编译对新手门槛稍高。安装编译依赖首先需要安装 Xcode Command Line Tools 和 Homebrew。xcode-select --install /bin/bash -c $(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh) brew install libusb pkg-config克隆并编译rpibootgit clone --depth1 https://github.com/raspberrypi/usbboot cd usbboot make编译成功后当前目录下会生成rpiboot可执行文件。运行并连接设备先运行工具指定使用64位的大容量存储模式sudo ./rpiboot -d mass-storage-gadget64再将计算模块跳线设为刷写模式通过IO板连接到Mac并上电。工具识别到设备后macOS可能会弹窗提示“您插入的磁盘电脑无法读取”。一定要点击“忽略”不要点击“初始化”。这个弹窗是正常的因为eMMC目前是空白或未格式化的状态。点击忽略后磁盘就会出现在“磁盘工具”或diskutil list命令的列表中。4. 镜像烧录工具选择与实操命令当计算模块的eMMC被成功识别为存储设备例如/dev/sda后烧录镜像就变成了一个标准的磁盘写入操作。你有两个主流选择图形化的 Raspberry Pi Imager 或命令行的dd工具。4.1 使用Raspberry Pi Imager推荐新手这是最安全、最不易出错的方法尤其适合刷写官方系统镜像。启动Imager在你的主机电脑上打开 Raspberry Pi Imager。选择操作系统点击“选择操作系统”你可以从列表中选择一个如Raspberry Pi OS或者点击“自定义”选择你已下载好的.img镜像文件。选择存储设备点击“选择存储设备”。这里需要非常小心。在列表中找到代表你计算模块eMMC的那个设备通常可以通过容量来辨别例如“14.9 GB USB驱动器”。务必再三确认选错了会覆盖你主机电脑的硬盘写入点击“下一步”再点击“是”确认覆盖。Imager会自动完成格式化和写入并会在最后验证写入的数据是否正确。这个过程耗时取决于镜像大小和USB速度。Imager的优势除了操作简单它还能在烧录前对镜像进行一些自定义设置如预配置Wi-Fi、SSH、主机名、用户名密码等这对于批量部署或无头无显示器启动的设备极其有用。4.2 使用dd命令推荐高级用户与自动化dd是Linux/macOS下的底层磁盘复制工具功能强大但需要谨慎使用因为一旦目标设备指定错误后果是灾难性的。基本命令格式如下sudo dd if/path/to/your/image.img of/dev/sdX bs4M statusprogress convfsync让我们拆解这个命令的每个部分及其背后的考量if/path/to/your/image.imgif代表输入文件input file。这里替换成你的系统镜像文件的实际路径例如~/Downloads/raspios_lite_arm64.img。of/dev/sdXof代表输出文件output file。这是最危险的部分。/dev/sdX必须替换为计算模块eMMC对应的设备标识符如/dev/sda或/dev/sdb。绝对不要指向你的系统硬盘如/dev/mmcblk0,/dev/nvme0n1使用lsblk命令在插入设备前后对比确认新增的设备名。bs4M块大小block size。设置为4兆字节。这个值不是随便定的。设置过小如默认的512字节会导致写入速度极慢因为IO次数太多。设置过大如100M可能会超出某些缓冲区限制或造成不必要的内存占用。4M是经过实践检验的、在兼容性和速度之间取得良好平衡的值。statusprogress显示写入进度。这是现代dd版本的一个非常实用的参数能让你实时看到写入速度和已完成量避免在漫长的等待中焦虑。convfsync确保数据完全同步到物理存储后再返回。这保证了在命令完成后所有数据都已切实写入eMMC而不是还在操作系统的缓存里。执行过程输入命令并按回车后终端会开始显示进度。写入一个完整的Raspberry Pi OS镜像到32GB eMMC通过USB 2.0接口可能需要20-30分钟通过USB 3.0接口会快很多。期间请保持设备连接稳定不要断电或拔线。写入完成后的验证dd命令本身没有内置验证。一个简单的验证方法是写入完成后重新拔插设备或重新运行sudo rpiboot让主机再次识别然后使用lsblk查看设备。你应该能看到设备下出现了两个分区以Raspberry Pi OS为例NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINTS sda 8:0 0 29.7G 0 disk ├─sda1 8:1 0 256M 0 part └─sda2 8:2 0 29.5G 0 partsda1是启动分区FAT32格式sda2是根文件系统分区通常是ext4。你可以手动挂载它们检查内容sudo mkdir -p /mnt/cm_boot /mnt/cm_root sudo mount /dev/sda1 /mnt/cm_boot sudo mount /dev/sda2 /mnt/cm_root # 查看文件 ls /mnt/cm_boot/ ls /mnt/cm_root/ # 操作完成后卸载 sudo umount /mnt/cm_boot /mnt/cm_root5. 首次启动与故障排查实录烧录完成最激动人心的时刻就是第一次启动。但这往往也是问题最容易暴露的时候。5.1 启动配置与操作更改跳线这是必须的一步将IO板上的跳线从刷写模式改回正常启动模式。CM4/CM5拔掉J2 (nRPI_BOOT) 上的跳线帽。CM1/CM3将 J4 (USB SLAVE BOOT ENABLE) 跳线帽从1-2改到2-3。断开USB数据线拔掉连接主机和IO板USB Slave端口的线。这一步很重要因为计算模块启动时如果检测到USB Slave连接可能会干扰正常的启动顺序。上电启动确保IO板连接了显示器如果需要和网络然后给IO板上电。计算模块现在应该从eMMC上的新系统启动了。你会看到屏幕上开始滚动启动日志或者绿灯有规律的闪烁。5.2 常见问题与解决方案即使严格按照步骤操作也可能遇到问题。以下是我遇到过的典型情况及其解决方法问题一主机运行rpiboot后无法识别到计算模块eMMC磁盘。可能原因与排查跳线错误再次确认跳线设置完全正确并且接触良好。USB线或端口问题换一根确认可传输数据的USB线换一个主机USB端口优先尝试USB 2.0口。供电不足IO板电源不稳定可能导致计算模块无法正常工作。使用官方推荐或质量可靠的5V电源。驱动问题Windows在设备管理器中检查是否有未识别的设备尝试重新安装驱动。rpiboot版本问题特别是在Ubuntu 24.04及更早版本中仓库里的rpiboot可能有bug。解决方案是从源码重新编译安装方法同macOS章节。计算模块硬件问题极少数情况下计算模块本身或IO板接触不良。尝试重新插拔计算模块确保金手指清洁且完全插入卡槽。问题二系统刷写成功但计算模块无法从eMMC启动无显示、绿灯常亮或不闪。可能原因与排查跳线未改回这是最常犯的错误请再次确认跳线已设置为“正常启动模式”。镜像文件损坏重新下载系统镜像并校验SHA256哈希值确保文件完整。烧录过程出错虽然dd显示完成但数据可能未完整写入。尝试用Raspberry Pi Imager重新烧录一次它会进行验证。CM3的特殊问题官方文档提到少量CM3设备因eMMC与CPU时序问题可能无法从自动创建的FAT分区启动。解决方案是手动创建启动分区将计算模块再次进入刷写模式并连接到主机。使用parted或fdisk对设备如/dev/sda重新分区。先删除所有现有分区然后创建一个起始于4MiB、大小为60MiB的FAT32主分区。sudo parted /dev/sda (parted) mklabel msdos (parted) mkpart primary fat32 4MiB 64MiB (parted) quit格式化该分区sudo mkfs.vfat -F32 /dev/sda1挂载这个分区并将官方镜像中启动分区通常是.img文件第一个分区的所有文件拷贝进去。sudo mount /dev/sda1 /mnt/boot # 假设你已经挂载了官方镜像的启动分区到 /mnt/img_boot sudo cp -r /mnt/img_boot/* /mnt/boot/ sudo umount /mnt/boot电源或外围设备问题断开所有非必要的外设如USB设备、HAT板仅连接电源和显示器看能否启动。问题三刷写速度异常缓慢。可能原因USB 2.0接口限制如果主机或IO板只有USB 2.0速度上限约35-40MB/s写入32GB镜像需要较长时间。主机性能或磁盘IO瓶颈如果主机电脑本身磁盘读写慢或CPU占用高。dd块大小设置不当bs参数设置太小。优化建议使用USB 3.0端口和数据线确保主机性能充足dd命令使用bs4M或bs8M。问题四在macOS上rpiboot运行后系统反复提示“磁盘未初始化”。原因与解决这是正常现象因为eMMC被呈现为空白磁盘。关键在于点击“忽略”。如果误点了“初始化”macOS会尝试格式化它这会破坏刷写模式。如果不小心初始化了需要重新给计算模块上电在刷写模式下并再次运行sudo ./rpiboot -d mass-storage-gadget64。5.3 批量刷写与镜像定制建议如果你需要为几十甚至上百个计算模块刷写系统手动操作是不可行的。批量刷写官方推荐使用Raspberry Pi Secure Boot Provisioner。这是一个更专业的工具链配合网络启动服务器可以自动化地完成多台设备的系统部署、安全密钥注入等流程适合生产环境。镜像定制如果你需要在刷写前对系统镜像进行深度定制如预装软件、修改配置、裁剪系统可以使用pi-gen工具。它是用来构建Raspberry Pi OS镜像的官方框架你可以基于它创建符合自己项目需求的衍生镜像然后再用本文的方法刷写到计算模块中。给树莓派计算模块刷写系统是一个连接软件与硬件、概念与实体的关键操作。整个过程像是一场精密的对话通过跳线设置发出指令通过USB通道传输引导程序最终将完整的操作系统交付给那片沉默的eMMC芯片。我最深刻的体会是耐心和细致远比技术本身更重要。每一次跳线的确认每一次设备号的核对都是对可能发生的数小时调试时间的节省。当你看到计算模块的绿灯开始有节奏地闪烁屏幕上出现熟悉的启动日志时那种将抽象代码转化为物理设备生命力的成就感正是嵌入式开发的魅力所在。
