Appearance
展示屏的客户端状态漂移：代码里发什么 ≠ 客户端里存什么
第二部 · Agent 实践 · 第29章
撰写日期：2026-07-10
结论
做一块常驻大屏（团队状态展示屏，支持在屏上拖动、缩放、改字）时，我被一个反直觉的现象绊住：明明代码里改好了布局，某台机器上看到的还是旧样子。根因不是代码没生效，而是那台机器的浏览器 localStorage 里存着用户自己调过的布局，把代码里的默认值盖掉了。
分布式的展示端有两份状态：代码里发布的，和客户端内存/缓存里持有的（localStorage、浏览器缓存）。一旦允许用户在客户端自定义，这两份就会漂移，而且是静默漂移——每台机器各看各的。
1. 两份状态的分离要显式设计
| 状态 | 存在哪 | 特点 | 风险 |
|---|---|---|---|
| 发布态 | 代码里的 DEFAULT 常量 | 全端一致、可版本管理 | —— |
| 客户端态 | localStorage / 缓存 | 每台机器独立、可被用户改 | 与发布态漂移，且无人察觉 |
设计时必须想清楚：客户端自定义是不是想要的能力？如果是（大屏确实需要现场微调），就得配一套让两份状态可控收敛的机制；如果不是，就别把可编辑状态落进 localStorage。
2. 布局固化工作流：编辑 → 写回种子 → 广播清缓存
允许现场编辑、又不想让漂移永久化，需要一条闭环工作流：
| 步骤 | 动作 | 说明 |
|---|---|---|
| 编辑 | 现场拖动/缩放/改字，存进 localStorage | 即时生效，不用发版 |
| 固化 | 把满意的布局写回代码里的 DEFAULT_LAYOUT 种子 | 让"这台机器调好的"变成"全端出厂默认" |
| 复位/广播 | 提供"复位回默认" + 清缓存信号 | 让其它机器丢弃各自的漂移态，重新吃发布态 |
一个实现细节值得记下来：固化进代码的默认布局最好以视口等比缩放存储（相对比例而非绝对像素），这样不同分辨率的屏播种时能自适应，而不是把一块屏调好的像素坐标硬套到另一块屏上。空 localStorage 即播种默认值，是让新机器开箱即用的关键。
3. 三种收敛策略，按场景选
客户端态和发布态的漂移，通用的解法只有三类：
| 策略 | 做法 | 适用 |
|---|---|---|
| 服务端为准 | 布局存服务端，客户端每次拉取 | 需要多端强一致、允许联网依赖 |
| 缓存失效 | 发版时带 cache-bust 信号，强制客户端丢弃旧缓存 | 以代码为唯一真相、偶尔现场微调 |
| 用户重播种 | 提供"复位"入口，由人主动清掉本地态 | 现场可控、机器数量少 |
我的判断：对数量不多、以代码为真相的展示端，"固化进种子 + 一键复位 + 清缓存广播" 这套轻量组合，比上服务端同步更划算——它不引入新的联网依赖，又能随时把漂移拉回统一基线。