关于 export-download-debugging
export-download-debugging 是用于排查导出或下载生成空文件、缺失文件或不可用文件的开发 Skill，适用于浏览器预览、iframe 捕获和 Electron 外壳。它先验证导出数据，再检查保存路径与宿主环境的保存机制。
主要功能
- 01区分数据捕获与文件保存
- 02记录数据类型、MIME 和字节数
- 03检查浏览器与 Electron 下载证据
- 04按顺序排查保存回退方案
- 05验证导出测试与类型检查
适用场景
- 01排查导出操作生成 0 KB 文件
- 02定位浏览器或 iframe 保存失败
- 03检查 Electron 下载路径与文件类型
- 04为导出修复补充测试和验证
安装
复制下面的命令，在终端中运行。
$
npx skills add https:/安装后在 Claude Code 中输入/export-download-debugging确认已加载。
详细介绍
导出下载调试
当导出或下载看似正常运行，却生成空文件、缺失文件或无法使用的文件时，请使用此指南。本文针对浏览器预览、iframe 捕获和 Electron 外壳进行了优化。
核心原则
将捕获与保存分开处理。调试目标路径之前，先确认导出负载包含非零字节。0 KB 文件通常意味着原生文件选择器或宿主创建了目标文件，但写入失败或受到阻止。
证据
- 记录负载类型、MIME 类型、字节长度、对象 URL 或数据 URL 路径，以及抛出的错误名称/消息。
- 检查
showSaveFilePicker、createWritable、<a download>、URL.createObjectURL和 URL 撤销操作前后的浏览器控制台输出及应用日志。 - 在 Electron 中，检查
will-download路径：文件名、MIME 类型、文件扩展名、保存对话框筛选器、取消情况和最终文件大小。 - 确认磁盘上实际下载的文件大小，以及它能否在普通图像查看器中打开。
修复顺序
- 首先准备并验证导出负载；在字节数据可用前禁用“保存”。
- 优先使用最简单、稳定的宿主保存方式。如果
showSaveFilePicker().createWritable()失败、受到沙盒限制或创建空文件，则改用<a download>或 Electron 的下载管理器。 - 避免在负载准备就绪前打开原生文件选择器。这样可以防止后续写入失败时，宿主创建空目标文件。
- 对于 PNG 回退方案，如果 Blob URL、撤销时机、CSP 或 iframe 沙盒设置存在疑点，请优先使用已验证的非空数据 URL。
- 在 Electron 中，为导出的图像扩展名（
.png、.jpg、.jpeg、.webp）添加明确的“另存为”筛选器，以便用户选择有效的图像目标。 - 保持 UI 简洁：格式选择、文件名/路径提示、清晰的待处理和错误状态，以及一个主要保存操作。
验证
- 为非空负载准备、回退保存行为、文件扩展名/MIME 映射，以及 UI 禁用/错误状态添加测试或更新现有测试。
- 运行针对性的导出测试，然后运行
pnpm --filter @open-design/web typecheck。 - 如果 Electron 下载处理逻辑发生变化，还要运行
pnpm --filter @open-design/desktop typecheck。 - 合并前，运行
pnpm guard，检查暂存差异中是否包含无关文件、生成产物和意外泄露的机密信息；如果正在准备修复以供审查，请使用仓库的 PR 质量门工作流。
评论
支持 Markdown