用途:在 Web 应用内建一个仅开发环境可见的小型页面,用确定性场景渲染真实生产 UI,覆盖难以或缓慢通过实际操作到达的状态,如鉴权过期、空/错误状态、长内容溢出、加载/成功/失败面板、大表格、对话框、弹出层等。定位轻量,先搭最小可用路径,场景增多再打磨。命名与 API 需适配目标框架、构建工具、路由与测试运行器。不适用于用户明确要装的真实 Storybook/Ladle、完整设计系统目录或纯后端工作。
主要能力:场景契约,用最小记录描述一个可渲染 UI 状态,含 id、title、可选 description、渲染目标/组件/视图,以及每次渲染生成新数据的 fixture 工厂(如 createProps、createState、setup),id 形如 <group>/<state> 以便用于 URL 和测试;手动注册表,显式有序的组与场景列表,小规模时优先手写导入而非自动发现,加载时校验重复 group id 与 scenario id;共享场景宿主,实验室页面与测试使用同一挂载包装,安装真实应用 provider(主题、路由、i18n、store、查询/缓存、modal/toast 根、特性开关或依赖注入),在此边界桩掉外部服务;仅开发环境实验室路由(如 /__ui-lab),用开发/构建标志排除出生产构建,支持深链 /__ui-lab/<id>;冒烟测试,导入注册表与共享宿主并挂载全部场景,断言不崩溃且无实时服务。
使用方式:先确认框架、路由、构建/开发标志、provider 设置与 UI 测试运行器,复用已有测试 fixture、领域构造器、mock 数据与 provider/测试工具。按顺序加入场景契约、共享宿主、手动注册表与重复 id 校验,接入仅开发路由且不改动正常启动路径,先加 1–2 个场景组并端到端验证,再补冒烟测试,之后才扩充场景。
限制:生产代码不得依赖实验室代码,实验室可导入生产 UI;不得发布实验室,需用静态开发专用构建护栏并在正常生产构建中验证;场景必须确定,不使用实时网络、随机、基于当前时间的日期或实时凭据;优先 fixture 状态而非脚本化设置,仅在需要交互行为时用 DOM 交互回放;不得为生产组件添加仅测试用属性;陈旧场景应删除。选择场景时优先有价值但实时难以到达的产品状态,跳过纯实时状态并对非显然的省略留注释。