把主力电脑从 Windows 换成 MacBook 之后，我最头疼的不是找 IDE，而是烧录嵌入式固件。手上几块合宙的开发板等着跑 LuatOS，可网上一搜，几乎所有教程截图都是 Windows 界面，社区里也默认 Luatools 只能在 Windows 上用。我一开始也差点为了烧录单独装一台虚拟机，后来才发现合宙官方其实一直在提供 Luatools for macOS 安装包，整个烧录和串口调试的思路完全可以迁移过来。这篇东西就是我实际折腾下来的完整记录，覆盖驱动安装、系统权限、进入下载模式、固件烧录、日志抓取和常见故障排查，给那些手头只有 Mac、又想玩合宙 Air 系列或 ESP32 系列的同学一个可以直接照着抄的路线。
1.1 先打破一个认知误区：Luatools 真的有 macOS 版
很多人以为 Luatools 只能跑 Windows，其实官方发布包里一直有 macOS 版本，安装包是标准 dmg 格式，拖动安装就行。我第一次打开前心里也没底，怕它是拿 Wine 套壳的，结果发现界面和 Windows 版几乎一致，功能也没有明显阉割。Luatools 这个工具在 LuatOS 开发里的地位，相当于 STM32 的 STM32CubeProgrammer 加串口助手的合体：它负责往芯片里下载固件和脚本，同时还能打开一个串口日志窗口直接看运行输出。对于平时用 Mac 做开发的人来税，这就意味着不需要为了刷一块板子单独装虚拟机，也不用每次都在两台电脑之间来回切。你只需要这一款工具，就能完成从空片到跑起来整个流程。
顺带说一句，合宙的板子不只有 Air 系列，很多 ESP32 系列的开发板也能跑 LuatOS，Luatools 同样支持。所以哪怕你手里的板子不是合宙自家模组，也有机会用这个工具烧录。当然，具体到某些小众芯片或者特殊批次，官方适配的进度会有差别，我建议先用自己手上板子的具体型号去对照官方支持列表，别想当然。
1.2 macOS 的设备模型为什么会让新手懵
Windows 用户习惯了"设备管理器里看到一个 COM3、COM4"，到 macOS 上会突然不知道去哪里找串口。macOS 没有盘符和 COM 口的概念，所有 USB 转串口设备会被映射成类似/dev/cu.usbserial-xxx这样的设备文件。cu这个前缀是"调用端口"的意思，一般用来做拨号或者串口连接，烧录和调试时认它就行。另一类文件是/dev/tty.usbserial-xxx，属于"终端端口"，功能上接近，但不少工具只认cu开头那个。
如果你在终端里执行：
ls /dev/cu.*就能看到当前系统里所有可用的串口设备。插上开发板之前和之后各执行一次，新增的那个路径就是你的板子。Windows 里需要看驱动有没有装好，Linux 和 macOS 也类似，只是表现形式从"有没有出现 COM 口"变成了"有没有出现 cu 设备文件"。理解了这个模型，后面所有烧录和串口调试操作都不会再觉得绕。
1.3 什么情况下还是建议你用 Windows 或换批量方案
Mac 能解决 90% 的日常单板烧录需求，但有一类场景我还是建议老老实实回到 Windows：产测和批量烧录。Luatools 本身虽然跨平台，但一些老型号模组的历史固件、特殊批次 BootROM，以及工厂里的自动烧录产线，很多都依赖 Windows 下的专属驱动和脚本工具链。如果你只是自己开发调试，Mac 完全够用；一旦要给别人做量产工具或者批量烧录测试，先把环境固化到 Windows 上，能少踩一堆兼容性的暗坑。这点不是 macOS 或者 Luatools 的问题，而是嵌入式工具链的历史包袱决定的。
2. 上路前的准备：转串芯片、系统拦截和 BOOT 模式
2.1 先搞清楚你的板载转串口芯片是哪一颗
烧录失败最隐蔽的原因之一，就是 USB 转串口驱动不对。合宙的开发板板载的转串口芯片一般就那几颗：CH340/CH341、CP2102/CP210x，还有一些国产兼容芯片。你可以在板子背面丝印上找芯片型号，也可以插上 USB 后用系统信息查看。驱动没装对的时候，插上板子系统毫无反应，/dev/cu.*里什么都不会新增。
| 常见芯片 | 官方驱动 | 注意事项 |
|---|---|---|
| CH340 / CH341 | 芯片原厂官方 macOS 驱动 | 老版本驱动在 Apple Silicon 上可能加载失败，优先找最新版 |
| CP210x 系列 | Silicon Labs 官方 VCP 驱动 | 安装后需要到系统设置里允许系统软件加载 |
| 板载合成/国产兼容芯片 | 看板子原理图和厂商说明 | 有时会兼容 CH340 或 CP210x 的指令集，按兼容型号装驱动 |
安装完驱动，强烈建议插上开发板后先跑一次system_profiler SPUSBDataType，看看系统到底认不认这个 USB 设备。如果这里能看到设备但/dev/cu.*里没有，基本可以断定是驱动没加载成功。
注意：在 Apple Silicon 的 Mac 上，老版本的内核扩展驱动可能直接被系统拒绝加载。处理方法只有一个——去芯片原厂官网下载适配新版系统的驱动，不要强行关闭系统安全策略。安全校验机制是保护措施，不值得为一块开发板绕过去。
2.2 第一次打开 Luatools，macOS 会拦你几次
下载好 Luatools 的 dmg 之后，双击安装，第一次从访达打开应用，大概率会看到"无法验证开发者"的提示。这不代表软件有问题，只是因为官方没有做 Apple 的公证流程。处理办法是：不要在弹出框里直接点"移到废纸篓"，而是到访达里找到应用图标，右键选择"打开"，系统会多出来一个"仍要打开"的按钮，点它就行。
之后 macOS 可能还会在"系统设置 → 隐私与安全性"里要求你允许来自互联网的下载内容。整个流程走完，Luatools 才能正常启动。如果第一次打开后提示应用已损坏，我建议不要急着去网上找"跳过签名验证"的命令，先把原安装包重新下载一次，很多时候是下载过程中的文件损坏，重下就好。盲目去执行关闭 Gatekeeper 的命令，等于给以后所有不明来源软件打开大门，不值得。
2.3 开发板的 BOOT 按键不是摆设
烧录 LuatOS 和烧录 Arduino 那种串口直接复位进 bootloader 不一样，大部分合宙模组需要你手动让芯片进入"下载模式"。合宙的 Air 系列开发板上通常有一个 BOOT 按键，操作方式是：按住 BOOT 键不要松，用 USB 线把板子连到 Mac，等电脑识别到串口设备之后再松开。如果你板子上已经跑过完整固件，有时候不用按键，直接通过软件复位也能碰巧进入下载模式，但最稳定的还是物理按键。
ESP32 系列则通常是按住 IO0 脚对应的 BOOT 按键再上电，原理是把 IO0 拉低让芯片从下载模式启动。具体按键位置不同板子不一样，但思路相通。我的建议是：第一次烧录前先不打开任何工具，按住下载按键插 USB，然后在终端执行：
ls /dev/cu.*确认确实多出来一个新设备，再打开 Luatools 操作。这样能避免"点了下载却找不到设备"的尴尬。
3. Luatools for macOS 烧录全流程：从选固件到验证
3.1 先选对固件，别看见 bin 就往下烧
LuatOS 的固件是按芯片型号区分的，Air780E 的固件不能烧到 Air105 上，ESP32-C3 的固件更不能往别的芯片上硬灌。选固件是新手最容易翻车的一步，好在合宙的官方资源站点把固件按模组型号和日期归档得很清楚，你只需要进入对应芯片的目录，找最新日期的 bin 文件下载就行。目录里一般会区分正式版和每日构建版，开发调试我建议用最新稳定版，除非你需要尝鲜某个新功能。
下载固件时还要顺便确认一下你的板子 Flash 大小，同型号不同 Flash 容量的固件也不能混用。Luatools 界面上一般会让选择芯片型号和 Flash 参数，如果你用的是官方开发板，直接按板子丝印型号选就行。别把"芯片能跑多大 flash"和"板子焊接了多大 flash"搞混，前者你改不了，后者看丝印，两个不一致时以板子实际焊的为准。
3.2 打开 Luatools 后需要做的最小配置
Luatools 界面乍看有点复杂，其实烧录时只需要关注几个关键位置：
| 界面区域 | 你该做什么 | 我的建议 |
|---|---|---|
| 串口选择 | 选中你在/dev/cu.*里看到的那个设备 | 如果有多个设备，拔插一次板子确认哪个是新增的 |
| 芯片型号 | 选择你板子对应的型号 | 选错型号会直接下载失败 |
| 固件路径 | 指定刚才下载的 bin 文件 | 路径不要放中文目录，某些版本会莫名出问题 |
| 波特率 | 一般保持默认 | 工具会按固件要求自动协商，手动乱改反而出错 |
| 下载模式 | 选择"下载固件" | 不要顺手勾选擦除全部 flash，除非你知道后果 |
在点击下载之前，先把 Luatools 自带的串口日志窗口关掉，或者至少断开占用。很多人会遇到"烧录失败，打开串口出错"，原因就是日志窗口还占着同一个串口没放。这个问题在 Windows 上也存在，但 macOS 因为设备文件是独占访问的，表现得更加干脆——工具直接报打不开设备。
3.3 从点击下载到进度条跑完的完整步骤
我整理一下自己在 macOS 上最顺利的一次完整操作流程，照做基本不会翻车：
- 打开 Luatools，先在串口选择里选中目标设备，然后加载对应固件文件，确认芯片型号无误。
- 按住开发板上的 BOOT 键，保持按住状态，重新插一次 USB 线（或者按一下复位键），让芯片进入下载模式。
- 点击 Luatools 里的下载按钮，这时候工具会开始等待设备握手。如果你的板子已经处于下载模式，点击后马上就会看到进度条。
- 进度条走完，工具会提示下载完成。这时按一下板子上的复位键，或者重新插拔 USB，让芯片退出下载模式并从新固件启动。
- 打开串口日志窗口，如果能看到正常的开机日志输出，说明烧录真的成功了。
很多第一次用的人会在第 3 步卡住：点击下载后工具一直提示"等待设备进入下载模式"。这就是板子没有成功进入下载模式，不要反复点下载按钮，重新按住 BOOT 插 USB 再来一次。如果在终端里能看到设备文件，但 Luatools 就是无法握手，换一根数据线再试。
3.4 烧录成功后的三个验证手段
进度条跑完不等于固件一定工作正常，我习惯于做三个验证。第一个是重新上电后看串口日志里有没有版本号输出，LuatOS 启动时一般会打印系统版本和编译时间，看到这些基本可以断定固件引导成功。第二个是往串口里发一些简单指令或者跑一段点灯脚本，验证应用层逻辑。第三个是再尝试一次烧录流程，看看能否顺利进入下载模式并再次写入，这一步能排除偶发的 flash 写入问题。三个验证都通过，这块板子才算真正进入可开发状态。
4. 串口调试：自带日志窗口和终端的三种玩法
4.1 Luatools 的串口日志窗口其实够用
Luatools 自带串口日志窗口，功能上能满足大部分调试需求。它能实时显示芯片输出的日志，还带时间戳，看运行顺序和耗时非常直观。LuatOS 的日志输出量比较大，尤其开了多个调试等级之后，Windows 用户一般习惯直接在这个窗口里过滤，macOS 版也一样，不需要额外装软件。
有一点要提醒：Luatools 的日志窗口和烧录功能共用同一个串口资源，占用端口的时候不能同时烧录。我自己的习惯是，先开日志窗口观察启动顺序，确认没问题后先断开日志，再进烧录流程。如果你要长时间采集日志，同时对固件做反复修改烧录，就不如直接用终端工具，或者用脚本把日志重定向到文件里慢慢翻。
4.2 终端三板斧：ls、screen、minicom
在 macOS 上做串口调试，最轻量的方式其实是终端自带的工具。先确认设备路径：
ls /dev/cu.*然后直接用screen接上串口：
screen /dev/cu.usbserial-xxx 115200把路径替换成你实际的设备文件名，波特率按固件要求修改。LuatOS 默认串口日志波特率一般是 115200，但也有模组出厂时是其它值，不确定就先看官方文档。退出 screen 的方法是先按Ctrl+A，再按K，最后按y确认关闭窗口。如果直接拔线，screen 会一直挂在那里，下次插上相同路径可能报端口被占用。
如果你需要更强大的功能，比如保存日志、设置行缓冲、定时发送十六进制数据，可以装minicom，通过brew install minicom安装，然后在minicom -s里配置串口设备和波特率。minicom 对习惯经典嵌入式调试方式的人来说更顺手，但它的菜单交互对新手不太友好，我一般只在需要脚本自动化交互时才用它。
4.3 串口调试中三个高频故障：乱码、掉线、重启循环
在 macOS 上调试串口，我遇到最多的问题就是乱码。乱码的第一嫌疑永远是波特率不一致，其次才是数据线质量。有些劣质 USB 线看起来能供电，但数据传输不稳，表现出来的症状就是日志突然中断或者整段乱掉。遇到这种情况，先确认波特率设置，再换一根短线试试。
掉线问题则更多与驱动和供电有关。macOS 的 USB 电源管理有时会让串口芯片进入低功耗状态，板子长时间不通信后，再打开日志窗口就看不到输出了。解决方式是重新插拔 USB 线，或者在系统设置里调整电能与电池相关选项。如果板子用 USB 供电，同时又在驱动 LED 等外设，电源余量不足也会导致反复掉线，这时最好改用独立供电。
重启循环这个故障需要结合日志判断。板子断电重启、打印到一半又重启，大多是代码里看门狗没喂，或者固件跑飞了。在 macOS 上排查的思路和 Windows 一样，先把日志完整抓下来，看最后一次输出卡在哪个模块，再针对性调整。这个问题的根源不在操作系统，不要浪费时间在烧录工具上找原因。
5. 踩坑实录：我在 Mac 上烧录遇到的问题与排查链路
5.1 "卡在 Downloading 69%"：不是固件坏了，是串口被占了
有段时间我烧录一块 Air780E，每次进度条走到 69% 就停滞，然后报错退出。一开始我以为是固件问题，换了几个版本都一样，甚至怀疑是板子 flash 损坏。后来仔细排查才发现，我同时开着 Luatools 的串口日志窗口，日志窗口还停留在同一个串口设备上。点击下载时，工具无法完全独占串口，进度走到一半协议握不上，直接失败。
后续我把排查链路固定成了这个顺序：先关掉所有占用串口的窗口和终端进程，再重新插拔板子让系统重新枚举设备，最后打开 Luatools 点下载。这个"关占用 → 重枚举 → 再下载"的三步操作，解决了我遇到的绝大多数烧录异常。
5.2 驱动装了，/dev 下面却还是看不到端口
还有一次更隐蔽：驱动明明装了，板子插入后系统信息也能看到 USB 设备，但/dev/cu.*里就是没有新设备。用system_profiler SPUSBDataType查看，发现设备被识别成一颗兼容 CH34x 的国产芯片，但我装的是老版本 CH340 驱动，它在新版 macOS 上压根没被加载。那个设备在 USB 层面是好的，操作系统也枚举到了，只是没有对应的 tty 设备节点。
这种问题只能去芯片原厂网站找对应型号、对应系统架构的最新驱动。安装完驱动后记得重启一下 Mac，或者至少重新插拔设备。内核扩展驱动的加载时机往往不是你想象的那种即时生效，重启一次能省下很多排查时间。
system_profiler SPUSBDataType | grep -A 10 -i "CH340\|CP210\|USB Serial"如果能看到厂商和芯片型号，但设备节点缺失，优先怀疑驱动版本不匹配。如果连这条命令里都看不到设备，那就是 USB 线质量或板子本身没进入正常供电状态，和驱动无关。
5.3 从 Intel 换到 Apple Silicon 时我重新踩了一遍的坑
换到 Apple Silicon 芯片的 Mac 之后，我又把之前踩过的驱动坑重新踩了一遍。老款 CH340 驱动在 Intel Mac 上明明用得好好的，到了新机器上直接无法加载，原因是 Apple Silicon 对内核扩展的签名和加载机制更严格，旧驱动没有适配新架构。
所以如果你是 M 系列芯片的用户，优先去下载官方标注兼容 Apple Silicon 的驱动版本。Luatools 本身在两种芯片上都跑得挺顺，串口调试和烧录流程没有让我觉得有架构差异。我的经验是：先把 USB 转串口驱动和系统安全策略搞定，工具层面的折腾就少很多。那些反复发生的烧录失败，绝大多数不是工具的问题，而是驱动没加载或者端口被占用。
最后分享一个小习惯：每次在同一块板子上反复烧录时，我会在笔记本侧面贴一张小纸条，写上这块板子对应的芯片型号和 BOOT 按键操作方式。调试到半夜脑子不清醒时，这张纸条比任何文档都有用。烧录这事的难点从来不在操作复杂，而在细节太多，把细节变成习惯之后，Mac 上烧 LuatOS 其实比想象中顺畅得多。
