ESPHome 完整上手指南：30 分钟用 ESP8266 从 0 到 1 做出温湿度采集节点-平芜编程栈

ESPHome 完整上手指南：30 分钟用 ESP8266 从 0 到 1 做出温湿度采集节点

【免费下载链接】esphomeESPHome is a system to control your ESP32, ESP8266, BK72xx, RP2040 by simple yet powerful configuration files and control them remotely through Home Automation systems.项目地址: https://gitcode.com/GitHub_Trending/es/esphome

ESPHome 是一套把 YAML 配置文件直接编译成固件并烧进开发板的系统。对第一次碰 ESP8266 的人来说，它省掉的是最烦的三件事：装工具链、写底层驱动、手动管理构建脚本。设备行为全部用配置文件描述，C++ 代码由它自动生成。这篇文章按「先看结果、再装环境、写配置、烧固件、加传感器、远程监控、本地自动化」的顺序，带你完整走一遍。

成品效果：这个节点最终能干什么

动手之前，先把目标摆出来。跟着做完全文，你手里会有一块能跑这三件事的 ESP8266：

每 60 秒把 DHT22 的温度、湿度读数推送到 Home Assistant；
温度超过 30°C 时，D1 引脚上的蜂鸣器本地鸣响 5 秒，断网也能触发；
之后升级固件走 WiFi 的 OTA 通道，不再插 USB 线。

准备工作：安装 ESPHome 并确认环境

ESPHome 本身是命令行工具，官方推荐的用法是从源码环境里跑。

从源码安装

获取代码并初始化环境，只需要三条命令：

git clone https://gitcode.com/GitHub_Trending/es/esphome cd esphome ./script/setup

⚙️ 初始化脚本 script/setup 会替你完成：创建 Python 虚拟环境、装依赖、配置 pre-commit 钩子、拉取 PlatformIO 编译工具链。

确认安装成功

source venv/bin/activate esphome version

输出里出现版本号，说明环境就绪，可以开始写设备。

写第一份配置：YAML 字段逐项拆解

用向导生成骨架

esphome wizard my_esp8266.yaml

向导按顺序提问：设备名称、芯片平台、开发板型号、WiFi 凭据、访问密码，最后替你落盘一份能直接编译的文件。

更想手写的话

整个文件的骨架只有几个小节。平台与网络部分：

esphome: name: my_esp8266 esp8266: board: nodemcuv2 logger: wifi: ssid: "你的网络名" password: "你的WiFi密码" ap: ssid: "备用热点名" password: "备用热点密码"

再加上两个受密码保护的服务和一个兜底页面：

api: password: "API访问密码" ota: password: "OTA升级密码" captive_portal:

小节	承担的职责	细节提醒
esphome	设备身份，`name`即设备域名	`friendly_name`是可选的昵称
esp8266	声明平台与开发板	`nodemcuv2`对应常见 NodeMCU 开发板
logger	打开串口日志	留空即可，无需参数
wifi	WiFi 凭据	`ap`是连不上网时自动开的备用热点
api / ota	Home Assistant 接入与远程升级	两处密码各自独立
captive_portal	备用热点的捕获页面	手机连上热点后方便拿到 SSID

编译与烧录的完整命令

先只编译、不烧录

esphome compile my_esp8266.yaml

这条命令按顺序做三件事：校验 YAML、生成 C++ 源码、产出固件文件。报错基本都出在配置层面，先在这里把它消掉。

编译、烧录一次到位

用 USB 线把开发板接上电脑，然后执行：

esphome run my_esp8266.yaml

run 会先编译，随后自动发现接在电脑上的板子，让你确认串口，再写入固件并回报结果。之后每次改动配置再烧录，它只重建有变化的部分，明显快于第一次。

接入 DHT22：接线对照与配置片段

DHT22 接线对照表

传感器引脚	ESP8266 引脚	作用
VCC	3.3V	供电
GND	GND	共地
DATA	D4（即 GPIO2）	单总线数据

配置里加传感器

给温度通道一个稳定的id，后面的自动化才能引用它：

sensor: - platform: dht pin: D4 temperature: name: "室内温度" id: indoor_temp humidity: name: "室内湿度" update_interval: 60s

dht平台默认覆盖 DHT22 这一类传感器，DHT11 也可通过model字段指定。保存后重新执行 run 命令烧录，Home Assistant 里就能看到温湿度两个实体。

远程监控与排查问题

接入 Home Assistant

在 Home Assistant 中进入「设置 > 设备与服务 > 集成」；
添加 ESPHome 集成，填入my_esp8266.local之类的域名；
用配置里 api 小节的密码完成配对，设备卡片和传感器实体随即出现在列表中。

打开内置 Web 服务器（可选）

不想依赖 Home Assistant 时，给配置追加两行：

web_server: port: 80

烧录后用浏览器打开板子 IP，同样能查看状态。

查看设备实时日志

esphome logs my_esp8266.yaml

🔍 启动过程、读数刷新、报错信息都在这里。出了问题先看日志，再动手改配置。

常见故障排查表

现象	排查方向
连不上网	核对 SSID 与密码；确认网络处于 2.4 GHz 频段，这颗芯片连不了 5 GHz；必要时在`wifi`小节调整`reboot_timeout`的等待时长
OTA 升级失败	两端是否同一网络、密码是否正确；闪存吃紧时精简配置减小固件体积
读数异常	核对接线、传感器型号与平台是否匹配；把采样间隔拉长，降低干扰

进阶玩法：本地自动化与更多组件

温度过高时本地触发蜂鸣器

自动化逻辑跑在设备内部，不依赖任何外部系统：

binary_sensor: - platform: template name: "高温警报" id: high_temp_alert state: |- return id(indoor_temp).state > 30; switch: - platform: gpio name: "警报蜂鸣器" pin: D1 id: alarm_buzzer automation: - trigger: platform: state entity_id: binary_sensor.high_temp_alert to: "on" action: - switch.turn_on: alarm_buzzer - delay: 5s - switch.turn_off: alarm_buzzer

整条链路是闭环的：模板传感器持续比对温度值，超过 30°C 时状态翻成 on，自动化随即打开蜂鸣器，等 5 秒后关闭，然后回到常态监控。