type
Post
status
Published
date
Jul 15, 2026
slug
article-04-rewrite
summary
从素材、手机界面和背景音乐,到测试与 Cloudflare Pages 部署,复盘方寸专注如何从可运行的原型走到可公开使用的成品。
tags
产品打磨
Web Audio
响应式设计
Cloudflare Pages
category
技术分享
icon
password
系列导航:第一篇 · 第二篇 · 第三篇
最后一个玩法合并进来时,我原以为项目已经快结束了。
它当然已经能玩:有故事、有练习、有进度,也有一套可以运行的界面。但“能玩”离“愿意交到别人手上”还有一段距离。图片放到真实背景里会不会看不清?手机上文字会不会挤在一起?音乐能不能在用户真正操作后自然响起,又在切到后台时安静停下?一个测试全绿的页面,会不会仍然在浏览器里塌成一块空背景?
后半程没有新增太多玩法,却花了不少时间回答这些问题。它们共同构成了把原型磨成成品的工作。

先让所有图片看起来属于同一个世界

最初的场景和角色也来自生成图。问题不在于单张图不好看,而在于每次都单独描述,最后得到的是几种不同的画风:有的像淡彩水墨,有的像 3D 玩具,有的角色比例接近日系动画。单独看都没有问题,放进同一个产品里却像来自不同的故事。
于是,素材刷新不再从一张张图片开始,而是先做一张 3:2 的“风格母版”。它先把这个世界该长什么样说清楚:
  • 轮廓清晰,受到工笔画启发;
  • 使用石绿、石青、朱砂和暖金等矿物色;
  • 能看见宣纸纹理,但不过分抢眼;
  • 光线明亮,孩子容易读懂画面;
  • 人物适合 6 至 12 岁使用者,不采用幼儿化的大头比例;
  • 避开苍白水彩、塑料感 3D、动漫脸、西式奇幻符号、文字和 UI。
有了这张母版,后面的图片才按使用场景成组生成:七张练习封面、六种地形、八个地标、横版和竖版各一张追踪背景、纸鸢和亭子,以及纸鸢小使的四种情绪。
玩法素材刷新后的运行时接触表
玩法素材刷新后的运行时接触表
这批图片使用 CPA 的 `gpt-image-2` 生成。源 PNG、提示词和接触表保存在 Trellis 任务目录;真正进入运行目录的,只有审核、裁切和压缩后的 WebP。
WebP 是适合网页传输的图片格式。这里把它放在最终产品里,并不是为了追求一个格式名称,而是为了不把几 MB 的源图、失败版本和未使用变体也带给每一位访问者。生成目录与 `public/assets` 分开,`public/assets` 只接收实际被引用的优化图片。
最后,素材流程固定为五步:
普通故事和场景图片的上限是 400 KB;画中寻物使用的透明物件上限是 200 KB。当前 `public/assets` 有 116 个文件,总体积约 11.75 MiB,最大单文件约 339 KiB。30 个寻物素材、28 张故事角色立绘、路线切片和追踪前景,都有测试逐一检查路径、扩展名和预算。
还有一个很朴素的教训:透明图不能只在文件浏览器里看。角色必须放进实际背景,在实际缩放和实际 `object-position` 下检查。`object-position` 可以理解为网页裁切图片时保留画面重心的位置。一张边缘很干净的 PNG,缩到手机上后,可能只剩下一块难以辨认的颜色。

手机上的难题,不是多写几个断点

项目只有一个全局 `styles.css`,但每种固定格式的界面都有稳定的尺寸约束。CSS 是网页的排版和外观规则;响应式设计则是让同一份页面在桌面、手机和横屏时都能保持可用。真正麻烦的往往不是断点数量,而是每个元素在有限空间里该让给谁。
状态栏、进度线、棋盘格、角色槽位和底部操作区不能因为数字变长或多出一句提示就忽然跳动。
以山径推演为例,每个格子都预留了四个位置:左上是顺序号,右上是当前位置,中间放地形或地标图,底部留固定高度给标签。手机横屏的高度不够时,可以隐藏不太重要的徽标;但山帖顺序和当前位置的轮廓必须留下。
故事剧场在桌面上有左右角色槽和底部对话卷。到了 390px 宽的手机,它会改成单角色主视图;工具栏、进度、角色和对话仍各自占有清楚的位置。选择出现时,对话区会提前为两个按钮留出高度,正文不会被推到屏幕外。
手机端故事剧场
手机端故事剧场
一个曾漏过的 bug 很说明问题。共享的觉醒背景类写了 `position: relative`,而全屏奖励场景需要 `position: absolute`。`position` 是 CSS 中决定元素如何占位和定位的规则。两个选择器的优先级一样,共享类又写在后面,于是奖励容器被改成了相对定位;它的子元素全是绝对定位,容器最终没有内容撑开高度,塌成了零,只剩一块深色背景。
测试、lint 和 build 当时都通过了,因为它们不会替我们计算浏览器里的真实布局。修复没有继续叠加一个更强的选择器,而是重新划分责任:共享装饰类只管理纹理和层叠顺序,具体页面自己决定 `position`、`display` 和尺寸。随后补了一条源码级回归断言,防止共享类再次声明布局属性。

