Phaser 拍照分享模式：截图、隐藏 HUD 和跨端保存限制要提前处理

拍照模式不是截一下 Canvas

很多 Phaser 游戏想做分享功能时，会直接调用 Canvas 的 toDataURL()，把当前画面保存成图片。原型能跑，但上线会遇到一堆问题：HUD 挡住角色，截图时正好在伤害闪烁，跨域图片污染 Canvas，移动端保存失败，水印尺寸不对，玩家昵称或聊天内容被截进图里。拍照分享是内容传播功能，也涉及隐私和平台限制，不能只看技术上能不能导出图片。

好的拍照模式需要一个独立流程：暂停或降速游戏，隐藏不适合入镜的 UI，调整相机构图，允许玩家选择滤镜、贴纸和水印，生成截图，处理保存或分享失败。Phaser 的 Canvas 能提供基础截图能力，但你需要协调 Scene、Camera、UI、资源和浏览器 API。尤其是 Web 游戏，跨端限制比想象多。

先区分截图和拍照模式

截图是快速保存当前画面，通常用于成就、战绩、分享结算。拍照模式则允许玩家自由构图、隐藏 HUD、移动相机、调整滤镜。两者可以复用导出流程，但交互不同。截图强调快，拍照强调控制。不要为了一个分享按钮引入复杂相机，也不要把拍照模式做成只能当前帧截图。

对于动作游戏，进入拍照模式时要暂停战斗或进入安全时间缩放。对于多人或联网游戏，拍照模式不能影响其他玩家，可以只暂停本地表现或提供观战式相机。对于排行榜截图，不能允许玩家随意改数值 UI。不同场景使用不同策略。

flowchart TD
  A["玩家点击拍照/分享"] --> B["PhotoModeController 保存当前 UI 和相机状态"]
  B --> C["暂停或降速游戏逻辑"]
  C --> D["隐藏 HUD、敏感文本和调试层"]
  D --> E["PhotoCamera 构图、缩放、滤镜、贴纸"]
  E --> F["RenderTexture / Canvas 导出图片"]
  F --> G{"保存或分享"}
  G -- "成功" --> H["恢复游戏并记录分享事件"]
  G -- "失败" --> I["提示手动长按保存或重试"]
  H --> J["恢复 UI、相机、输入"]
  I --> J

HUD 隐藏要用层级管理

截图前临时 setVisible(false) 几个按钮很容易漏。更稳的做法是把 UI 分层：gameplay HUD、debug、system overlay、photo overlay、watermark。拍照时隐藏 gameplay HUD、debug 和聊天敏感层，保留必要的拍照操作层；导出时再隐藏拍照操作层，只保留水印和贴纸。导出完成后按保存的可见状态恢复。

不要把所有 UI 都放在同一个 Container 里。结算截图可能需要显示成绩面板，但不需要显示返回按钮；风景拍照需要隐藏全部 HUD；活动分享需要显示活动 logo。PhotoModeController 可以接收 profile：clean, result, eventShare，每个 profile 定义哪些层参与截图。

Canvas 导出有跨域陷阱

如果游戏加载了跨域图片，且服务器没有正确 CORS 头，Canvas 会被污染，toDataURL() 或 toBlob() 会抛错。很多团队本地测试没问题，上线 CDN 后截图失败，就是这个原因。所有可能入镜的图片资源都要来自允许跨域的域名，加载时设置正确属性。第三方头像、广告图、用户上传图尤其危险。如果不能保证 CORS，导出前要隐藏这些资源或使用代理。

移动端还要考虑内存。高分辨率截图会创建大 Blob，低端设备可能失败。可以提供普通清晰度和高清选项。默认截图尺寸不要盲目使用设备像素比的最大值。分享图通常 1080 宽已经足够。超大 Canvas 导出会卡主线程，必要时显示处理中。

一个截图服务骨架

下面的代码展示如何保存 UI 状态、导出 Canvas，并在失败时恢复。真实项目需要结合具体 UI 层。

export class ScreenshotService {
  constructor(
    private readonly game: Phaser.Game,
    private readonly hideForCapture: () => void,
    private readonly restoreAfterCapture: () => void,
  ) {}

  async captureBlob(type = "image/png", quality?: number) {
    this.hideForCapture();
    await new Promise<void>((resolve) => requestAnimationFrame(() => resolve()));

    const canvas = this.game.canvas;
    try {
      const blob = await new Promise<Blob>((resolve, reject) => {
        canvas.toBlob((result) => {
          if (result) resolve(result);
          else reject(new Error("canvas_to_blob_failed"));
        }, type, quality);
      });
      return blob;
    } finally {
      this.restoreAfterCapture();
    }
  }
}

这里等待一个 animation frame，是为了让隐藏 HUD 的状态真正渲染到 Canvas。否则你可能刚设置不可见就立刻截图，画面还是上一帧。导出失败也必须恢复 UI，所以使用 finally。

拍照相机要限制边界

自由相机听起来很棒，但不能让玩家看到未加载区域、穿帮对象或地图外空白。PhotoCamera 应有边界、缩放范围和目标锁定。可以允许轻微偏移、旋转或景深效果，但不要破坏游戏可读性。对于像素风游戏，缩放要保持整数倍或使用合适采样，避免截图糊。

滤镜也要克制。截图滤镜可以通过后处理 Pipeline、RenderTexture 或简单覆盖层实现。关键是导出结果和预览一致。某些 WebGL 后处理在截图时可能表现不同，要在目标浏览器测试。拍照模式里的贴纸和文字最好使用游戏内字体或位图字体，避免系统字体差异导致布局变化。

