ESP8266 FSBrowser 示例深度解析基于 ESP8266WebServer 的跨文件系统 Web 文件管理器【免费下载链接】ArduinoESP8266 core for Arduino项目地址: https://gitcode.com/gh_mirrors/ard/Arduino导读本文围绕 Arduino 生态下 ESP8266 core 仓库中的FSBrowser官方示例展开完整讲解如何构建一个基于 HTTP 请求与 HTML/JavaScript 前端的文件系统浏览器FileSystem Browser它可统一运行在 SPIFFS、LittleFS 与 SDFS 三种文件系统之上。读完本文你将掌握 FSBrowser 的编译配置、文件系统烧录方法、浏览器访问与编辑流程、文件系统瘦身与内嵌页面等进阶选项并从 FSBrowser.ino 的源码出发理解其 RESTful API 设计与底层实现原理。FSBrowser 是什么FSBrowser 是一个面向 ESP8266 的 Web 文件系统浏览器示例程序ESP8266 通过 ESP8266WebServer 暴露一组 HTTP 接口浏览器端则用 HTML/JavaScript 渲染文件树、文本编辑器和图片预览从而实现对设备文件系统的浏览、编辑、上传、下载、新建、删除与重命名操作。该统一版本由早期的FSWebServer、FSBrowser和SDWebServer三个示例合并而来原始版权归 Hristo Gochkov2015其核心设计目标是同一套代码、同一个前端同时兼容 SPIFFS、LittleFS 与 SDFS 三种文件系统。示例本体位于 libraries/ESP8266WebServer/examples/FSBrowser/FSBrowser.ino随附的 readme.md 是该功能的官方使用说明本文以其为骨架展开。从源码结构看示例的文件布局如下FSBrowser.ino主程序包含文件系统初始化、Wi-Fi/MDNS 连接、HTTP 路由与全部请求处理器data/需要烧录到文件系统根目录的 Web 前端资源其中data/edit/index.htm是核心编辑器页面data/index.htm、data/favicon.ico、data/pins.png为示例内容文件extras/构建期工具与产物包括reduce_index.sh压缩/内嵌脚本、index.htm.gzgzip 压缩版页面与index_htm.h可内嵌进固件的 C 头文件。快速上手五步跑通 FSBrowser第 1 步选择文件系统打开FSBrowser.ino文件头部有三行#define宏同一时刻只能启用其中一个// #define USE_SPIFFS #define USE_LITTLEFS // #define USE_SDFS取消注释USE_SPIFFS使用 SPIFFS老式 SPI 闪存文件系统取消注释USE_LITTLEFS使用 LittleFS推荐的新式闪存文件系统取消注释USE_SDFS使用 SDFSSD 卡文件系统。如果三个宏全部注释编译会直接报错源码中显式写明了这一点FSBrowser.ino#error Please select a filesystem first by uncommenting one of the #define USE_xxx lines at the beginning of the sketch.宏的选择同时决定了编译期绑定到哪个文件系统实例。在源码中#if/#elif条件编译块会为fileSystem指针与fileSystemConfig配置对象赋值#if defined USE_SPIFFS #include FS.h const char* fsName SPIFFS; FS* fileSystem SPIFFS; SPIFFSConfig fileSystemConfig SPIFFSConfig(); #elif defined USE_LITTLEFS #include LittleFS.h const char* fsName LittleFS; FS* fileSystem LittleFS; LittleFSConfig fileSystemConfig LittleFSConfig(); #elif defined USE_SDFS #include SDFS.h const char* fsName SDFS; FS* fileSystem SDFS; SDFSConfig fileSystemConfig SDFSConfig(); #endif这种“运行时通过FS*抽象基类操作、编译期通过宏选择具体实现”的模式正是整个 FSBrowser 能一套代码兼容三种文件系统的关键也解释了 readme 中“统一版本”的由来。第 2 步填入 Wi-Fi 凭据在源码中搜索STASSID将占位符替换为你的网络信息#ifndef STASSID #define STASSID your-ssid #define STAPSK your-password #endif程序启动后会以 STA 模式连接该网络并注册 mDNS 主机名fsbrowser源码中的const char* host fsbrowser;因此浏览器可用http://fsbrowser.local访问设备。第 3 步编译并烧录固件在 Arduino IDE 中打开FSBrowser.ino选择目标 ESP8266 开发板直接编译上传即可。需要说明的是示例本身还会初始化串口调试输出115200 baud连接过程与文件系统初始化结果都会打印在串口监视器上。第 4 步向文件系统烧录 Web 前端资源固件本身不含前端页面除非启用内嵌选项见下文因此必须把data文件夹的内容写入文件系统SDFS 方案把data文件夹的内容注意不是data文件夹本身复制到一张 FAT/FAT32 格式化的 SD 卡根目录并将 SD 卡连接到 ESP8266 的 SPI 端口SPIFFS 或 LittleFS 方案使用 Arduino IDE 的 “ESP8266 Sketch Data Upload” 插件即esptool配合文件系统镜像工具将data目录作为数据镜像烧录到闪存。烧录完成后设备上应存在/edit/index.htm编辑器页面与/index.htm默认首页等文件。第 5 步在浏览器中打开编辑器确保设备与电脑在同一网络后访问http://fsbrowser.local/edit如果 mDNS 在你的网络环境中不可用也可以改用串口监视器中打印的 IP 地址例如http://192.168.x.x/edit。页面功能与前端交互设计浏览器端页面由 data/edit/index.htm 实现约 1100 行单文件 HTML/JavaScript。从脚本结构看前端主要包含三大部分文件树File Tree默认占窗口宽度 20%#tree的width: 20%以文件夹优先、字母序排列文件条目显示大小如1.23 KiB并按扩展名区分文本文件span.txt、图片文件span.img与普通文件图标。主面板Editor / Preview左侧 20% 为文件树右侧 80% 为主面板。文本文件用 Ace.js 编辑器打开图片文件用img标签内联预览其余格式显示“(file not found or format not supported)”。顶栏Header包含文件选择框、路径输入框、Upload / MkDir / MkFile 按钮、Save / Discard / Help 编辑器按钮以及右上角的文件系统状态条FS 类型、已用/总容量进度条meter。前端与后端的通信全部通过XMLHttpRequest完成请求期间页面会通过半透明遮罩#loading与旋转 spinner 提示异步操作进行中。文件树支持右键上下文菜单提供 Edit/Preview、Download、Rename/Move、Delete 等操作文本编辑器则绑定了Ctrl-S保存与Ctrl-Alt-h快捷键帮助等快捷键。前端对三种文件系统的差异化处理前端会先请求/status接口获取fsInfo包含type、isOk、totalBytes、usedBytes等字段并据此做出差异fsInfo.type ! SPIFFS时才显示 MkDir 按钮——因为 SPIFFS 没有真正的目录概念见下文限制刷新路径时SPIFFS 一律刷新整棵树无父节点概念LittleFS/SDFS 则支持逐级递归刷新。HTTP API 一览前端与后端的契约FSBrowser 的核心是一组围绕/edit的 RESTful 接口路由在 FSBrowser.ino 中注册HTTP 方法路径处理器功能GET/statushandleStatus返回 FS 类型、状态、容量 JSONGET/list?dir路径handleFileList返回目录下的文件/文件夹列表JSONGET/edithandleGetEdit返回编辑器页面index.htmPUT/edithandleFileCreate新建文件/文件夹或重命名/移动DELETE/edithandleFileDelete删除文件或文件夹递归POST/editreplyOKhandleFileUpload文件上传两个回调分别处理请求结束与分块数据其他任意 URIhandleNotFound兜底优先尝试从文件系统读文件失败返回 404 调试页前端 JavaScript 中的httpList、httpCreate、httpRename、httpDelete、httpUpload、postFile等函数与这些路由一一对应。例如新建文件发送PUT /edit且FormData中携带path重命名则额外携带src源路径上传与保存文件使用POST /edit并携带data字段。关键实现细节列表接口使用 HTTP/1.1 分块响应handleFileList为避免在内存中拼装大字符串调用了server.chunkedResponseModeStart(200, text/json)开启分块模式FSBrowser.ino。若客户端是 HTTP/1.0_currentVersion 0分块模式不可用接口会返回 505 错误。对应库实现见 ESP8266WebServer.h。文件读取自动处理目录索引与 gziphandleFileRead对以/结尾的路径自动追加index.htm若文件不存在则尝试path .gz配合extras里的 gzip 页面再通过server.streamFile(file, contentType)流式发送FSBrowser.inostreamFile的库实现见 ESP8266WebServer.h。文件上传是分阶段回调handleFileUpload依据upload.status在UPLOAD_FILE_START创建文件、UPLOAD_FILE_WRITE写入数据块并校验写入字节数、UPLOAD_FILE_END关闭文件三个状态间流转。删除文件夹是递归的带警告deleteRecursive先删除目录内所有子项再删除目录本身。源码注释明确提醒嵌入式设备上递归可能导致栈溢出崩溃此写法仅用于演示生产系统不应照搬FSBrowser.ino。URL 解码handleNotFound中对 URI 调用ESP8266WebServer::urlDecode以便正确处理含空格的路径。文件系统不自动格式化setup()中fileSystemConfig.setAutoFormat(false)后调用fileSystem-setConfig(fileSystemConfig)与fileSystem-begin()挂载失败时不会格式化文件系统而是返回FS INIT ERROR错误信息。/status的 JSON 结构handleStatus返回的 JSON 形如{type:LittleFS, isOk:true, totalBytes:1048576, usedBytes:32768,unsupportedFiles:}type当前选择的文件系统名SPIFFS / LittleFS / SDFSisOk挂载是否成功totalBytes/usedBytes由FSInfo结构体获得的总容量与已用字节数unsupportedFiles仅 SPIFFS 模式非空列出文件名不合规而被跳过的文件见下文 SPIFFS 限制。存储空间优化从 27KB 级压缩到 7KB 以内data目录自带若干示例文件index.htm、pins.png、favicon.ico等。若 ESP8266 文件系统空间紧张readme 给出了两个层面的瘦身手段删除示例文件删除文件系统根目录下的示例文件仅保留必需的edit/index.htm替换为 gzip 压缩版把data/edit/index.htm替换为extras/index.htm.gz压缩后的编辑器页面。readme 说明此压缩版不适合用于学习或调试但能把整个文件系统占用压到7KB 以下。注意handleFileRead的“找不到文件时自动尝试.gz后缀”逻辑见上文使得index.htm.gz可以无缝替代index.htm这正是该优化能够成立的原因。在已有文件系统上使用 FSBrowser 的两种方式如果你不想执行第 4 步重新烧录整个文件系统或者要在一个已有数据的文件系统上部署编辑器页面readme 提供了两条路径方式一用 cURL 上传页面在data目录下打开命令行执行curl -F fileedit/index.htm;filename/edit/index.htm fsbrowser.local/edit该命令通过 HTTP 的multipart/form-data上传方式把本地的edit/index.htm直接写入设备文件系统的/edit/index.htm无需重新烧录镜像。方式二把页面内嵌进固件取消 FSBrowser.ino 处的宏注释并重新编译#define INCLUDE_FALLBACK_INDEX_HTM启用后程序会把extras/index_htm.h中内嵌的 gzip 版页面编入固件见 handleGetEdit 的兜底逻辑当文件系统上既找不到/edit/index.htm也找不到/edit/index.htm.gz时直接返回内嵌页面。该内嵌版本功能与原始页面等价代价是固件体积增大。改动页面后的重建流程重要无论是使用 gzip 版还是INCLUDE_FALLBACK_INDEX_HTM内嵌版每次修改index.htm后都必须在extras目录下重新运行reduce_index.sh脚本重新编译并上传固件。reduce_index.sh的流水线是reduce_index.sh用html-minifierkangax 的命令行版本对data/edit/index.htm做压缩去除注释、空白、可省略标签、冗余属性等用gzip压缩得到index.htm.gz用xxd -i把 gzip 字节流转换为 C 数组写入自动生成的extras/index_htm.h文件头明确警告“Auto-generated file. Please do not modify by hand”。脚本依赖xxdVIM 软件包自带、npm与全局安装的html-minifierrun 之前请先确保这三个工具可用。依赖说明Ace.js 编辑器与离线兜底FSBrowser 的编辑功能依赖Ace.js 1.4.9文本编辑器页面通过 CDN 加载https://cdnjs.cloudflare.com/ajax/libs/ace/1.4.9/ace.js。因此浏览器必须能访问互联网编辑功能才能开箱即用。若浏览器无外网例如电脑直连 ESP8266 的 AP 热点可把ace.js复制到文件系统的edit子目录并按需附带插件与语言模式文件。readme 给出的一组典型文件为ace.js ext-keybinding_menu.js ext-searchbox.js mode-html.js worker-html.js worker-css.js worker-javascript.js mode-xml.js worker-xml.js mode-json.js worker-json.js前端逻辑会先尝试 CDN失败后再从/edit/ace.js加载本地副本见 index.htm 的脚本注入逻辑。若本地也没有ace.js页面自动降级为纯文本查看器并显示警告信息对应loadTxtPreview函数。路径约定与各文件系统限制readme 中明确了 FSBrowser 的路径与命名约定这些约定在前端 JS如getParentFolder的路径解析注释与后端源码中均有对应根目录文件系统的根统一写作/路径必须以/开头SPIFFS 不支持不带前导斜杠的路径后端checkForUnsupportedPath会将其判为!NO_LEADING_SLASH!创建语义路径以/结尾表示“新建文件夹”不以/结尾表示“新建文件”与文件有无扩展名无关目录索引URL 不以文件名结尾时含子文件夹默认返回该目录下的index.htm8.3 文件名限制SDFS/FAT16FAT16 只支持 8.3 短文件名SPIFFS 与 LittleFS 也有各自的命名限制。readme 提示 FAT 系列需查阅 8.3 文件名规范SPIFFS/LittleFS 的限制细节见 ESP8266 文件系统官方文档目录支持差异SDFS 与 LittleFS 支持真正的目录SPIFFS 下所有文件都平铺在根上文件名中虽可含/字符但并非真实层级。此外readme 还提到SPIFFS 特有的文件名校验后端在列出目录与创建文件时都会调用checkForUnsupportedPathFSBrowser.ino拒绝含双斜杠//、尾随斜杠/或缺少前导斜杠的文件名并在/status的unsupportedFiles字段中汇总提示。针对 SDFSSD 卡的专属配置若选择USE_SDFS需注意两个配置点CS 引脚SDFS 默认 CS 引脚为 GPIO4SDFSConfig(uint8_t csPin 4, ...)见 SDFS.h。如果你的 SD 卡 CS 引脚没有接到默认引脚需取消 FSBrowser.ino 中fileSystemConfig.setCSPin(chipSelectPin);的注释并把chipSelectPin改为实际 GPIO。setCSPin与setAutoFormat的链式配置接口定义在 SDFS.h。自动格式化与闪存文件系统一致FSBrowser 对 SD 卡同样关闭了自动格式化setAutoFormat(false)挂载失败时只报FS INIT ERROR不会破坏卡上数据。变更记录从旧版 FSBrowser 到统一版的关键改动readme 的 Changelog 部分回顾了该示例的演进理解这些改动有助于排查移植问题适配 LittleFS基于 SDFS时的修复引入#define宏选择文件系统从SD切换到SDFSbegin()不再支持参数删除 SS 引脚参数并改为可选的fileSystemConfig配置LittleFS 的open()第二个参数为必填统一显式指定r读或w写因FILE_WRITE在 LittleFS 下未声明统一改用w字符串。UI / 可用性改进文件系统挂载失败时不格式化仅返回FS INIT ERROR文件树面板宽度改为比例的 20%大屏下可显示长文件名为文件新增图标与文件夹图标缩进对齐换用更轻量中性的图标集并为文本/图片文件提供专属图标条目排序文件夹优先、再普通文件各自按字母序排列文件名后显示文件大小右上角增加文件系统状态信息类型、容量、剩余空间异步操作期间以半透明遮罩 状态文字明确提示点击文件后自动把文件名填入顶栏路径框选择上传文件时默认落在上次点击的文件夹移除 8.3 小写文件名限制支持无扩展名文件名与带扩展名的目录名改进文件树局部递归刷新删除文件后刷新父目录、新建嵌套文件后展示所在文件夹为 Ace 编辑器增加 Save / Discard / Help 按钮、离开前未保存确认、保存后刷新树与状态移除右键菜单中无效的 “Upload” 项右键菜单新增 “Rename/Move” 功能支持通过把index.htm内嵌进程序在已有文件系统上直接使用。TODO未实现的想法readme 中还列出了一些探讨中的方向例如查询 SDFS 的 FAT 类型FAT16/FAT32以在 FAT16 上限制 8.3 文件名、增加可见的根节点/不可删除并标注 FS 类型、把 Mkdir/MkFile 移入右键菜单、实现拖拽移动、可选地把 SPIFFS 呈现为层级结构、同时挂载多个文件系统SPIFFS SDFS 或 LittleFS SDFS等。这些均为规划项当前版本尚未实现。测试清单如何验证 FSBrowser 行为readme 末节提供了针对三种文件系统的行为验证清单可作为手工回归测试脚本。其核心操作为MkFile新建文件、List列表、Edit编辑、Download下载、Delete删除、Upload上传、View image预览图片、Mkdir新建目录、嵌套文件创建与删除、以及对不支持文件名的创建尝试。清单按“8.3 短文件名”与“长文件名”两类用例分别在根目录与子目录中执行。以 LittleFS 长文件名为例覆盖的操作包括MkFile /My text file 1.txt / List / Edit / Download / Delete / Upload /My image file 1.png / View image / Delete image / Mkdir /My Directory MkFile /My Directory/My text file 2.txt / List / Edit / Download / Delete / Upload /My Directory/My image file 2.png / View image / Mkdir /My Directory/My Subdirectory Delete root folder /My Directory Create nested file /My folder/My test file.txt and delete file My test file.txt该清单还专门覆盖了“删除根文件夹”“创建嵌套文件后删除”等边界场景用于验证deleteRecursive与lastExistingParent删除/移动后向上找回最近仍存在的祖先目录见 FSBrowser.ino的行为是否符合预期。小结FSBrowser 是学习 ESP8266WebServer 高级用法的绝佳范本它以单文件 HTML 前端 一组 RESTful 路由实现了完整的文件管理能力通过FS*抽象统一了 SPIFFS、LittleFS、SDFS 三种文件系统并示范了分块响应、流式文件发送、分阶段上传回调、gzip 兜底、资源内嵌等嵌入式 Web 开发的典型技巧。无论是作为 Web 配置界面的基础还是作为文件系统操作的参考实现它都值得在动手前通读一遍源码。进一步探索可以参考仓库中的相关文件FSBrowser.ino、前端页面、readme、压缩脚本、SDFS 配置类 以及文件系统抽象层 FS.h。【免费下载链接】ArduinoESP8266 core for Arduino项目地址: https://gitcode.com/gh_mirrors/ard/Arduino创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考