最简路径 uni.downloadFile + uni.openDocument 在真机上大概率失败，因未处理平台差异和临时路径生命周期；需改用 downloadFile → saveFile → openDocument 链路，并针对 iOS 文件名编码、H5 单独跳转做适配。
直接用 uni.downloadFile + uni.openDocument 是最简路径，但真机上大概率失败——安卓找不到文件、iOS 报“无法打开”、H5 完全不走这套逻辑。核心问题不是 API 不可用，而是没处理平台差异和临时路径生命周期。
uni.downloadFile 返回的 tempFilePath 不能直接跨平台 open
安卓和 iOS 的 tempFilePath 指向的是应用沙盒内临时目录，系统级文档查看器默认无权访问；H5 端压根不生成本地路径，tempFilePath 是空字符串或无效值。直接传给 uni.openDocument 在非 H5 环境下基本会报 fail: file not found 或静默失败。
- 安卓：临时文件可能被系统清理，且部分厂商（如华为、小米）对沙盒外路径访问更严格
- iOS：沙盒隔离强，
tempFilePath不在 Document 目录，uni.openDocument无法授权访问 - H5：应跳转
window.location.href或用iframe内嵌，uni.openDocument无意义
uni.saveFile 后的 savedFilePath 才是可靠打开入口
uni.saveFile 把临时文件持久化到应用私有目录（如 _doc/），返回的 savedFilePath 才是各平台都认可的、可被 uni.openDocument 安全调用的路径。但注意两点：
- 必须等
saveFile.success回调拿到savedFilePath后再调uni.openDocument，不能只依赖downloadFile.success - iOS 上若文件名含中文或特殊字符，需用
escape()编码，否则openDocument会失败 - 安卓 10+（API 29+）即使申请了存储权限，也不建议写入公共目录（如
/sdcard/），优先用_doc/或_downloads/
示例关键片段：
uni.downloadFile({ url: 'https://example.com/report.pdf', success: (res) => { if (res.statusCode === 200) { uni.saveFile({ tempFilePath: res.tempFilePath, success: (saveRes) => { const filePath = saveRes.savedFilePath; // iOS 中文文件名处理 const platform = uni.getSystemInfoSync().platform; const finalPath = platform === 'ios' ? escape(filePath) : filePath; uni.openDocument({ filePath: finalPath, showMenu: true }); }, fail: console.error }); } } });
H5 环境必须单独处理，不能复用 App 逻辑
H5 下 uni.downloadFile 实际触发浏览器原生下载，tempFilePath 为空，uni.saveFile 和 uni.openDocument 均不可用。此时唯一可靠方式是让浏览器接管：
- PDF/Word 等支持内嵌的格式，可用
<iframe src="url"></iframe>或新窗口打开 - 通用下载：直接设置
window.location.href = url，由浏览器决定保存或预览 - 不要在 H5 条件编译块里调用任何
uni.*FileAPI，会报错或无响应
条件编译示例：
// #ifdef H5 window.open(url, '_blank'); // #endif // #ifdef APP-PLUS // 走 downloadFile → saveFile → openDocument 流程 // #endif
文件类型与系统支持度影响 openDocument 行为
uni.openDocument 本质是唤起系统默认应用，它不校验文件内容，只看扩展名。常见陷阱：
- 后端返回的 Content-Type 错误（比如 PDF 返回
text/plain），iOS 可能拒绝打开 - 文件扩展名缺失或错误（如返回
xxx?token=abc），需手动补全，例如从 URL 或响应头Content-Disposition提取真实文件名 - 安卓部分低端机对 .docx 支持差，.pdf 最稳；.xlsx 建议转成 PDF 预览更可靠
- 没有安装对应阅读器时，iOS 会提示“无法打开”，安卓可能闪退或无反应，需加
fail回调兜底提示
实际中，别依赖服务器给的文件名。建议统一提取并标准化：
const ext = url.match(/\.([a-z0-9]{2,4})(?:\?|$)/i)?.[1] || 'pdf';
const fileName = `document_${Date.now()}.${ext.toLowerCase()}`;
真正难的不是调三个 API，而是把「临时路径→持久路径→系统唤起」这个链路在三端都跑通。最容易被忽略的是 iOS 的文件名编码和 H5 的完全隔离处理——漏掉任一端，用户就会卡在“点了没反应”。
