Arduino 工程迁移到 PlatformIO 步骤

你的工程/
├── platformio.ini          # 工程配置文件（核心）
├── src/                    # 所有源码放在这里
│   ├── main.cpp            # 必须存在，程序入口
│   ├── main.h
│   ├── xxx.cpp
│   └── xxx.h
└── include/                # （可选）额外的头文件路径

操作要点：

将 Arduino 的 .ino 文件改名为 main.cpp
其他 .cpp / .h 文件直接复制到 src/ 目录
不再需要保留 Arduino 的项目文件夹命名约束

第 2 步：编写 `platformio.ini`

在工程根目录创建 platformio.ini 文件，内容模板如下：

[env:你的开发板]
platform = 平台名           ; espressif32 / atmelavr / ststm32 ...
board = 开发板ID            ; esp32dev / uno / nodemcuv2 ...
framework = arduino
monitor_speed = 115200
upload_speed = 921600

; ========== 依赖库 ==========
lib_deps =
   库名1
   库名2

如何获取开发板 ID？
访问 PlatformIO Boards 文档，搜索你的开发板型号（如 ESP32 Dev Module 对应 esp32dev，Arduino Uno 对应 uno）。

提示：
upload_speed 对于 ESP32 系列建议设为 921600，可显著加快烧录速度。

第 3 步：确定库依赖（最容易出问题）

Arduino IDE 的库管理器会自动解析依赖，但 PlatformIO 需要你在 lib_deps 中显式声明。

3.1 列出原工程用到的所有库

搜索原 .ino 文件中所有 #include 的第三方库头文件，例如：

#include <ESPAsyncWebServer.h>
#include <AsyncTCP.h>
#include <ArduinoJson.h>

3.2 在 PlatformIO 库注册表查找确切名称

打开 PlatformIO Registry，搜索每个库名。

关键规则：优先使用 作者/库名 格式，避免模糊库名引发平台错误

Arduino IDE 中的写法	PlatformIO 中推荐的写法
`ESP Async WebServer`	`esphome/ESPAsyncWebServer-esphome@^3.0.0`
`AsyncTCP`	`esphome/AsyncTCP-esphome@^2.0.0`
`ArduinoJson`	`bblanchon/ArduinoJson@^6.21.0`

原因： 模糊名称（如 AsyncTCP）可能解析到其他平台的版本（例如 AsyncTCP_RP2040W 被错误用于 ESP32 工程）。

3.3 `@^版本号` 的含义

@^6.21.0 → 锁定大版本 6，接受 6.x 的更新（推荐）
不加版本号 → 每次编译都拉取最新版，可能引入不兼容变更

第 4 步：调整源码（Arduino → PlatformIO 差异）

4.1 入口文件命名与内容

main.cpp 必须存在，且第一个 #include 必须是 <Arduino.h>
setup() 和 loop() 函数放在 main.cpp 中

#include <Arduino.h>

void setup() {
    // 初始化代码
}

void loop() {
    // 主循环代码
}

4.2 函数前置声明（严格模式）

PlatformIO 使用的编译器（GCC/Clang）比 Arduino IDE 更严格。所有在定义前被调用的函数，必须加前置声明。

// 在文件顶部加前置声明
void fastTask(void *pvParameters);
void slowTask(void *pvParameters);

void setup() {
    xTaskCreatePinnedToCore(slowTask, "Slow", 4096, NULL, 1, NULL, 0);
}

// 实际定义在后面
void slowTask(void *pvParameters) {
    while(1) { delay(1000); }
}

如果不加前置声明，编译时会报错： 'slowTask' was not declared in this scope

4.3 头文件 `#include` 路径规则

框架自带库用 <>：#include <WiFi.h>
自己工程的头文件用 ""：#include "main.h"
第三方库也用 <>：#include <ArduinoJson.h>

第 5 步：首次编译（下载工具链）

在 VS Code 底部蓝色状态栏点击 对勾 (Build) 按钮，或在终端执行：

pio run

首次编译会自动下载目标平台的工具链（例如 ESP32 工具链约几百 MB），耗时 3~10 分钟
下载完成后才开始正式编译
这一步也是解决 IntelliSense 报错的前提：框架头文件（如 WiFi.h）未下载前，IDE 找不到它们，会报红线

第 6 步：修复常见编译错误（按频率排序）

错误类型	示例报错	解决方法
库解析到错误平台	`AsyncTCP_RP2040W` 被拉取到 ESP32 工程	改用 `作者/库名@版本` 精确指定（见第 3 步）
函数未声明	`'slowTask' was not declared in this scope`	加前置声明（见 4.2）
头文件找不到	`fatal error: WiFi.h: No such file or directory`	先完成第 5 步编译，再重建 IntelliSense 索引
类型不匹配	`ip_addr_t has no member named 'addr'`	框架版本不兼容，换用 `esphome` 分支的库（如 AsyncTCP）
`setup()`/`loop()` 重复定义	`multiple definition of 'setup()'`	检查是否有其他 `.cpp` 文件也定义了这两个函数

第 7 步：修复 IntelliSense（VS Code C/C++ 扩展报红线）

即使编译通过，编辑器仍可能出现红色波浪线（找不到头文件或类型）。请按以下步骤修复：

按 Ctrl+Shift+P 打开命令面板
输入并选择：PlatformIO: Rebuild IntelliSense Index
等待索引重建完成（右下角有进度提示，约 10~30 秒）
```
pio project init --ide vscode
```

快速检查清单

在提交代码或分享工程前，请逐项确认：

platformio.ini 中 platform / board / framework 填写正确
lib_deps 使用 作者/库名@版本 格式，没有模糊库名
main.cpp 第一个 #include 是 <Arduino.h>
所有定义在调用位置之后的函数都已加前置声明
首次编译已执行，工具链已下载
IntelliSense 索引已重建，无红色波浪线

AI硬件创业社区

智能硬件社区聚焦AI智能硬件技术生态，汇聚嵌入式AI、物联网硬件开发者，打造交流分享平台，同步全国赛事资讯、开展 OPC 核心人才招募，助力技术落地与开发者成长。

更多推荐

【实战】STM32八大系列怎么选？F0/F1/F4/H7/L4/U5/WB/G0核心参数对比与嵌入式物联网项目选型决策（附选型评估代码）

STM32八大系列选型的核心原则是"够用即可，适度预留"：功耗约束（电池供电锁L4/U5）是不可妥协的硬约束，关键外设（以太网/CAN-FD/无线RF/高级定时器）直接排除不支持的系列，算力需求（FPU/DSP/Cache）决定算法实现方式，成本预算在满足前三项的前提下选最低方案，生态与供货优先选上市2年以上的成熟型号并确认替代方案。对绝大多数工业控制和物联网项目，STM32F4是性能、生态、成本