离屏渲染：照片捕获为什么需要独立的 canvas

两个世界的碰撞

照片捕获是实时流。摄像头每秒产生 30 帧画面，用户调整滤镜，期待立即看到效果。这是一个持续更新、永不停止的过程。

画布合成是静态操作。用户拖拽图片、调整布局、添加文字。每个操作产生一个新的状态，这个状态会保持，直到下一次修改。

这两个世界在同一个应用里相遇。它们的本质冲突决定了一件事：必须分离。

离屏策略的必然性

照片捕获系统不触碰主画布。当用户点击"拍照"，一个隐藏的 canvas 元素在内存中被创建。它抓取视频的当前帧，应用选中的滤镜，转换成 PNG 文件，然后消失。

整个过程不出现在 DOM 树中。主画布甚至不知道这件事发生了。

这不是性能优化，而是设计的必然。

主画布服务于合成。它的更新周期由用户操作驱动。它的渲染依赖 DOM 和 CSS。它需要保持状态的持久性。

照片捕获服务于瞬间。它的更新周期是摄像头的帧率。它的渲染依赖 Canvas API。它不需要持久化，只需要在那一刻精确捕获。

如果强行让主画布处理照片捕获，就会出现两种破坏：

• 实时流的频繁更新会干扰合成画布的状态管理
• 合成画布的 DOM 结构会拖慢实时流的渲染性能

分离不是复杂度，而是对本质差异的尊重。

捕获引擎的封装

usePhotoBooth 这个 hook 封装了整个照片捕获引擎。它管理摄像头权限，处理倒计时，在关键时刻调用 internalCaptureFrame 完成捕获。

捕获的核心逻辑很简单：

1. 在内存中创建临时 canvas
2. 从 video 元素绘制当前帧（非镜像）
3. 通过 ctx.filter 应用滤镜
4. 转换为 PNG File 对象

只有最终的 PNG 文件跨越边界，进入全局状态，出现在资源面板。

这个设计有一个微妙的地方。照片捕获不是生成"图像数据"，而是生成"文件对象"。文件是应用中资源的通用格式。无论是用户上传的图片，还是摄像头捕获的照片，还是从素材库选择的贴纸，它们在进入主画布之前，都统一为文件。

统一的数据格式消除了后续处理的差异。主画布不需要知道这个图像来自哪里，只需要知道它是一个可用的资源。

关于导出管道的双路径设计，双重导出管道的架构选择有详细讨论。

导出的用户上下文分叉

用户完成创作，点击"生成分享链接"。系统必须做一个判断：这个用户是否登录？这个布尔值决定了两条完全不同的执行路径。

游客用户的所有操作都留在浏览器。html-to-image 库遍历主画布的 DOM 结构，捕获所有的插槽、图片、变换和背景色，渲染成 PNG data URL。一个新标签页打开，展示图像。用户可以保存，但没有持久链接，无法真正分享。

登录用户的流程涉及后端。同样的 data URL 被发送到 /api/creations 端点，由 Cloudflare Worker 处理。Worker 生成唯一 ID，上传图像到 R2 存储，构建公开 URL，写入 Supabase 数据库。响应返回客户端，触发分享弹窗。

这种设计反映了用户上下文。游客想要即时结果，零摩擦。登录用户想要持久性和分享能力。同一个 DOM 转图像的操作服务于两者，但之后的路径完全分叉。

发现的裂缝

系统存在一个明显的 bug。前端发送的是 JSON 格式的 Base64 数据：

body: JSON.stringify({ image: dataUrl })

但后端 worker 期待的是 FormData 格式的文件上传：

const formData = await c.req.formData();
const file = formData.get('file');

这意味着上传流程目前是断的。

这不是小问题。它揭示了一个更深层的设计疏漏：前后端的接口契约没有统一。可能的原因是前端代码改过，后端没跟上。也可能是后端代码是从另一个项目复制的，接口定义不一致。

这个 bug 提醒我们：即使架构设计合理，实现中依然会有裂缝。重要的不是避免所有错误，而是建立能够快速发现和修复错误的机制。

设计的本质

照片捕获和画布合成的分离，体现了一个核心设计原则：让架构匹配操作的本质。

捕获是流式的、实时的。它需要低层 canvas API 和内存效率。 合成是静态的、基于 DOM 的。它需要布局灵活性和 CSS 变换。 导出是上下文依赖的。它需要根据用户认证状态分叉。

如果试图用统一的接口处理这三种操作，会在每个层面产生摩擦。分离让每个子系统可以独立优化、测试、调试。它们之间的契约很简单：文件进，图像出。

这种分离不是事先规划的，而是从问题中涌现的。当你理解了捕获、合成、导出的本质差异，分离就是自然的选择。

从意图到架构讨论了这种从用户意图反推技术实现的思维方式。当设计匹配问题的本质，系统就变得容易理解、容易扩展、容易修复。

边界的价值

好的架构不是消除边界，而是建立清晰的边界。

照片捕获的边界是文件。画布合成的边界是 DOM。导出的边界是用户的认证状态。

每个边界都定义了责任的范围。照片捕获不需要知道文件会被如何使用。画布合成不需要知道资源来自哪里。导出不需要知道画布是如何渲染的。

这种分离让系统的每个部分都可以独立演化。未来可以换掉照片捕获的实现，只要输出格式不变。可以重写画布合成的逻辑，只要接受的资源类型不变。可以改变导出的存储方式，只要返回的 URL 格式不变。

清晰的边界不是限制，而是自由。它让每个模块在自己的领域内做到最好，而不必担心影响其他模块。

当架构匹配操作的本质，系统就不需要额外的抽象层来掩盖不匹配。代码变得简单，因为它直接反映了问题的结构。