网页伴侣的页面要好看,第一反应当然是 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两步链条,职责分明:
- tailwindcss CLI 扫描
tools/web_index.html里的工具类,产出 minify 后的 CSS——只有页面真正用到的类会进产物,通常几 KB; - 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 解卦——设备替手机去调大模型。那是下一篇的主角。