企业官网建设流程全解析

ESPHome 2026.10 这个版本，最让我兴奋的其实是那个从实验性组件转正的 Wi-Fi 人体检测功能。简单说，你手头那块吃灰很久的 ESP32 老开发板，不用外接毫米波雷达，不用焊 PIR 红外模块，刷个新固件就能把“房间里有没有人”这个问题直接交给 Wi-Fi 信号来判断。我这一周把书房、卫生间、客厅各放了一块旧板子实测，从配置到调参踩了不少坑，也摸索出一套相对稳定的参数组合。这篇文章就聊聊我对这个新版本的理解、配置细节，以及一些常规文档里不会写的排查经验，给正打算把手头老设备利用起来的人一个参考。

1. 为什么一个大版本更新把“用 Wi-Fi 检测人体”做成了主角

1.1 人体存在检测的老方案有多贵/多麻烦

先说一个很现实的问题：在这之前，想在智能家居系统里实现“人体存在检测”，主流方案就两条路。一条是 PIR 红外，模块确实便宜，几块钱就能买到，但它只能检测“动”。人只要坐在沙发上看手机超过十几秒，PIR 就认为房间没人了，灯光自动关闭，体验非常割裂。另一条是毫米波雷达，能检测微动、呼吸，甚至能区分静止的人，效果确实好，但模块加运费动辄三四十块起步，还得考虑供电、接线、安装角度、天线遮挡一系列问题。

我家里已经部署了七八块 ESP32 做温湿度采集、门窗磁、灯带控制，线路和位置都定死了。为一个人体检测再单独加一块毫米波雷达模块，成本倒不是花不起，关键是改造麻烦。所以当听说 ESPHome 新版把 Wi-Fi 人体检测做成官方组件时，我第一反应是：这方向对了。用现有设备、现有供电、现有 Wi-Fi 环境，省掉一切硬件开销，这才是老设备用户真正需要的功能。

1.2 从 RSSI 到 CSI：Wi-Fi 信号里藏着人的“指纹”

这里得稍微解释一下原理，不然调参的时候你会很懵。Wi-Fi 信号在室内传播时，并不是直直地从路由器打到设备上，它会经过墙壁反射、家具散射、人体吸收，最后到达接收端的是无数条路径叠加后的结果。传统 RSSI 只能告诉你“总信号强度”这个数值，人在房间里走动引起的强度变化非常微弱，容易被距离、天线朝向、蓝牙干扰这些因素淹没，所以靠 RSSI 检测人体，误差大到没法用。

而 CSI，也就是信道状态信息，记录的是每个子载波在频域上的幅值和相位。你可以把它理解成对房间拍了一张“多径快照”：人站在哪个位置，呼吸时胸腔起伏，抬手时手臂移动，都会让特定子载波的相位和幅值发生变化。ESP32 系列本身具备采集 CSI 的能力，之前只是没有框架把这些数据包装成好用的传感器接口。这次 ESPHome 把 CSI 转正为核心组件，数据采集、特征提取、阈值判断全在固件里完成，用户只需要在 YAML 里写几行配置，就能得到一个标准的人体存在 binary_sensor。

1.3 为什么说“老设备原地起飞”

我手头这块 ESP32 是几年前买的经典款，双核 240MHz，没有蓝牙 5.0，也没有任何 AI 加速模块，按说实时跑 CSI 分析是有点吃力的。但实际体验下来，ESPHome 把 CSI 处理流水线做得相当克制，CPU 占用在合理范围内，人体状态上报延迟在几秒级，完全够用于存在检测这种场景。

更关键的是，这套功能对硬件零要求：不需要额外传感器，不需要改接线，甚至不需要换天线。原本被各种“新功能只支持新芯片”规则劝退的老开发板，升级固件后一夜之间多了一项过去必须掏钱买模块才能实现的能力。这就是“原地起飞”的意思——硬件没变，能力边界变了。

2. 动手前先搞懂：CSI 人体检测组件在 ESPHome 里怎么工作

2.1 配置入口和组件架构

升级到 2026.10 后，新组件并不是单独一个sensor:就完事，它分成两个部分协同工作。第一部分是esp32_csi:，负责初始化 Wi-Fi 信道状态信息采集，相当于传感器的“硬件驱动层”；第二部分是binary_sensor:里的platform: esp32_csi，负责把采集到的 CSI 统计特征换算成有人/无人状态，相当于“应用层”。

我实测用的最小配置块长这样：

esp32: board: esp32dev framework: type: arduino esp32_csi: channel: 6 ht: true binary_sensor: - platform: esp32_csi name: "书房人体存在" device_class: occupancy

这块配置跑起来之后，ESPHome 日志里会周期性打印 CSI 数据包数量。如果这个数值在持续增长，说明采集链路已经通了。然后binary_sensor会在检测到 CSI 特征变化时切换状态，默认的判定逻辑是“特征变化幅度超过阈值就认为有人”。