想要的是音乐,不是再读一遍规则

声音也返工了两次。第一版只有答题提示和语音;后来加了环境音,但那是非常轻的通用合成器声音,在实际设备上几乎听不见。需求里说的是背景音乐,不是把规则再朗读一遍。
最后没有引入音频文件,而是让浏览器用 Web Audio 实时合成音乐。Web Audio 是浏览器提供的一套声音能力,可以在网页里生成、混合和控制声音。五卷内容分别对应五组音色:
画卷主题
主导音色
山林
古琴
水境
箫与笛
大地
埙
灯火
琵琶
星河
古筝
每个主题都有五声音阶动机、不同的根音、节拍和背景纹理。目标是让人能分辨出不同画卷的气氛,而不是假装浏览器振荡器可以替代真实的演奏录音。
浏览器的自动播放规则也决定了:音乐必须等到用户第一次点击、触摸或按键之后才启动。`App` 只保存“是否启用”和归一化后的音量;`ambientAudio.js` 负责保存 `AudioContext`、主音量、压缩器、定时器和当前声音。可以把 `AudioContext` 看作浏览器里的声音工作台。
切换主题时,它会替换同一套循环的乐句安排,而不是再启动第二条循环。页面被隐藏、用户关闭声音或组件卸载时,程序会清理定时器和有限声部,并渐弱后暂停或关闭声音工作台。
背景音乐、动态效果和年级设置
背景音乐、动态效果和年级设置
音量单独保存在 `focus-classics-ambient-volume-v1`,并统一限制在 `0..1`。这样调节音量不会改动整份进度 JSON;旧存档没有音量字段时,也可以使用一个听得见、但不过分抢戏的默认值。

把测试用在最容易伤到体验的地方

当前仓库有 6 个测试文件、72 项测试。重点不是给每个按钮做浅层快照,而是盯住那些一旦出错就可能损坏存档,或让关卡无法完成的纯逻辑:
  • 旧进度迁移、幂等与活动 run 保留;
  • 二十四景内容池和静态素材引用;
  • 七游戏三程覆盖与卷末四项组成;
  • 主线、34 个事件、12 条两段记忆的完整性;
  • story skip、选择历史、短期 echo 和终章重试;
  • 寻物布局、非完成态拼图和加权路线的可解性;
  • 伴灵效果合并,避免同类加成重复叠加;
  • 五卷主题、五种国乐音色和音量归一化。
这里的“纯逻辑”指不依赖屏幕点击和网络请求、输入相同就应当给出相同结果的程序部分。它特别适合检查存档迁移、随机布局和关卡是否可解。
每次代码改动都要经过三道基础检查:
内容测试还会确认 120 个成语、90 首古诗以及每景分级题池有效。但这些检查不是全部。凡是看得见的改动,还要在桌面、390px 手机和短横屏上检查真实布局;声音则要实际走一遍首次手势、开关、主题切换、音量持久化、切到后台与清理。
最终验收从公开域名进入了冒险首页、年级选择、故事剧场、自由练习和山径推演。桌面与手机截图没有控件重叠,浏览器控制台也没有 warning 或 error。

把静态产品放到 Cloudflare Pages

应用是一个静态 Vite SPA,没有服务端 API。Vite 负责把前端代码构建成可以直接发布的静态文件;SPA 是单页应用,页面切换主要发生在浏览器内。于是部署到 Cloudflare Pages 比较直接。Cloudflare Pages 是用于托管这类静态网站的服务:构建完成后,把生成的文件发布出去即可。
项目保留了最初的 Pages 名称 `firefly-focus-kids`,产品品牌已经变成“方寸专注”。生产站点可以通过 Pages 默认域名和自定义域名访问:
2026 年 7 月 15 日的玩法、素材与音频刷新已经在两个地址上验证,代表性 WebP 都返回 `200 image/webp`。文章截图由 PicGo 上传并通过 jsDelivr 提供,不进入产品构建包。

如果从头再来

回头看,我会更早做三件事。
第一,在写视觉方案前,先找一个真正的孩子通过玩法确认产品方向。最初的成人护眼页工程质量不差,但它验证的是错误的问题。
第二,从第一版就给持久化结构加版本号。后来从 21 个阶段改成 24 个场景时,迁移逻辑比功能本身更需要谨慎。
第三,尽早建立浏览器视觉回归。纯函数测试很适合这个项目,却抓不到奖励页高度塌陷、手机状态小字压住进度条、素材焦点被裁掉这类问题。
当前版本也有明确限制:没有多儿童档案、账号和跨设备同步;没有真正的录制乐器音轨;也没有完整的自动化浏览器测试套件。这些方向可以继续做,但会改变隐私、部署和维护成本,不能当成“顺手加上”的小功能。
从一个三分钟计时页走到现在,反复出现的问题都很具体:规则要能恢复,随机要能复现,内容要有边界,视觉要在真实设备上成立。下一轮最该补的是自动化视觉回归,然后再继续扩充故事内容。

手搓导航站日记 (终章):DevOps 降临!打造“自动驾驶”级的导航站 🚀方寸专注(三):七种小游戏如何长成一个无压力的留存循环
Loading...