在 VS Code 使用 PlatformIO 開發 Arduino 與 ESP32

本文介紹如何在 Visual Studio Code 中安裝 PlatformIO、建立專案、撰寫程式、編譯、燒錄，以及使用序列埠監控器查看輸出。

範例以搭載 ATmega328P 的 Arduino Uno 為主；PlatformIO 也支援 ESP32、ESP8266、RP2040 等開發板，但建立專案時必須選擇與手上硬體相符的板型。

PlatformIO 常縮寫為 PIO。它會替每個專案管理開發平台、編譯工具、函式庫與燒錄工具，因此通常不需要另外安裝 Arduino IDE。

目錄

開始前要準備什麼

• Visual Studio Code
• 支援資料傳輸的 USB 線
• 一塊 Arduino、ESP32 或其他 PlatformIO 支援的開發板
• 第一次建立專案時可正常連線的網路

安裝 USB 驅動程式

開發板連接電腦後，Windows 必須能辨識板子上的 USB 介面。不是所有開發板都使用 CH340，也不是所有板子都要另外安裝驅動程式。

在 Windows 確認序列埠

1. 用 USB 線連接開發板。
2. 開啟「裝置管理員」。
3. 展開「連接埠（COM 和 LPT）」。
4. 記下新出現的序列埠，例如 COM3 或 COM5。

若裝置旁有黃色驚嘆號、完全沒有出現 COM Port，或顯示未知裝置，再依 USB 晶片安裝對應驅動：

• WCH CH340／CH341 驅動
• Silicon Labs CP210x 驅動

有些 USB 線只能供電、不能傳輸資料。板子有亮燈但電腦找不到序列埠時，先換一條確定能傳資料的線。

安裝 PlatformIO IDE

1. 安裝並開啟 Visual Studio Code。
2. 點選左側的「Extensions（擴充功能）」。
3. 搜尋 PlatformIO IDE。
4. 確認發布者為 PlatformIO，然後按下「Install」。
5. 安裝完成後，依畫面提示重新載入或重開 VS Code。

安裝成功後，左側活動列會出現 PlatformIO 圖示。點選它即可開啟專案工具。

使用 VS Code 擴充功能時，不需要另外安裝 PlatformIO Core；擴充功能已包含所需的 Core 與終端機環境。

建立第一個專案

1. 開啟 New Project

在 PlatformIO Home 選擇「New Project」。

2. 設定專案

若保留預設位置，專案通常會建立在使用者文件目錄下。若想放在自己的程式碼目錄，取消「Use default location」並選擇路徑。

按下「Finish」後，PlatformIO 會下載開發板所需的平台、Framework 與工具鏈。第一次建立專案可能需要幾分鐘，請保持網路連線並等待完成。

認識 PlatformIO 專案結構

Arduino Uno 的 platformio.ini 基本內容如下：

[env:uno]
platform = atmelavr
board = uno
framework = arduino
monitor_speed = 9600

修改 platformio.ini 後，PlatformIO 可能會重新安裝套件或更新程式碼索引，等待右下角處理完成再編譯。

撰寫第一支程式

開啟 src/main.cpp。

PlatformIO 使用標準 C++ 原始碼檔。使用 Arduino 的 pinMode()、digitalWrite()、Serial 等 API 時，必須先加入：

#include <Arduino.h>

以下程式會讓板載 LED 每秒切換一次，同時將狀態送到序列埠：

#include <Arduino.h>

void setup() {
  pinMode(LED_BUILTIN, OUTPUT);
  Serial.begin(9600);
}

void loop() {
  digitalWrite(LED_BUILTIN, HIGH);
  Serial.println("LED ON");
  delay(1000);

  digitalWrite(LED_BUILTIN, LOW);
  Serial.println("LED OFF");
  delay(1000);
}

Serial.begin(9600) 必須與 monitor_speed = 9600 相同，否則序列埠輸出可能會變成亂碼。

編譯、燒錄與查看輸出

PlatformIO 工具列

VS Code 底部狀態列提供常用操作。將滑鼠停在圖示上可查看名稱：

也可以從左側 PlatformIO 圖示進入「Project Tasks」，在目前環境下選擇 Build、Upload、Clean 或 Monitor。

1. 編譯程式

先執行「Build」。終端機最後出現 SUCCESS 代表編譯完成；若顯示 FAILED，向上查看第一個錯誤訊息。

2. 燒錄程式

1. 使用 USB 線連接開發板。
2. 關閉其他正在占用序列埠的程式。
3. 執行「Upload」。
4. 終端機最後出現 SUCCESS 代表燒錄完成。

PlatformIO 預設會自動偵測可用的序列埠。若偵測不到，先檢查 USB 線、驅動、板型與序列埠是否被其他程式占用。

