硅基铁匠丙午年 · 独立刊物
← 返回全部文章
技术与 AI约 12 分钟

断网也能看片、查维基：Nomad 把 ESP32 变成口袋服务器

用一块 Waveshare ESP32-S3 和一张 microSD 卡，可以搭建自带 Wi-Fi 的离线媒体库。动手前需了解 4GiB 文件限制、视频转码要求、发热、稳定性和当前安全边界。

坐飞机、露营、跑长途，手机里提前下载的片子总有不够看的时候。几个人想共用一套电影、音乐和电子书，通常还得带路由器、小主机，再装一套媒体服务。

Nomad 把这套东西压进了一块 ESP32-S3 开发板。它会自己创建 Wi-Fi 热点，手机、平板和电脑连上之后，直接用浏览器打开媒体库。整个过程不依赖互联网，也不用安装 App 。

它也能装离线维基、 Project Gutenberg 、 TED 等 ZIM 内容。设备通过 USB 供电，可以连接充电宝、电脑或其他 USB 电源。

ESP32 的性能和存储条件有限，搭建前需要确认文件格式、存储限制和安全边界。格式或编码不兼容时，可能出现菜单正常、视频无法播放的情况。

它把四样东西塞进了一个小盒子

Nomad 技术结构图

Nomad 的工作链路很短：

  1. ESP32-S3 创建本地 Wi-Fi 热点；
  2. microSD 卡保存网页、索引和媒体文件；
  3. ESP32 上的 Web 服务把内容发送给浏览器；
  4. 手机或电脑负责解码和播放。

所以它没有 Jellyfin 、 Plex 那种服务端实时转码能力。 Nomad 主要负责“发文件”，播放效果取决于三个条件：媒体编码是否被浏览器支持、 SD 卡读取是否稳定、当前无线环境是否拥挤。

目前的界面包括电影、剧集、音乐、 PDF 、 EPUB 、漫画、图片、普通文件和 ZIM 离线资料库。它还有后台索引、播放进度、主题切换和文件管理。播放进度保存在各自浏览器里，不是跨设备账号同步。

适用场景与性能上限

Nomad 很适合这些场景：

  • 自驾、露营、长途航班和轮船上的离线片库；
  • 网络不稳定地区的电子书、音频和资料分发；
  • 教室、展会或小型活动里的本地内容站；
  • ESP32 、 Web UI 、局域网服务和 3D 打印的练手项目。

它不适合作为家里的主媒体服务器，也不适合存唯一一份重要资料。

当前 Nomad 构建要求 microSD 卡使用 FAT32，因此单个文件必须小于 4GiB，最大值为 4GiB−1 字节。这是当前软件栈的限制，不代表 ESP32-S3 在技术上完全无法支持 exFAT 。 ESP32 也无法实时把高码率视频转成低码率。维护者建议视频尽量压到 480p；1080p 在部分编码和单路播放时能用，但无线干扰、 SD 卡和码率都会影响缓冲。

维护者称测试中最多跑到约 8 路视频，但没有公布那次测试的具体编码和码率。测试地点在无线干扰较少的树林，城市环境可能更差，因此 8 路只能视为一次理想环境结果。音乐占用的带宽较低，多路视频对无线带宽和读取稳定性的要求高得多。

准备这些硬件和软件

Nomad Mk4 外壳拆解

最省事的硬件组合是：

  • Waveshare ESP32-S3 1.47 英寸 LCD 开发板；
  • 16GB 以上 microSD 卡，仓库推荐 16GB～128GB；README 标称最高 2TB，但 1.5～2TB 尚未完整实测；
  • USB 电源；
  • 可选的 SD 卡延长线和 3D 打印外壳。

项目针对这块 Waveshare 板做了不少底层适配。其他 ESP32-S3 即使参数接近，也可能缺少同样的 SD 卡布线、 PSRAM 、 Flash 或屏幕配置。第一次搭建不建议换板。

microSD 卡最好选 High Endurance 系列，并保留电脑上的媒体备份。索引重建、上传和文件编辑会产生写入；Class 10 只代表最低持续顺序写入速度，不等于耐写寿命，持续高温也可能缩短卡片寿命。

