error-message-explainer

错误信息解读器

将晦涩的编译器错误转化为针对 Arduino/ESP32/RP2040 项目的可操作修复方案。

资源

本技能包含以下捆绑工具：

• scripts/parse_errors.py - 自动化错误分析，内置 20+ 种错误模式
• ../../docs/board-support/uno-r4-family.md - Uno R4 板卡系列的共有注意事项

快速开始

从文件分析错误：

uv run --no-project scripts/parse_errors.py --file error_log.txt

分析单条错误：

uv run --no-project scripts/parse_errors.py --message "error: 'LED' was not declared in this scope"

交互模式：

uv run --no-project scripts/parse_errors.py --interactive

从编译器管道输入：

arduino-cli compile 2>&1 | uv run --no-project scripts/parse_errors.py --stdin

如何使用本技能

当用户粘贴错误信息时：

1. 从下方模式中识别错误类型
2. 用通俗的语言解释其含义
3. 展示具体的修复方法及代码示例
4. 解释该错误为何发生（教育价值）
5. 如果目标是 Uno R4 系列，且故障涉及 WiFi、OTA、USB 或板卡识别，请打开 ../../docs/board-support/uno-r4-family.md

恢复边界

在建议执行重置、擦除、bootloader 修复或重新刷写之前，请先记录确切的板卡/版本、工具与库版本、端口、供电路径以及最后一个已知正常的镜像。对于上传失败、启动失败、电源故障或固件损坏，请使用路由器恢复参考。不要把编译修复称为硬件或系统修复。

常见编译错误

1. "'xyz' was not declared in this scope"

error: 'xyz' was not declared in this scope

含义： 编译器无法识别名称 xyz。

常见原因与修复：

原因	修复
变量/函数名拼写错误	检查拼写，C++ 区分大小写！
变量在声明前被使用	将声明移到首次使用之前
缺少 #include	添加所需的库头文件
函数在其被调用之后才定义	添加前置声明或将函数上移

示例 - 拼写错误：

// WRONG
int ledpin = 13;      // lowercase 'p'
digitalWrite(ledPin, HIGH);  // uppercase 'P' - DIFFERENT!

// CORRECT
int ledPin = 13;
digitalWrite(ledPin, HIGH);

示例 - 缺少 Include：

// WRONG - Servo not defined!
Servo myServo;

// CORRECT
#include <Servo.h>
Servo myServo;

---

2. "expected ';' before..."

error: expected ';' before 'xyz'

含义： 上一行缺少分号。

修复： 在错误行上方的那一行末尾添加 ;。

// WRONG - error points to line 3
int x = 5       // ← missing ; here!
int y = 10;

// CORRECT
int x = 5;
int y = 10;

小技巧： 报错行号是编译器发现问题的地方，而不是缺少 ; 的地方！

---

3. "expected ')' before..." 或 "expected '}' before..."

error: expected ')' before ';'
error: expected '}' at end of input

含义： 括号或花括号不匹配。

常见模式：