分享 API 要准备降级

Web Share API 在移动端浏览器支持较好，但桌面和内嵌 WebView 差异很大。保存图片也受平台限制。流程应该是：优先使用 navigator.share 分享文件；不支持时提供下载链接；下载也受限时显示图片预览，提示长按保存。不要只有一个“分享失败”。平台能力检测比 userAgent 判断可靠。

文件名可以包含游戏名、日期和关卡 id，但不要包含玩家隐私。分享前还要确认截图中没有敏感信息：账号 id、调试面板、聊天内容、未公开活动配置。拍照模式默认隐藏这些层。若玩家自定义文字贴纸，需要过滤长度和敏感字符，至少避免布局撑爆。

水印和品牌要有规则

分享图通常需要水印、二维码或活动 logo。水印应考虑不同画幅和安全边距。不要把 logo 固定在右下角 20 像素，遇到刘海屏截图、竖屏图、裁剪图就可能被截掉。可以按图片尺寸计算位置，并提供浅色和深色版本。水印不能遮挡角色脸和关键成绩。

活动分享图可以使用模板：背景来自当前截图，前景叠加活动框、成绩、奖励信息。模板层和游戏截图层分开，便于不同活动替换。不要让运营每次都要求程序改截图坐标。

上线前检查清单

确认截图和拍照模式流程分开；确认 HUD、调试层、敏感文本按层级隐藏；确认导出前等待一帧；确认 Canvas 资源不会被跨域污染；确认低端移动设备有合理截图尺寸；确认拍照相机有边界和缩放限制；确认 Web Share 不支持时有下载或长按保存降级；确认水印适配不同画幅；确认导出失败会恢复 UI 和输入；确认分享埋点记录成功、失败和平台能力。

拍照分享的价值是让玩家愿意展示游戏，而不是让他和浏览器限制搏斗。Phaser 提供了直接的 Canvas 能力，但真正稳定的分享体验来自流程控制、层级管理和降级策略。先把截图变成可恢复、可解释的系统，再去做滤镜和贴纸，分享功能才不会成为线上事故。

结算分享和自由拍照的安全差异

结算分享通常包含成绩、排名、获得奖励和活动信息，它更像一张凭证。自由拍照则偏表达，玩家可以选择角度和贴纸。两者安全边界不同。结算图里的分数和奖励不能来自可编辑 UI 文本，应该从结算结果快照渲染；自由拍照可以隐藏数值，只展示场景和角色。不要让玩家通过修改 DOM 或本地状态生成看似官方的假成绩图。

如果分享图会参与活动投稿，还要保存生成参数：场景 id、角色皮肤、贴纸 id、滤镜、时间和客户端版本。服务器端不一定重建图片，但至少能判断是否来自合法模板。纯客户端活动也应在图中加入轻量水印或活动码，方便运营识别来源。

截图时的动画冻结

截图瞬间如果角色眨眼、受击闪白、伤害数字飞过，成图会很差。拍照模式可以冻结角色动画在当前帧，也可以提供姿势选择；结算截图则应等待关键动画结束后再开放分享按钮。截图服务可以提供 prepareCapture 阶段，让 Scene 清理临时特效、隐藏飘字、暂停粒子，再导出。导出后恢复这些临时效果或直接让它们自然结束。

需要注意的是，冻结不能破坏游戏状态。暂停粒子和 tween 是表现行为，战斗逻辑、网络同步和计时器要按场景策略处理。单机拍照可以全局暂停；联机游戏只能暂停本地表现。PhotoModeController 应声明当前模式的暂停策略，而不是所有地方都 scene.pause()。

图片质量和文件大小

PNG 清晰但体积大，适合像素风、透明贴纸和 UI；JPEG 体积小，适合大面积照片式画面，但会压缩文字。WebP 兼顾质量和体积，但分享兼容性要测试。可以根据分享类型选择：结算图用 PNG 或高质量 WebP，风景截图用 JPEG/WebP。导出后如果文件太大，Web Share 可能失败，下载也慢。服务可以在本地压缩到目标尺寸和质量。

预览图也要和最终图一致。玩家在预览里看到水印不挡脸，保存后不应变成另一套布局。最好用同一张 Blob 生成预览和分享，而不是预览一套 DOM、导出一套 Canvas。这样问题少很多。

社交平台裁剪适配

不同平台对图片比例的处理差异很大。朋友圈、微博、Discord、X、短视频封面都会裁剪或压缩。分享图最好有安全区：核心角色、成绩和二维码不要贴边。可以提供 1:1、16:9、9:16 三种模板，按入口选择。结算页分享通常适合 1:1 或 4:5，横版风景图适合 16:9，竖屏活动海报适合 9:16。

模板预览时要显示裁剪安全线，至少开发模式要能看。运营换水印或活动 logo 时，不应靠肉眼猜位置。Phaser 里可以用同一套布局函数计算水印、安全区和文本位置，避免不同模板重复写坐标。

用户生成内容的边界

如果允许玩家添加自定义文字、贴纸组合或涂鸦，截图功能就变成轻量 UGC。要限制文字长度、行数、字符集和位置，防止遮住整个画面或生成不当内容。贴纸素材要来自白名单，不能让玩家加载任意外部图片，否则跨域、安全和审核都会变复杂。

自定义内容保存时也要区分本地和公开。玩家本地保存可以宽松一些，公开投稿或活动分享需要更严格规则。客户端先做基础限制，服务端或运营再做审核。拍照模式越自由，越要有边界，否则传播功能可能变成风险入口。