软件需要：

  • Arduino IDE；
  • FAT32 格式化工具；
  • GitHub 仓库中的 SD_Card_Template；
  • 可选的 HandBrake 1.11.2 或更高版本；
  • 处理 ZIM 、封面和大媒体库时使用 Nomad Card Tools 。

搭建最小可用版本

仓库目前没有 GitHub Releases 或稳定版固件下载页。建议下载固定提交的仓库压缩包，并保留搭建时使用的源码，避免后续因 main 分支变化而难以复现配置。

下面以 2026 年 7 月 27 日的提交 6dd953f 为核对版本。

第一步：准备测试卡

先把卡里的旧数据备份，再格式化为 FAT32 。 Windows 对大于 32GB 的卡通常不会直接提供 FAT32 选项，需要使用专门的 FAT32 格式化工具。

格式化会清空整张卡。盘符选错，电脑里其他磁盘也会被擦掉。

完成后，把仓库里的 SD_Card_Template 内容复制到卡根目录。先不要塞几百部电影，保留模板文件，再增加一个小测试视频和一首 MP3 就够了。

一个最小目录可以这样放：

/Movies
    demo.mp4
    demo.jpg

/Music
    demo.mp3

index.html
menu.html
movies.html
music.html
...

电影海报与视频使用相同的主文件名，例如 demo.mp4 对应 demo.jpg。剧集文件要放进剧名子目录，使用 S01E01 - 标题.mp4 这类命名，按字母排序时不容易乱。

第二步：准备兼容性较高的测试视频

仓库已经提供 HandBrake 预设：

Nomad-480p-Web-DirectPlay-HandBrake-1.11.2.json

这份预设使用：

  • MP4 容器；
  • H.264 Main Level 3.0；
  • 最高 720×480；
  • 最高 30 fps；
  • 600 kbps 平均视频码率，两遍编码；
  • 80 kbps AAC 双声道；
  • Web Optimized 。

导入方法：打开 HandBrake，选择 Presets > Import from file，导入上面的 JSON，再选择 Nomad 480p Web Direct Play - Small。

README 列出了 MKV 、 MOV 、 TS 等扩展名，主要表示索引和分发层面的识别范围；能否播放仍取决于容器内编码和手机浏览器的解码能力。现有问题还报告过 MKV 无法正常出现在媒体库中。首次验证建议使用仓库预设生成的 H.264 + AAC MP4，确认可用后再测试其他格式。

请只放自己拥有、获授权或允许传播的媒体。 Nomad 不处理 DRM，也不改变内容版权。

第三步：配置 Arduino IDE

在 Arduino IDE 的开发板管理器中加入：

https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json

然后选择 ESP32S3 Dev Module，核对这些选项：

USB CDC on Boot: Enabled
Flash Size: 16MB (128Mb)
Partition Scheme: 16MB Flash (3MB APP/9.9MB FATFS)
PSRAM: OPI PSRAM
Upload Speed: 921600
USB Mode: USB-OTG (TinyUSB)

依赖按以下版本安装：

ArduinoJson 7.3.0
Async TCP 3.4.7
ESP Async WebServer 3.7.1
LVGL 8.3.10
SdFat 2.3.0

把 firmware/JcorpNomadProject 整个目录保留完整，再打开其中的 .ino 文件。缺少 AsyncTCP.h、lv_spinner_create 参数不匹配等报错，大多与依赖缺失或版本不一致有关。

仓库固定了上面五个 Arduino 库版本，但没有固定 Arduino IDE 和 esp32 by Espressif Systems 开发板包版本。首次编译成功后，把这两项版本也记下来；只保存提交号还不足以完全复现构建环境。

上传失败、串口不再识别时，可以按住 BOOT，按一下 RESET，先松 RESET，再松 BOOT，让开发板重新进入刷写模式。

第四步：连接、索引、做 10 分钟验收

刷写完成并插入 SD 卡后：

  1. 连接 Wi-Fi Jcorp_Nomad；
  2. 初始密码为 password；
  3. 浏览器访问 nomad.local/menu；
  4. 地址打不开时改用 192.168.4.1/menu；
  5. 进入管理页，执行 Library Index > Full Scan Now；
  6. 先完整播放 10 分钟测试视频；
  7. 再接入第二台设备，同时播放视频或音乐。

一开始导入大型媒体库会增加排错难度。确认一个 MP4 、一首 MP3 和第二台设备均可正常使用后，再逐步增加内容。索引大量音乐时若设备重启，可以改用电脑端 Card Tools 重建索引。