// WRONG - unmatched parenthesis
if (x > 5 {  // missing )
}

// WRONG - unmatched brace
void setup() {
    Serial.begin(115200);
// missing closing }

// CORRECT
if (x > 5) {
}

void setup() {
    Serial.begin(115200);
}

调试技巧： 使用 IDE 自动格式化（Ctrl+T）来发现不匹配之处。

---

4. "invalid conversion from 'const char*' to 'char*'"

error: invalid conversion from 'const char*' to 'char*'

含义： 试图修改字符串字面量（它是只读的）。

// WRONG
char* message = "Hello";  // string literals are const!
message[0] = 'h';         // can't modify!

// CORRECT (if you need to modify)
char message[] = "Hello"; // creates modifiable copy
message[0] = 'h';         // OK!

// CORRECT (if read-only is fine)
const char* message = "Hello";

---

5. "no matching function for call to..."

error: no matching function for call to 'SomeClass::method(int, int, int)'
note: candidate: void SomeClass::method(int, int)

含义： 调用函数时参数数量或类型不正确。

// WRONG - too many arguments
myServo.write(90, 100);  // write() takes only 1 argument!

// CORRECT
myServo.write(90);

阅读 "note:" 行 - 它们会显示实际接受的参数类型。

---

6. "multiple definition of 'xyz'"

error: multiple definition of 'xyz'

含义： 同一个变量/函数在多个文件中被定义。

修复：

// In header file (.h), use 'extern':
extern int globalVar;  // declaration only

// In ONE .cpp file, define it:
int globalVar = 0;     // actual definition

或者对于头文件中的函数：

// WRONG - defined in header, included multiple times
int add(int a, int b) { return a + b; }

// CORRECT - use 'inline'
inline int add(int a, int b) { return a + b; }

---

7. "'xyz' does not name a type"

error: 'WiFiClient' does not name a type

含义： 类/类型无法识别。

修复：

板卡	库	Include
ESP32	WiFi	#include <WiFi.h>
ESP8266	WiFi	#include <ESP8266WiFi.h>
Arduino + WiFi Shield	WiFi	#include <WiFi.h>

// WRONG
WiFiClient client;  // WiFiClient unknown!

// CORRECT for ESP32
#include <WiFi.h>
WiFiClient client;

---

8. "redefinition of 'xyz'"

error: redefinition of 'int x'

含义： 变量在同一作用域中被声明了两次。

// WRONG
int count = 0;
int count = 0;  // redefinition!

// WRONG in loops
for (int i = 0; i < 10; i++) {
    int i = 5;  // shadows loop variable!
}

// CORRECT
int count = 0;  // declare once
count = 5;      // assign without 'int'

---

上传错误

9. "avrdude: stk500_recv(): programmer is not responding"

avrdude: stk500_recv(): programmer is not responding
avrdude: stk500_getsync() attempt X of 10: not in sync

含义： Arduino IDE 无法与板卡通信。

修复（按顺序尝试）：

1. ✅ 是否选择了正确的板卡？（工具 → 开发板）
2. ✅ 是否选择了正确的端口？（工具 → 端口）
3. ✅ USB 线是数据线（而非仅充电线）？
4. ✅ 尝试不同的 USB 端口
5. ✅ 引脚 0/1（TX/RX）上未连接任何东西？
6. ✅ 在上传期间按下复位按钮
7. ✅ 安装/重新安装 USB 驱动

---

10. “A fatal error occurred: Failed to connect to ESP32”

A fatal error occurred: Failed to connect to ESP32: 
Timed out waiting for packet header

含义： ESP32 未进入 bootloader 模式。

修复： 上传时按住 BOOT 按钮：

1. 在 IDE 中点击 Upload
2. 当出现 “Connecting...” 时，按住 BOOT 按钮
3. 上传开始时松开
4. 某些开发板：按住 BOOT，按 EN/RST，松开 BOOT

---

11. “Sketch too big”

Sketch too big; see https://support.arduino.cc/...
Sketch uses 34816 bytes (107%) of program storage space.
Maximum is 32256 bytes.

含义： 程序无法放入 flash 存储器。

修复：

// 1. Use F() macro for strings (saves RAM + sometimes Flash)
Serial.println(F("This string in flash"));  // instead of RAM

// 2. Remove unused libraries
// Each #include adds code even if not used

// 3. Use smaller data types
uint8_t x = 5;  // instead of int (2 bytes saved)

// 4. Choose board with more flash (ESP32 has 4MB vs Arduino's 32KB)

---

库错误

12. “fatal error: xyz.h: No such file or directory”

fatal error: Adafruit_BME280.h: No such file or directory

含义： 库未安装。

修复：

1. Sketch → Include Library → Manage Libraries
2. 搜索库名称
3. 点击 Install
4. 如果 Library Manager 中没有：下载 ZIP，Sketch → Include Library → Add .ZIP Library

---

13. “exit status 1 / Error compiling for board...”

exit status 1
Error compiling for board Arduino Uno.

含义： 通用错误 - 向上滚动以找到真正的错误消息。

实际错误在这一行上面！ 查找包含 error: 的行。

---

类型错误

14. “cannot convert 'String' to 'const char*'”

error: cannot convert 'String' to 'const char*'

含义： 函数期望 C-string，但得到的是 Arduino String。

// WRONG
String myString = "hello";
someFunction(myString);  // if someFunction expects const char*

// CORRECT
String myString = "hello";
someFunction(myString.c_str());  // convert to C-string

---

15. “invalid operands to binary expression”

error: invalid operands of types 'const char*' and 'const char*' to binary 'operator+'

含义： 不能对 C-string 使用 +。

// WRONG
const char* a = "hello";
const char* b = " world";
const char* c = a + b;  // doesn't work!

// CORRECT - use String
String a = "hello";
String b = " world";
String c = a + b;  // works!

// Or use snprintf
char c[20];
snprintf(c, sizeof(c), "%s%s", a, b);

---

快速参考表

错误包含	可能的问题	快速修复
“not declared”	拼写错误或缺少 include	检查拼写，添加 #include
“expected ';'”	缺少分号	在错误行的上一行添加 ;
“expected ')'”	括号不匹配	数一数 ( 和 )
“expected '}'”	花括号不匹配	数一数 { 和 }
“no matching function”	参数错误	检查函数签名
“does not name a type”	缺少库	添加 #include
“multiple definition”	在多个文件中定义	使用 extern
“stk500”	上传失败	检查开发板/端口/线缆
“No such file”	库未安装	通过 Library Manager 安装
“too big”	flash 不足	使用 F()，删除未使用的代码

调试策略

1. 阅读第一个错误（后面的错误通常是连锁反应）
2. 记下文件和行号
3. 查看该行以及上一行
4. 检查上面列出的常见模式
5. 一次修复一个错误，重新编译
6. 重复直到没有错误

共享输出契约

使用共享 Arduino 技能契约： 说明假设、所需工具和版本、实现步骤、 按证明阶段划分的测试/证据、已知限制以及恢复/安全注意事项。