构建配置
源码构建入口是 platformio.ini。系统只维护一个固件产品；发布环境共享 [esp32_base] 和 [unified_flags]，按芯片覆盖分区、PSRAM、OTA 和运行时参数。上述配置段只复用编译参数，不是产品版本，不需要为配置按需启停另建固件档位。
环境矩阵
| 环境 | 芯片 | Flash | PSRAM | 分区表 | OTA |
|---|---|---|---|---|---|
esp32-F4R0 | ESP32 | 4MB | 无 | partitions/4MB.csv | 否 |
esp32-F8R0 | ESP32 | 8MB | 无 | partitions/8MB.csv | 是 |
esp32-F8R8 | ESP32 | 8MB | 8MB | partitions/8MB.csv | 是 |
esp32c3-F4R0 | ESP32-C3 | 4MB | 无 | partitions/4MB.csv | 否 |
esp32c6-F4R0 | ESP32-C6 | 4MB | 无 | partitions/4MB.csv | 否 |
esp32c6-F8R0 | ESP32-C6 | 8MB | 无 | partitions/8MB.csv | 是 |
esp32s3-F8R0 | ESP32-S3 | 8MB | 无 | partitions/8MB.csv | 是 |
esp32s3-F8R8 | ESP32-S3 | 8MB | 8MB | partitions/8MB.csv | 是 |
esp32s3-F16R8 | ESP32-S3 | 16MB | 8MB | partitions/16MB.csv | 是 |
native | 主机 | - | - | - | - |
9 个 ESP32 环境均属于发布矩阵；发布清单见设备文档 fim/manifest.json。标准命名不再使用 F8R4，R0 表示无 PSRAM，R8 表示 8MB PSRAM。
配置层次
[esp32_base] 平台、Arduino、LittleFS、公共库和基础宏
|
[unified_flags] 统一功能编译开关
|
[芯片 runtime] TCP 连接数、队列和任务栈
|
[env:<name>] board、分区、PSRAM、OTA 和库覆盖基础配置使用 partitions/4MB.csv、8MB.csv、16MB.csv 三套分区表；文件系统类型为 LittleFS（CSV 中的 spiffs 标签是 Arduino-ESP32 的兼容命名）。
统一功能开关
unified_flags 提供公共编译开关基线，目标硬件覆盖后的最终能力才决定哪些功能代码进入镜像；不能表述为所有芯片全量编入所有功能。设备屏幕只面向 ESP32-S3。RuntimeFeatureManager 从 /config/features.json 加载用户覆盖，FeatureBudget 再按 DRAM 水位决定是否允许初始化；已编译不代表默认启用，未编译也不能仅修改配置就启用。
| 类别 | 代表宏 | 运行时默认 |
|---|---|---|
| 核心 Web | WEB_SERVER、WEB_STATIC、WEB_API、AUTH、SESSION | 开启 |
| 基础能力 | MQTT、GPIO、PERIPH_EXEC、HEALTH_MONITOR、LOGGER | 编译启用，按页面/配置使用 |
| 外设 | SENSOR_DRIVER、DS18B20、LCD、NEOPIXEL、I2C_SENSORS、RFID 等 | 关闭，按需开启 |
| 自动化 | RULE_SCRIPT、COMMAND_SCRIPT | 关闭；命令脚本与规则脚本强制组合 |
| 运维 | LOG_VIEWER、FILE_LOGGING、CONFIG_TRANSFER、USER_ADMIN | 关闭或按构建宏决定 |
| 网络扩展 | ETHERNET、CELLULAR、BLE | 关闭；需外部硬件 |
环境级覆盖
| 覆盖 | 环境 | 原因 |
|---|---|---|
FASTBEE_ENABLE_OTA=0、OTA_FS=0 | 4MB 环境 | 单 app 分区，没有 ota_1 |
FASTBEE_ENABLE_SCREEN_PANEL=0、SCREEN_UI=0 | 非 ESP32-S3 目标 | 设备屏幕当前仅面向 S3 |
FASTBEE_ENABLE_IR_REMOTE=0、RF_LEARN=0 | esp32s3-F8R8 | 与 S3 RMT/库组合存在冲突 |
FASTBEE_ENABLE_IR_REMOTE=1、RF_LEARN=1 | esp32-F8R8、esp32s3-F16R8 | 具备对应依赖和资源 |
修改开关时必须同时考虑库依赖、分区大小、Web 页面资源和内存预算；不要仅修改前端菜单隐藏功能。
运行时资源参数
| 宏 | ESP32 F8x / F4R0 | C3 | C6 | S3 |
|---|---|---|---|---|
CONFIG_ASYNC_TCP_MAX_CONNECTIONS | 6 / 4 | 4 | 6 | 8 |
CONFIG_ASYNC_TCP_QUEUE_SIZE | 32 / 8 | 4 | 8 | 24 |
ARDUINO_LOOP_STACK_SIZE | 16384 / 12288 | 12288 | 12288 | 16384 |
SCRIPT_TASK_STACK | 8192 / 6144 | 6144 | 6144 | 8192 |
SIMPLE_TASK_STACK | 6144 / 4096 | 4096 | 4096 | 6144 |
ARDUINO_USB_CDC_ON_BOOT | - | 1 | 0 | 1 |
上表是PlatformIO配置宏，不是最终任务实例测量。当前 src/main.cpp 强覆盖loopTask栈为24KiB；Worker最低栈无PSRAM8192字节、有PSRAM12288字节，并与 SIMPLE_TASK_STACK 取较大值。Worker数量和实际初始化还受芯片、需求及预算控制。
提高连接数与队列会增加内部DRAM成本，不能据此保证吞吐提升。遇到 503 或内存预算拒绝时，先减少并发和重型功能，再调整这些参数。
OTA 策略
- 4MB：
FASTBEE_ENABLE_OTA=0，OTA 路由不注册，使用串口/在线工具重新烧录合并固件。 - 8MB/16MB：有
app0/app1，FASTBEE_ENABLE_OTA=1；固件必须小于 app 分区，开始升级前还要通过内存门控。 - 构建/发布可生成固件、LittleFS和合并镜像，但当前没有独立文件系统OTA writer。旧
FASTBEE_ENABLE_OTA_FS宏和配置键保留兼容，不能据其值承诺在线更新Web文件系统；开发候选对otaFs返回未实现。LittleFS写入应使用明确保全现场配置的部署流程，不能用普通应用OTA成功推断文件系统也已更新。
常用命令
# 仅构建（不操作设备）
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/deploy.ps1 -Env esp32s3-F8R8 -BuildOnly
# 固件及LittleFS定向构建
npm run test:firmware -- esp32s3-F8R8
# Native测试
npm run test:native
# 校验环境、分区和 OTA 矩阵
node scripts/validate-build-matrix.js同一工作区构建、Host/Native测试和Web资源生成须用 scripts/firmware-build-lock.ps1 串行协调；直接Host测试或Web构建需在外层获取锁。不建议直接把 data/www 当发布源。发布 Web 资源应由 deploy.ps1/gzip-www.js 生成 staging 目录，避免旧的 .gz 文件和页面残留。
自定义环境检查
- 明确芯片、Flash、PSRAM 和外部模块。
- 选择匹配的
partitions/*.csv；需要 OTA 时必须存在app1。 - 设置对应
FASTBEE_USE_PSRAM、OTA 和网络适配器宏。 - 运行
validate-build-matrix.js，再进行固件、LittleFS、登录和/api/health冒烟测试。 - 记录实际构建环境和镜像 SHA-256，避免把开发环境误当发布固件。