用途
Export Download Debugging 是一个面向导出/下载故障排查的技能,适用于导出或下载流程看似执行完成、却生成空文件、缺失文件或无法使用的文件的场景。它针对浏览器预览、iframe 截图和 Electron 外壳环境做了专门适配。
主要能力
核心原则
将“捕获”与“保存”分开。在调试目标保存路径之前,先证明导出载荷具有非零字节。0 KB 文件往往意味着原生文件选择器或宿主先创建了目标文件,随后写入失败或被阻止。
证据收集
- 记录载荷类型、MIME 类型、字节长度、object URL 或 data URL 路径,以及抛出的错误名称与消息。
- 检查浏览器控制台输出,以及 showSaveFilePicker、createWritable、
<a download>、URL.createObjectURL 和 URL 撤销相关的应用日志。 - 在 Electron 中检查 will-download 路径:文件名、MIME、文件扩展名、保存对话框过滤器、取消操作和最终文件大小。
- 确认磁盘上实际下载文件的大小,以及它能否在普通图片查看器中打开。
修复顺序
- 先准备并验证导出载荷;在字节可用之前禁用“保存”按钮。
- 优先使用宿主最简单稳定的保存通道。若 showSaveFilePicker().createWritable() 失败、受沙箱限制或产生空文件,改用
<a download>或 Electron 的下载管理器。 - 避免在载荷就绪前打开原生选择器,以防宿主在后续写入失败时留下空的目标文件。
- 对 PNG 降级方案,当 blob URL、撤销时机、CSP 或 iframe 沙箱存在疑问时,优先使用经验证非空的 data URL。
- 在 Electron 中为导出的图片扩展名(.png、.jpg、.jpeg、.webp)添加明确的“另存为”过滤器,让用户能选择真实的图片目标路径。
- 保持界面克制:格式选择、文件名/路径提示、清晰的进行中与错误状态,以及一个主保存操作。
验证
- 为非空载荷准备、回退保存行为、文件扩展名/MIME 映射以及界面禁用/错误状态添加或更新测试。
- 运行聚焦的导出测试,然后执行
pnpm --filter @open-design/web typecheck。 - 若改动了 Electron 下载处理,还需运行
pnpm --filter @open-design/desktop typecheck。 - 提交前运行
pnpm guard,检查暂存差异中是否有无关文件、生成产物和意外密钥,然后按仓库的 PR 质量门禁工作流走流程。
使用方式
该技能以排查流程的形式使用:先复现问题并收集上述证据,再按修复顺序逐项调整,最后通过测试与类型检查验证。资料未提供具体安装命令或调用接口。
适用场景
- 浏览器预览中导出图片得到 0 KB 或空白文件。
- iframe 截图后保存失败。
- Electron 应用下载图片时文件缺失或无法打开。
- File System Access API 在沙箱或权限受限环境下写入失败。
限制
资料仅描述排查与修复方法,未提供该技能的独立安装方式、收费模式或支持的平台范围,这些信息暂未提供。