2.2 关键参数解读：信道、HT 模式、阈值、窗口

新组件给了不少可调参数，但真正影响效果的其实就那么几个。

第一个是信道。CSI 分析需要一个稳定的参考信号，建议把channel固定下来，和你的无线路由器保持一致更好。为什么？如果信道跳来跳去，CSI 的统计基线会不断重建，人即使站着不动也可能被误判为“动态”。我一开始没设固定信道，结果一个晚上触发了二十多次误报，后来锁在路由器的信道上，问题立刻缓解。

第二个是 HT 模式。简单理解就是 Wi-Fi 带宽：ht: false对应 20MHz，ht: true对应 40MHz。带宽越宽，可分析的子载波越多，灵敏度越高，但受同频干扰的影响也越大。我的测试结论是：家庭环境首选ht: true，但如果你家附近 Wi-Fi 热点密集，降回false能减少随机误报。

第三个是最关键的“动作阈值”。它决定 CSI 特征变化要多大才会触发“有人”状态。数值越小越灵敏，细微动作就能触发，但误报率直线上升；数值越大越保守，只有明显移动才触发，但漏报风险增加。我后面会给几组实测组合，这里先记住一个原则：阈值不是调出来的，是配合你所在房间的活动特点试出来的。

第四个是扫描间隔和滑动窗口。scan_interval控制多久采集一次 CSI 快照，window_size控制用多少个快照做统计平滑。这两个参数直接影响延迟：窗口越大越平滑，但有人进屋后状态翻转会更慢；窗口太小则容易出现瞬间抖动造成误判。

2.3 部署位置与传感器布局对效果的影响

这是所有参数里最容易被忽略、但影响最大的一项。Wi-Fi 人体检测的本质是通过环境电磁变化反推人的位置，所以设备放哪里，决定了它能“看见”多少空间。

我总结了几条实测规律。设备最好放在房间对角线的一侧，天线朝向房间主体空间，离地面 80cm 到 1m 左右，相当于家具的中间高度，人体躯干活动最容易被捕捉到。放在桌面边缘且周围没有遮挡时，覆盖一个 10 平米的卧室没问题。但如果塞到桌子下面、被金属收纳箱挡住，信号路径被固定住，人从旁边走过去 CSI 变化很小，基本等于白装。还有一种情况，设备离路由器不到 1 米，人从它们之间走过时多径变化极小，检测几乎无反应，这时候需要把设备挪到离路由器至少两三米的位置。

3. 老 ESP32 刷上 ESPHome 2026.10，接入人体存在传感器全流程

3.1 升级固件前的备份与兼容检查

动手之前先把备份做好，这是我不止一次吃过亏后的习惯。ESPHome 升级一般不会丢配置，但大版本更新偶尔会改默认行为，比如某些传感器的参数名变了，或者新固件对老芯片存储器布局有调整。我的做法是：先把当前设备的 YAML 和secrets.yaml复制一份到本地，然后到 ESPHome Dashboard 里点升级。

升级后第一次编译可能会提示旧组件与新组件冲突，比如你之前手动配置过某些实验性 CSI 相关的自定义组件，新版本转正后会跟它抢资源。遇到这种情况不用慌，在 YAML 里把自定义组件的相关段落删掉，保留官方组件即可。我这次就清理了一段两年前从社区抄来的 CSI 实验配置，删掉后编译时间反而缩短了。

3.2 最小可用配置：5 分钟跑通 Wi-Fi 人体检测

如果你只是想先跑通，别急着调参，用下面这份配置直接刷，大概率能出效果。

esp32: board: esp32dev framework: type: arduino logger: level: DEBUG wifi: ssid: !secret wifi_ssid password: !secret wifi_password channel: 6 esp32_csi: channel: 6 ht: true scan_interval: 2s window_size: 10 threshold: 75 binary_sensor: - platform: esp32_csi name: "书房人体存在" device_class: occupancy filters: - delayed_on: 5s - delayed_off: 60s

逐个说明我为什么这样写。wifi里强制指定channel: 6，是为了和esp32_csi的信道保持一致，避免设备与路由器反复协商信道导致 CSI 基线不稳。scan_interval: 2s是扫描间隔，window_size: 10表示用最近 10 次快照做统计，相当于 20 秒的滑动窗口。threshold: 75是动作阈值，先给个中庸值，后面再调。

filters里的两个延迟很关键：delayed_on: 5s表示 CSI 特征变化持续 5 秒后才把状态翻转为“有人”，防止瞬间干扰造成闪变；delayed_off: 60s表示状态进入“无人”前必须保持 60 秒的无人特征，避免人静止不动时被误判为离开。

刷完固件后，观察日志，正常会看到类似CSI: packets=123, threshold=75的输出。然后走进房间，手机打开 HA 的传感器页面，等 5 秒左右，状态应变“有人”。再走出门，等 60 秒左右，状态变回“无人”。

