读到一个 ADC 数字，只能说明转换器输出了原始计数。电压需要量程、参考与校准信息。
本文使用经典 ESP32、ESP-IDF v2.1 与隔离低压演示电路。ESP-IDF（乐鑫开发框架）版本会改变接口与工具链。本文固定早期开发环境，GPIO 编号、电压和外设复用按具体开发板原理图核对，不把板子排针顺序当芯片引脚编号。
1. 从现象推到机制
衰减配置影响可测输入范围，器件差异与非线性会影响换算。经典 ESP32 的 ADC1 与 ADC2 在无线使用条件下也有不同约束。不能用一个理想满量程公式宣称所有板子精确。
图中的四个节点分别表示模拟输入、ADC 配置、原始计数、多点校验。顺着实线检查输入如何变成输出，再沿虚线核对反馈条件。图示表达的是本文讨论的关系，不是实测曲线或现场截图。
2. 最小实现与输入条件
选择板上可确认的 ADC1 输入，使用额定范围内的多个已知低压点比较。v2.1 的旧接口名为 adc1_get_voltage，但返回的是原始转换计数，不是已经校准的毫伏值。保留外部测量，不输入超出芯片限制的电压。
1
2
3
4
adc1_config_width(ADC_WIDTH_12Bit);
adc1_config_channel_atten(ADC1_CHANNEL_6, ADC_ATTEN_11db);
int raw = adc1_get_voltage(ADC1_CHANNEL_6);
// v2.1 旧 API 返回原始计数；通道与板上引脚另核对
先检查供电与串口，再在独立工程验证。仅使用额定范围内的低压信号，输入不能因为“只是测试”越过芯片限制；烧录成功与外设运行需要分别记录。
3. 用对照区分原因
下表列出需要主动改变的条件。预期行为来自机制分析，复现时还需记录运行环境和原始输出，不能将预期当作已经测得的结果。
| 改变的条件 | 需要验证的行为 |
|---|---|
| 同一输入在不同板上读数不同 | 需要考虑个体与参考差异 |
| 调整衰减配置 | 换算条件也随之改变 |
| 单点看起来接近 | 不能证明全范围线性与精度 |
对照 1：同一输入在不同板上读数不同
需要考虑个体与参考差异。观察时记录外部测量和原始计数。把这个条件与基准情形分开，有助于判断变化来自哪一层；若得到相反结果，应先核对前提，再修改实现。
对照 2：调整衰减配置
换算条件也随之改变。观察时记录生效配置与输入范围。把这个条件与基准情形分开，有助于判断变化来自哪一层；若得到相反结果，应先核对前提，再修改实现。
对照 3：单点看起来接近
不能证明全范围线性与精度。观察时记录多个已知点的误差分布。把这个条件与基准情形分开，有助于判断变化来自哪一层；若得到相反结果，应先核对前提，再修改实现。
4. 适用条件与取舍
平均滤波只能减少部分随机波动，不会消除比例误差与非线性。应用显示应保留合理精度和质量状态。
一次正常运行只覆盖了这组输入。继续扩展前，应把上面的异常对照保留下来，尤其关注“单点看起来接近”这一分支。后续方案若改变了图中任意一处依赖，原来的判断就要重新验证，不能仅凭界面相似或返回值相同沿用结论。
