export-download-debugging

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Export Download Debugging

导出下载调试

Use this when an export or download appears to run but produces an empty, missing, or unusable file. It is tuned for browser previews, iframe capture, and Electron shells.

当导出或下载看似执行完成，但生成空文件、缺失文件或无法使用的文件时，可使用本指南。本指南针对浏览器预览、iframe捕获和Electron环境进行了优化。

Core rule

核心规则

Separate capture from save. Prove the export payload has non-zero bytes before debugging the destination path. A 0 KB file often means the native picker or host created the target file, then the write failed or was blocked.

将捕获操作与保存操作分离。在调试目标路径之前，先确认导出负载包含非零字节。0KB文件通常意味着原生选择器或宿主已创建目标文件，但后续写入操作失败或被阻止。

Evidence

排查证据

Record the payload type, MIME type, byte length, object URL or data URL path, and thrown error name/message.
Check browser console output and app logs around
```
showSaveFilePicker
```
,
```
createWritable
```
,
```
<a download>
```
,
```
URL.createObjectURL
```
, and URL revocation.
In Electron, inspect the
```
will-download
```
path: filename, MIME, file extension, save dialog filters, cancellation, and final file size.
Confirm the actual downloaded file size on disk and whether it opens in a normal image viewer.

记录负载类型、MIME类型、字节长度、对象URL或data URL路径，以及抛出的错误名称/信息。
检查浏览器控制台输出和应用日志中与
```
showSaveFilePicker
```
、
```
createWritable
```
、
```
<a download>
```
、
```
URL.createObjectURL
```
和URL撤销相关的内容。
在Electron中，检查
```
will-download
```
路径：文件名、MIME类型、文件扩展名、保存对话框过滤器、取消状态和最终文件大小。
确认磁盘上实际下载文件的大小，以及该文件能否在常规图片查看器中打开。

Fix order

修复步骤

Prepare and validate the export payload first; disable Save until bytes are available.
Prefer the simplest stable save channel for the host. If
```
showSaveFilePicker().createWritable()
```
fails, is sandboxed, or creates empty files, route to
```
<a download>
```
or Electron's download manager instead.
Avoid opening a native picker before the payload is ready. This prevents the host from creating an empty destination file on later write failure.
For PNG fallback, prefer a verified non-empty data URL when blob URLs, revocation timing, CSP, or iframe sandboxing are suspicious.
In Electron, add explicit Save As filters for exported image extensions (
```
.png
```
,
```
.jpg
```
,
```
.jpeg
```
,
```
.webp
```
) so users can choose a real image target.
Keep the UI restrained: format selection, filename/path hint, clear pending and error states, and one primary save action.

先准备并验证导出负载；在字节可用前禁用保存功能。
为宿主选择最简单且稳定的保存渠道。如果
```
showSaveFilePicker().createWritable()
```
失败、处于沙箱环境或生成空文件，则改用
```
<a download>
```
或Electron的下载管理器。
避免在负载准备就绪前打开原生选择器。这可防止后续写入失败时，宿主创建空的目标文件。
若使用PNG降级方案，当Blob URL、撤销时机、CSP或iframe沙箱存在异常时，优先使用已验证的非空data URL。
在Electron中，为导出的图片扩展名（
```
.png
```
、
```
.jpg
```
、
```
.jpeg
```
、
```
.webp
```
）添加明确的“另存为”过滤器，以便用户选择有效的图片目标文件。
保持UI简洁：提供格式选择、文件名/路径提示，明确待处理和错误状态，仅保留一个主要保存操作按钮。

Validation

验证方法

Add or update tests for non-empty payload preparation, fallback save behavior, file extension/MIME mapping, and UI disabled/error states.

Run focused export tests, then

pnpm --filter @open-design/web typecheck

If Electron download handling changed, also run
```
pnpm --filter @open-design/desktop typecheck
```
.
Before landing, run
```
pnpm guard
```
, inspect the staged diff for unrelated files, generated artifacts, and accidental secrets, then use the repository's PR quality-gate workflow if the fix is being prepared for review.

添加或更新针对非空负载准备、降级保存行为、文件扩展名/MIME映射以及UI禁用/错误状态的测试。
运行针对性的导出测试，然后执行
```
pnpm --filter @open-design/web typecheck
```
。
若修改了Electron的下载处理逻辑，还需运行
```
pnpm --filter @open-design/desktop typecheck
```
。
在合并代码前，运行
```
pnpm guard
```
，检查暂存的差异文件是否包含无关文件、生成的产物或意外泄露的机密信息，若修复内容需提交审核，则使用仓库的PR质量门禁工作流。