大飞的技术博客

·约 3 分钟·

热点里没有 CDN:Tailwind 内嵌与固件资产管线

网页伴侣的页面要好看,第一反应当然是 Tailwind——但马上撞上一堵墙:手机连的是设备热点,热点里没有互联网,CDN 引不了。<script src="cdn.tailwindcss.com"> 在这张网络里是一个永远转圈的请求。这篇讲这块屏幕背后的完整管线:CSS 怎么编译、HTML 怎么内嵌、gzip 怎么进 flash,以及没有设备时怎么看效果。

演进:从字节数组到文件

v1 的做法很直接:HTML 是生成器产出的 C 字节数组(web_assets.c),编进 app 二进制,httpd 从内存里把字符串吐出去。能用,但两个别扭:每改一行 HTML 都要重编整个固件;页面长大后开始挤压 app 分区。

assets 分区落地后,页面搬了家:构建产物变成 assets/www/app.html.gz,和签文语料、字库一起打包进只读 FAT。固件侧从一个 extern 数组变成一次 FAT 文件查找,idf.py flash 时随镜像自动带上,单独更新资源用 idf.py assets-flash——改页面不再等于改固件。

Tailwind 在无网环境下的正确姿势

Tailwind 的工作方式恰好帮了大忙:它是编译型的,最终产物就是一份纯 CSS。那就把编译放在有网的开发机上:

npx -y tailwindcss@3.4.17 -c tools/tailwind.config.js \
     -i tools/web_input.css -o tools/web_index.css --minify
python -X utf8 tools/gen_web.py

两步链条,职责分明:

  1. tailwindcss CLI 扫描 tools/web_index.html 里的工具类,产出 minify 后的 CSS——只有页面真正用到的类会进产物,通常几 KB;
  2. gen_web.py 把 CSS 内联进 HTML 的 <!--INLINE_CSS--> 标记处,再整体 gzip,写进 assets/www/app.html.gz。

生成器里有两个容易漏的细节:

  • Content-Encoding: gzip 直接声明,不做协商。浏览器请求资源时本来就带 Accept-Encoding: gzip,固件侧不需要任何 accept 判断——收到请求就把 gzip 字节流原样吐出去,浏览器自己解压。gzip 让页面从 44KB 缩到 10KB 量级,200×200 墨水屏设备的热点传输,每一 KB 都有体感。
  • mtime=0 保证输出字节可复现——同一份源码,两次构建产出逐字节相同的 .gz。对做增量对比和完整性校验的人(主要是未来的自己)是莫大的仁慈。

顺带一提主题:tailwind.config.js 里定义的不是蓝紫渐变,而是设备的材质——宣纸 #f7f2e8、墨 #26211c、朱砂 #a3302a。网页是墨水屏的门面,配色跟玻璃走。

单文件纪律

热点里的页面只有一份 HTML,没有第二跳。这条约束执行得比想象中严格:

  • CSS 内联,JS 内联,图标用 SVG 直接画在 HTML 里;
  • 不做路由,一个页面内 tab 切换;
  • 没有框架、没有构建时的 JS 转译,<script> 里是原生 ES 手写——反正页面小,框架的收益是负的。

「单文件」和「无框架」不是审美洁癖,是把复杂度拦在固件外:任何依赖解析、代码分包、运行时加载,在这个网络拓扑里都没有存身之处。

没有设备怎么看效果

改页面不可能每次都烧机验证,tools/web_mock.py 就是为此存在的:

python -X utf8 tools/web_mock.py   # 本机起服务,/app 出页面

它用 build 中间产物渲染同一个 HTML,并把每个 /api/* 端点桩成和 web.c 同形状的假 JSON。于是无设备时能完整走一遍视觉流程:配网表单、求签、奇门、历史,连加载态都和真机一致。

边界写得清楚:mock 的 JSON 是手工对齐固件输出的形状,固件才是唯一真相——mock 只管视觉,不管语义。这话反过来也成立:每次改 web.c 的 JSON 字段,mock 里那几行假数据要跟着改,不然下一个人对着 mock 调样式,调出来的东西真机上就是歪的。

小结

整条管线一句话:源文件(Tailwind 工具类)→ 开发机编译(内嵌 CSS)→ gzip → FAT 镜像 → 设备 mmap/读文件 → Content-Encoding: gzip 原样吐出。热点里没有 CDN 不可怕,可怕的是用「在线引入」的思路硬套离线设备——把编译搬到开发机、把产物搬进资产分区,离线约束反而逼出了一条更干净的构建链。

页面里唯一会走出热点的请求,是网页上触发的 AI 解卦——设备替手机去调大模型。那是下一篇的主角。