离线维基需要电脑预处理

ZIM 文件不能直接拖进 SD 卡。 Nomad Card Tools 会在电脑上完成拆分和索引，绕开 FAT32 单文件小于 4GiB 的限制。

Windows 双击：

START-Windows.bat

Linux 运行：

./start-linux.sh

工具可以添加一个 ZIM，也可以批量导入整个目录。已有资料不会被自动清空，但目前无法只移除其中一个 ZIM；要删掉某个资料库，往往需要清理 ZIM 数据后重新导入保留的集合。

Kiwix 提供不同体积的 Wikipedia 、 Gutenberg 、 TED 、 iFixit 等离线包。 Nomad Tools 目前仍比较粗糙，README 只写到可以处理多数常见 ZIM；明确测试过的主要是 Wikipedia 、 Gutenberg EPUB 和 TEDx 视频。其他资料包应先用小样本验证搜索和阅读，再考虑几十 GB 的完整集合。

安全边界

Nomad 屏幕状态界面

Nomad 面向随身携带、离线使用且成员彼此信任的小型网络。不要让陌生人接入，也不要通过端口映射将它暴露到互联网。

当前核对版本有几处明确风险：

  • 管理密码默认为空，此时 checkAdminAuth() 会直接放行管理操作；
  • 未鉴权的 /settings 会返回 adminPassword 哈希和 Wi-Fi 密码，/admin-status 也会返回 Wi-Fi 密码；登录接口直接接受该哈希，已连接客户端可把泄漏值当作等效密码换取管理令牌；
  • 上传、建目录、重命名、递归删除和文件保存接口均未执行管理鉴权，已连接客户端可以尝试修改或删除 SD 卡内容；
  • 文件保存接口还能覆盖设备网页。 Nomad 使用 HTTP，也没有用户级访问控制，同一热点内的客户端应被视为处于共同信任域。

外出使用时，建议遵守以下限制：

  • 不把热点密码告诉不信任的人；
  • 不在卡里存身份证扫描件、密码库、私密照片和唯一备份；
  • 不把设备桥接到公网，不做路由器端口转发；
  • 每次出行前保留一份完整 SD 卡备份；
  • 公开活动只放可被所有参与者看到、下载和删除后也不致损失的内容。

修改默认 Wi-Fi 密码可以阻止不知道新密码的人加入热点。设置管理密码只能保护正确接入鉴权检查的接口；当前的哈希泄漏和未鉴权文件接口意味着它不能可靠地把已连接客户端降为只读访客。

使用前还需留意

  • 项目状态： 项目仍处于 Beta，README 也把 Mk4 称为 semi-stable 。近期反馈包括 MKV 无法正常入库、库列表可见但图片或视频无法播放，以及大型音乐库索引时重启。构建环境、卡片质量和媒体格式都会影响结果。
  • 发热与装配： 维护文档建议外壳优先使用 PETG，并提醒屏幕和排线比较脆。外壳装配前先完成播放测试，减少排查软件问题时的拆装次数。
  • 许可证： 仓库根目录使用 CC BY-NC-SA 4.0，包含“非商业使用”和“相同方式共享”要求。这份许可证不属于常见的 OSI 开源软件许可证，仓库中的部分第三方组件还带有各自的许可。公开授权不包含商业用途；销售改版成品、商业集成或其他营利用途，应先向相应权利人取得额外许可。

适合哪些人

Nomad 是一台很小、低功耗、可由大多数现代手机、平板和电脑浏览器访问的离线内容盒子。它的性能、存储格式和安全机制无法承担 NAS 或 Plex 的用途，入口跳转、 mDNS 和媒体直放能力也会受具体系统与浏览器影响。

它适合愿意刷固件、整理目录并提前转码视频的用户。当前版本无法承担 4K 直放，也不宜向陌生人开放热点。

如果是你，会先往这张卡里放电影、电子书，还是一套离线维基？

来源链接: https://github.com/Jstudner/jcorp-nomad

构建指南: https://www.instructables.com/Jcorp-Nomad-Mini-WIFI-Media-Server/

图片与技术图来自 Jcorp Nomad 仓库，仓库标注 CC BY-NC-SA 4.0 。

来源：https://github.com/Jstudner/jcorp-nomad