3. 開啟 Serial Monitor

燒錄成功後執行「Serial Monitor」，應每秒看到一次：

LED ON
LED OFF

若同時接了多塊開發板，或自動偵測到錯誤的序列埠，可以在 platformio.ini 指定連接埠：

upload_port = COM5
monitor_port = COM5

COM 編號可能在更換 USB 插孔後改變，因此只有必要時才建議固定設定。

常用 PlatformIO CLI 指令

從 PlatformIO 工具列開啟 Core CLI 後，可以使用：

# 列出目前偵測到的裝置
pio device list

# 編譯
pio run

# 編譯並燒錄
pio run --target upload

# 開啟序列埠監控器
pio device monitor --baud 9600

# 清除編譯產物
pio run --target clean

CLI 與畫面上的 Build、Upload、Monitor 功能相同，也很適合用來確認詳細錯誤。

安裝第三方函式庫

建議將函式庫寫入 platformio.ini 的 lib_deps，換到其他電腦時 PlatformIO 也能自動安裝相同依賴。

[env:uno]
platform = atmelavr
board = uno
framework = arduino
monitor_speed = 9600

lib_deps =
  adafruit/Adafruit Unified Sensor

儲存後重新 Build，PlatformIO 會下載函式庫。若同名函式庫很多，建議從 PlatformIO Registry 複製完整的擁有者與套件名稱。

改用 ESP32 時要注意什麼

流程與 Arduino Uno 相同，但建立專案時要選擇實際的 ESP32 板型，不要沿用 Uno 設定。常見的通用 ESP32 Dev Module 設定如下：

[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200

同樣是 ESP32，仍可能使用不同的 USB 晶片、Flash 大小、燒錄模式與腳位配置。請以板子上的型號與 PlatformIO Boards 搜尋結果為準。

部分 ESP32 板在自動燒錄失敗時，需要按住 BOOT、開始 Upload，待終端機出現連線提示後再放開；是否需要這個操作取決於開發板的自動燒錄電路。

常見問題排查

電腦找不到 COM Port

1. 確認 USB 線支援資料傳輸。
2. 換一個 USB 插孔，避免先經過 USB Hub。
3. 查看裝置管理員是否出現未知裝置或黃色驚嘆號。
4. 安裝與 USB 晶片相符的 CH340、CP210x 等驅動。
5. 在 PlatformIO Core CLI 執行 pio device list。

could not open port 或 Access is denied

序列埠通常正被其他程式占用。關閉 Arduino IDE 的 Serial Monitor、其他序列埠工具，以及 PlatformIO 已開啟的 Monitor，再重新 Upload。

avrdude: stk500_recv(): programmer is not responding

• Board 與 Upload Port 是否選對。
• 是否有電路接在 Uno 的 D0（RX）與 D1（TX）干擾通訊。
• 板子的 bootloader 是否正常。
• 若使用 Arduino Nano 相容板，處理器或 bootloader 設定是否相符。

Failed to connect to ESP32

• 確認 ESP32 板型與 COM Port 正確。
• 拔除可能影響啟動模式的外接電路。
• 嘗試在燒錄連線階段按住 BOOT，成功連線後再放開。
• 某些板子燒錄後要按一次 EN 或 RESET。

Arduino.h: No such file or directory

• 程式應放在 src/main.cpp。
• platformio.ini 內必須有 framework = arduino。
• 確認專案建立與套件下載已完成。
• 可執行 PlatformIO: Rebuild C/C++ Project Index 更新程式碼索引。

Serial Monitor 顯示亂碼或沒有輸出

• Serial.begin(...) 與 monitor_speed 必須一致。
• 確認 Monitor 開啟的是正確 COM Port。
• 某些板子開啟 Monitor 後會自動重置，請等待幾秒。
• 確認程式有執行到 Serial.begin() 與輸出指令。

修改程式後像是沒有更新

先執行「Clean」，再重新 Build。若問題仍存在，檢查目前選用的 Project Environment 是否正確，以及 platformio.ini 是否有多個 [env:...]。

完成檢查表

• PlatformIO IDE 已安裝且左側有 PlatformIO 圖示
• 裝置管理員能看到開發板的 COM Port
• Board 與 Framework 選擇正確
• Arduino 程式已加入 #include <Arduino.h>
• Build 最後顯示 SUCCESS
• Upload 最後顯示 SUCCESS
• Serial.begin() 與 monitor_speed 使用相同鮑率
• Serial Monitor 能看到預期輸出

延伸閱讀

• PlatformIO IDE for VS Code 官方文件
• Arduino Uno 的 PlatformIO 板型設定
• PlatformIO Boards 清單
• upload_port 設定說明
• PlatformIO Library Dependency Finder