PhotoCraft 无法使用？加载、空白画布与导出问题排查

PhotoCraft 出问题时，先区分编辑器没加载、单个文件打不开、修改后无法导出。三种情况的原因不同。保留原文件，先下载仍能访问的工作，再用小型测试图片排查；不要直接刷新正在编辑的页面或清除浏览器存储。

本文针对 v0.5.0 Web 发布包，文档核验日期为 2026 年 10 月 10 日。下面提供诊断流程，不表示本站复现了所有问题。图形后端、托管要求和回退参数依据官方 Web 文档。

示例症状：PSD 能打开，但初始画面不同

2026 年 10 月 10 日的本地检查中，v0.5.0 显示了 640 × 400、RGB、8 位合成 PSD 的两个图层，但 Background 遮住 Amber card，与内嵌合成图不同。隐藏 Background 后矩形可见，把它拖到 Amber card 下方后恢复参考外观。原因尚未确定，可能是样例编码，也可能是导入器行为。排序是该样例的观察结果，不是所有 PSD 渲染差异的通用修复。

环境为 macOS 26.2（25C56）的 Codex 内置 Chromium，1280 × 720 视口和默认渲染器；引擎版本和 WebGPU/WebGL 选择未记录。可以下载双图层 PSD与参考 PNG，完整兼容记录提供体积、哈希和三个状态截图。

同一会话验证 PNG 文件选择器导入、新增英文文字、撤销与重做、裁剪、亮度调整，以及下载 PNG 后独立解码为 640 × 400。没有测试 PSD 保存重开、复杂特性或移动端。如果你的生产文件失败，请按下面症状排查，不要直接把这个样例的排序办法当成通用修复。

先按症状分类

现象	首先检查	帮助区分什么
一直停留在加载阶段	等待运行时下载，查看失败请求	网络传输或运行时初始化
菜单正常，画布黑屏或空白	打开小 PNG，选择适合屏幕	文档视图问题或图形后端
PNG 正常，某个 PSD 失败	文件尺寸、位深、图层和复杂特性	文件解码或内存问题
按快捷键后页面消失	浏览器是否截获快捷键	刷新或新标签冲突
导出结束但找不到文件	浏览器下载记录和拦截提示	下载交付问题
下载成功但 PSD 外观变了	分别比较文字、蒙版、样式和颜色	兼容性问题

每次只改变一个条件。同时换浏览器、文件和图形后端，即使恢复正常也难以知道原因。

首次加载慢怎么办？

在线版需要下载 WebAssembly 程序并初始化图形引擎，首次访问通常比已有缓存时更慢。上游文档里的体积示例来自较早发布包，不能直接当作本站 v0.5.0 的传输大小。

1. 下载仍在进行时保持标签打开，频繁刷新可能反复初始化。
2. 检查普通内容页能否打开。只有编辑器失败时，使用编辑器提供的独立窗口入口比较。
3. 打开浏览器开发者工具的 Network，查看 .wasm 和 JavaScript 请求状态。记录状态码与 URL，勿公开 Cookie 或请求令牌。
4. 用干净浏览器配置或无痕窗口比较，排查扩展干扰。无痕窗口也会影响存储，它是诊断手段，不一定是长期解决方案。
5. 持续失败时查看联系/帮助页了解可用渠道，并准备好浏览器版本、系统、发生时间、失败请求 URL 与状态码。

如果 .wasm 请求失败，记录它的 URL 和状态码。反复刷新通常不能修复运行时文件缺失，或 .wasm URL 返回 HTML 的问题。官方托管文档解释了 WASM 交付、压缩、相对资源路径和缓存一致性为什么重要。官方托管说明

菜单可用但画布空白怎么办？

先选择 View → Fit on Screen，检查图层是否隐藏。空的新文档、画布平移到图片之外，都不能证明图形引擎故障。再打开一张已知正常的小 PNG。

如果工作区本身不能渲染，保存仍可访问的内容，再尝试编辑器里的备用渲染入口。上游优先使用 WebGPU，并自动回退 WebGL2；?webgl 强制 WebGL2，?cpu 选择较慢的 CPU 画布。备用后端能显示小图，不意味着大 PSD 的速度或视觉结果也相同。参数见图形回退说明。

使用较新的浏览器，检查是否允许受支持的图形功能。受组织管理的设备不要绕过管控，把不可用的能力记录给管理员。非本地公开站点需要 HTTPS 才能使用 WebGPU 与剪贴板相关安全上下文能力；显卡、驱动与浏览器也会影响可用性。

为什么 PNG 正常，PSD 打不开？

磁盘上的压缩文件体积不能代表编辑时的全部内存。解码像素、蒙版、图层预览、智能对象与历史记录都可能额外占用资源。复杂颜色模式或滤镜与简单三层 RGB 文件是不同的测试。

1. 确认原软件能打开，并保留未改动源文件。
2. 记录宽高、文件大小、颜色模式、位深与图层数。
3. 从原软件导出扁平参考 PNG，检查该 PNG 在这里能否打开。
4. 仅在副本上逐步去掉复杂功能组以定位原因，不能扁平化唯一可编辑原件。
5. 导入成功后，在 100% 下比较参考图，再开始修改。

详细方法见PSD 兼容性检查。能显示合成预览，不代表所有图层数据都能编辑。

保存后文件在哪里？

Web 版通过浏览器下载保存。查看下载列表中的文件名、后缀、大小与完成状态；浏览器可能追加数字、使用默认文件夹，或要求允许多次下载。如果下载的是 HTML，可能触发了“保存网页”，请改用编辑器内部的 File → Save As。

在小图上试一次 File → Export → Quick Export as PNG。成功则继续核对原任务的格式与缩放；也失败则记录浏览器下载提示。嵌入环境必须允许下载，见iframe 配置说明。重新打开下载文件确认结果，才算保存完成。刷新或关闭标签不等于云端备份。

如何提交有效问题报告？

说明部署版本、系统与浏览器版本、渲染方式、文件尺寸与图层数、复现步骤、预期结果、实际结果和报错原文。截图先去除个人信息，尽量使用可分享的小型合成文件复现，不公开客户素材。

网站加载或导航问题先查看联系/帮助页了解可用渠道；只有属于 PhotoCraft 编辑器本身的引擎缺陷，才提交到官方问题仓库。疑似漏洞按官方安全政策处理，不把安全敏感信息放进公开 Issue。随后可参考首次编辑教程和快捷键指南。