故障排查

无法打开或校验归档

• 先确认文件已下载完整，并用其他可信来源提供的 SHA-256 核对。
• 文件扩展名可能与真实格式不符；ZiFile 会优先保护性失败，而不是猜测错误格式。
• 加密归档需要正确密码。CLI 使用 --password-stdin；空密码会被拒绝。
• 分卷、恢复记录或少见编码可能超出当前支持范围。RAR 读取为 Beta，RAR 创建不支持。

报告兼容性问题时，优先提供创建工具、工具版本、格式选项、ZiFile 版本和可公开的最小复现文件；不要上传客户数据、密码或私人归档。

解压被安全策略拒绝

包含 ..、绝对路径、设备名、大小写碰撞、链接或异常展开规模的归档会被拒绝。这通常是归档损坏、不兼容或具有攻击性的信号。ZiFile 不提供关闭这些安全边界的开关。可在受控环境中用可信工具检查归档结构，但不要覆盖重要目录。

“创建”按钮不可用

• 单流 gzip、zstd、xz、bzip2、lz4 或 brotli 必须只选择一个现有文件，不能选择目录。
• ZIP、7z 或 TAR 组合可接收多个文件和文件夹。
• 来源为空、来源已不存在或输出位置无效时，创建会在保存对话框前被阻止。
• RAR 是只读格式，不能作为创建目标。

操作很慢或被取消

超大归档会受到条目数、展开大小、压缩倍率和内存边界保护；列表按 500 项分页。取消需要 Worker 到达可取消点，超时后应用会终止 Worker。任务失败后可先保存错误文本并重新打开应用，不要反复对同一可疑归档重试。

Worker 意外退出

ZiFile 会把 Worker 崩溃、协议错误或资源限制转换为任务错误，并保持桌面进程可用。重新打开归档可启动新 Worker。如果同一文件稳定复现，请记录应用版本、操作、格式、文件大小和错误文本，并按安全报告要求提供最小样本。

开发包无法安装

未签名 .Dev MSIX 不是正式发行物，某些 Windows 版本会拒绝其 Publisher。不要导入测试根证书、关闭 SmartScreen 或修改系统信任策略。使用完整可运行目录进行开发验证，等待正式可信签名或 Microsoft Store 包用于生产安装。

Explorer 菜单只有在正式包成功安装并激活 Shell 扩展后才可能出现；当前 Release Candidate 不能把注册存在等同于可信安装和菜单生命周期验证。

安全地报告问题

普通缺陷可在 GitHub Issues 提交。疑似安全漏洞请遵循安全政策，不要在公开 Issue 发布未修复漏洞细节、恶意归档、凭据或私人数据。日志中如含本地用户名或路径，请先脱敏。