3.3 调参进阶：减少误报与漏报的实测组合

跑通之后就是调优阶段。这一周我分别在书房、卫生间、客厅做了三组测试，环境和活动特点不同，最优参数完全不同。我整理成一张表，你可以直接用。

为什么会这样？卫生间需要高灵敏度和快速响应，所以阈值调低、窗口调小；书房需要抑制“人静止但被判定为无人”的漏报，所以把延迟关闭拉到 60 秒，让状态翻转更保守；客厅活动复杂，随便一个动作变化都很明显，阈值调高反而能过滤掉微动干扰。

这里有个容易被忽略的联动细节：delayed_off设得越长，灯光自动化熄灭就越晚，但也越不容易误关。如果你习惯人走灯灭，又不介意多亮一分钟，把delayed_off设成 90 秒甚至 120 秒，体验会好很多。

4. 常见问题与排查技巧实录

4.1 日志里看不到任何 CSI 变化怎么排查

如果你刷完固件，日志里一直没有任何 CSI 相关的输出，先别急着怀疑组件坏了。我遇到过三次，原因各不相同。

第一次是因为 ESP32 固件里开了省电模式，Wi-Fi 接收窗口不稳定导致 CSI 采集失败。在 YAML 的wifi:段里加一行power_save_mode: none，重启后问题解决。第二次是设备跑在 AP 模式下，CSI 组件依赖 STA 模式的数据链路，改成连接路由器后就正常了。第三次最隐蔽，我手头那块老板子的天线虚焊，信号太弱，换了一块板子后 CSI 包数量立刻上来了。

排查顺序建议是：先看日志里有没有ESP32-CSI字样，没有就检查供电和天线；有数据但不触发状态翻转，再检查信道一致性和阈值设置。

4.2 有人但一直报“无人”是怎么回事

这种情况最常见的诱因是“基线校准”问题。CSI 组件上电后，会默认把当前环境当成无人基线。如果你在刷机后的前几分钟就有人待在房间里，组件可能把“有人”的状态也纳入了基线统计，之后人不动了，它反而认为环境没变化，输出无人。

解决办法很简单：刷完固件后，让房间保持完全无人状态至少两分钟，让组件建立干净的空环境基线。我每次调整参数后也会刻意等两分钟再进房间测试，效果稳定很多。还有人静止坐在设备正下方 30cm 内的位置，人体几乎贴住天线，多径变化反而消失。这种物理遮挡问题只能通过调整部署位置解决。

4.3 误报频繁、设备重启如何解决

误报的来源通常不是人体，而是房间里其他周期性工作的电器。空调风机启动、加湿器雾气喷出、鱼缸水泵运转，都会让室内多径环境发生规律性变化，CSI 统计特征就会被带偏。

我书房的空调一开，误报次数明显增加。后来把threshold从 75 提到 90，配合delayed_on延长到 10 秒，基本压住了。如果还不行，可以考虑在 HA 自动化里增加“传感器在设备运行期间不触发灯光”的条件，比如通过功率插座判断空调是否在工作，在自动化里做一层逻辑过滤。

另一个可能导致误报甚至重启的原因在供电。ESP32 用劣质 USB 电源时电流不足，Wi-Fi 发射功率一上去电压就掉，CSI 数据会剧烈抖动。这个不好直接看出来，建议换一个标称 2A 以上的电源再观察。我实测换电源后，误报率至少降了一半。

4.4 和其他传感器联动时的两个坑

如果你家里原来就有 PIR 传感器，新加 CSI 人体检测后别急着让它们同时控制同一个自动化。PIR 的缺点是“人静即灭”，CSI 的优点是“静默也能检测存在”，两者冲突时应该以 CSI 为准，PIR 只在 CSI 不可达的角落做辅助。我一开始直接让两个传感器“或”逻辑触发开灯，结果人在书房刷手机超过半分钟，PIR 关灯，CSI 又立刻开灯，灯光反复横跳，体验非常糟糕。后来改成“CSI 优先，PIR 仅在 CSI 状态为无人且检测到移动时提示”，才算干净。

还有一个坑是多个 ESP32 同时跑 CSI 检测同一个房间。如果两台设备信道相同且扫描时序不同步，它们的 Wi-Fi 发射可能互相干扰，导致 CSI 数据异常。我的建议是同一区域只保留一台主检测设备，或者把两台设备设到不同信道，中间用 HA 做结果汇总，别让它们直接抢信号。

最后说点个人体会。这套 Wi-Fi 人体检测不会取代毫米波雷达，它测不到呼吸级别微动，也无法和雷达那样输出距离信息。但对“人在不在房间”这个高频需求来说，它的性价比无敌：不用加硬件，不用改布线，把吃灰的老 ESP32 刷个固件就能用。如果你家里正好有旧板子，强烈建议先拿一台试试，固定信道、调好阈值、放对位置，效果会比你预期的更接近毫米波方案。