2. 开发环境搭建：Windows/Linux/macOS下的PlatformIO与Arduino IDE配置

说实话，搞嵌入式开发这么多年，我踩过最多的坑就是环境配置。明明代码逻辑没问题，编译却报一堆莫名其妙的错误。最后发现，八成是工具链没配好。

Marlin固件的移植，说白了就是一场与编译器的博弈。你想想看，一个固件要跑在AVR、ARM、ESP32甚至RISC-V上，开发环境能不讲究吗？

这一章，我就带你把这套环境彻底捋顺。不管你是Windows党、Linux老手还是macOS用户，都能找到适合自己的路子。

2.1 开发环境选型：为什么我推荐PlatformIO？

先说说我的个人习惯。早年做Marlin移植，我一直在用Arduino IDE。后来项目越来越复杂，板子越来越多，Arduino IDE的短板就暴露了——项目管理混乱、依赖库版本冲突、没有代码补全。

直到我遇到了PlatformIO。这玩意儿，说白了就是VS Code里的一个插件，但背后是一整套嵌入式开发工具链。它解决了几个核心痛点：

• 统一的依赖管理：每个项目有自己的platformio.ini，库版本锁定，不会出现「在我电脑上能编译」的尴尬
• 多平台支持：一套代码，切换board配置就能编译不同目标
• 调试能力：配合J-Link或ST-Link，可以单步调试Marlin

当然，Arduino IDE也不是一无是处。快速验证、给学生演示、或者只是改个配置参数，它确实更轻量。我的建议是：主力用PlatformIO，备胎用Arduino IDE。

2.2 Windows环境搭建

Windows用户最多，问题也最多。嗯，这里要注意几个关键点。

2.2.1 安装VS Code + PlatformIO

步骤很简单，但顺序别搞反：

1. 下载安装 Visual Studio Code（别装成Visual Studio，那是写C#的）
2. 打开VS Code，点击左侧扩展图标，搜索「PlatformIO IDE」
3. 安装后重启，等待PlatformIO初始化（第一次会比较慢，去喝杯咖啡）

2.2.2 安装Arduino IDE（备选）

从arduino.cc下载最新版，安装时注意勾选「安装USB驱动」。这一步很多人会漏掉，导致板子连不上。

安装完成后，打开Arduino IDE，进入「文件 → 首选项」，在「附加开发板管理器网址」中添加Marlin需要的板支持包：

https://raw.githubusercontent.com/MarlinFirmware/Marlin/2.1.x/package_Marlin_index.json

然后去「工具 → 开发板 → 开发板管理器」，搜索并安装Marlin板支持包。我记得第一次装的时候，下载了将近500MB的数据，耐心等吧。

2.2.3 驱动与串口问题

Windows下最头疼的就是驱动。CH340、CP2102、FT232，每种芯片都要装对应的驱动。我的建议是直接装一个驱动精灵或者去芯片官网下载。

2.3 Linux环境搭建

Linux下配置环境，说白了就是几条命令的事。但不同发行版有细微差别，我以Ubuntu 22.04为例。

2.3.1 PlatformIO安装

Linux下推荐用命令行安装，干净利落：

# 安装Python3和pip（如果没装）
sudo apt update
sudo apt install python3 python3-pip

# 安装PlatformIO核心
python3 -c "$(curl -fsSL https://raw.githubusercontent.com/platformio/platformio/master/scripts/get-platformio.py)"

# 添加用户到dialout组（否则无法访问串口）
sudo usermod -a -G dialout $USER
# 注销重新登录生效

然后安装VS Code，再装PlatformIO插件。Linux下有个好处——串口权限问题比Windows少得多。

2.3.2 Arduino IDE安装

从官网下载Linux版，解压后运行install.sh。或者用snap安装：

sudo snap install arduino

我个人更推荐snap版，自动更新，省心。

2.3.3 权限问题处理

Linux下最常见的坑是串口权限。插上板子后，ls /dev/ttyUSB*能看到设备，但Arduino IDE或PlatformIO就是连不上。原因很简单——当前用户没有访问权限。

解决方法：把用户加到dialout组，然后注销重登。如果还不行，检查一下是不是被ModemManager占用了：

sudo systemctl stop ModemManager
sudo systemctl disable ModemManager

2.4 macOS环境搭建

macOS用户相对少，但配置起来其实最省心。为什么？因为macOS的类Unix内核和Linux很像，驱动问题也少。

2.4.1 安装Homebrew（前置条件）

Homebrew是macOS的包管理器，没有它很多工具装起来很麻烦：

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

2.4.2 安装PlatformIO

同样推荐命令行安装：

brew install python3
python3 -c "$(curl -fsSL https://raw.githubusercontent.com/platformio/platformio/master/scripts/get-platformio.py)"

然后装VS Code和PlatformIO插件。macOS下基本不会遇到权限问题，这点比Linux和Windows都友好。

2.4.3 安装Arduino IDE

从官网下载macOS版，或者用Homebrew：

brew install --cask arduino

安装完成后，记得安装Marlin板支持包，步骤和Windows一样。

2.5 验证环境：编译第一个Marlin固件

环境搭好了，得跑个例子验证一下。我习惯用Marlin的默认配置来测试。

2.5.1 克隆Marlin源码

git clone https://github.com/MarlinFirmware/Marlin.git
cd Marlin

2.5.2 用PlatformIO编译

进入Marlin目录，找到platformio.ini文件。默认配置是针对很多板子的，我们只编译一个：

# 编译Mega2560版本
pio run -e mega2560

第一次编译会下载工具链和依赖库，大概需要5-10分钟。看到类似下面的输出，说明环境没问题：

==========================================
[SUCCESS] Took 45.32 seconds
==========================================

2.5.3 用Arduino IDE编译

打开Arduino IDE，选择「工具 → 开发板 → Arduino Mega 2560」。然后打开Marlin源码中的Marlin.ino，点击「验证」按钮。

如果编译通过，恭喜你——环境搭建完成！

2.6 知识体系总览

下面这张图，是我梳理的本章知识结构。你可以把它当作一个检查清单：

2.7 避坑指南：我踩过的那些坑

最后，分享几个我实际项目中遇到的坑，希望能帮你省点时间：

• Python版本问题：PlatformIO依赖Python 3.6+。我曾经在Ubuntu 18.04上默认Python是3.5，折腾了半天才发现是版本太低。升级到3.8后一切正常。
• VS Code插件冲突：如果你同时装了C/C++、Python、PlatformIO等多个插件，偶尔会出现IntelliSense冲突。我的做法是禁用C/C++插件，只用PlatformIO自带的代码分析。
• 防火墙拦截：公司网络环境下，PlatformIO下载工具链可能被防火墙拦截。解决方案是配置代理，或者手动下载工具链放到~/.platformio/packages目录下。
• 路径空格：Windows下，如果项目路径包含空格（比如D:\My Projects\Marlin），编译会报错。把项目放到没有空格的路径下，比如D:\Projects\Marlin。

环境搭建这部分，说白了就是一次性的体力活。配好了，后面几十章都能顺畅跑。配不好，每编译一次都是折磨。所以，花点时间把这一步走扎实，绝对值。