必须先下载文件再传本地路径，否则90%会失败；uni.openDocument仅支持App和小程序，H5需降级为Office Online或iframe，且须确保filePath为合法本地路径、后缀正确、Content-Type匹配、权限与编码合规。
不能直接传网络地址，必须先下载再转本地路径——这是 90% 打不开 Word 的根本原因。
uni.openDocument 传了 .docx 但白屏或报错 “file not found”
常见错误现象是：调用 uni.openDocument 后无反应、闪退、或控制台报 fail no such file or directory。这不是代码写错了，而是传进去的 filePath 根本不是系统能识别的本地文件路径。
- Android 必须用
plus.io.convertLocalFileSystemURL转换tempFilePath，否则系统读不到文件（iOS 部分版本可直传，但不建议依赖） -
tempFilePath后缀必须是.docx或.xlsx，不能是.tmp或无后缀；可用path.extname检查，必要时手动重命名 - 服务端响应头必须带正确的
Content-Type：application/vnd.openxmlformats-officedocument.wordprocessingml.document（Word）或application/vnd.openxmlformats-officedocument.spreadsheetml.sheet（Excel） - Android 10+ 需在
manifest.json中声明"android.permission.READ_EXTERNAL_STORAGE"，且targetSdkVersion≤ 29，或启用android:requestLegacyExternalStorage="true"
H5 端点开就下载，根本预览不了
H5 完全不支持 uni.openDocument，这是官方明确限制（仅 App 和小程序支持）。所谓“打开”，浏览器只能触发下载，或跳转到第三方在线查看器。
- 必须降级为微软 Office Online：
https://view.officeapps.live.com/op/view.aspx?src=+encodeURIComponent(公网可访问的 .docx URL) - URL 必须是 HTTPS、公网直连、无登录态重定向；
/api/file?id=123这类接口地址一定失败 - 中文文件名、空格、特殊字符必须编码，否则链接被截断，预览页白屏
- 文件大小建议 ≤10MB；超大 Excel 表格加载慢且无错误提示，只能靠超时兜底
后端返回 ArrayBuffer，怎么喂给 uni.openDocument？
当接口返回的是二进制流（arraybuffer），不能直接塞给 uni.openDocument——它只认文件路径，不认内存数据。
- 用
uni.arrayBufferToBase64转成 base64 字符串 - 用
uni.getFileSystemManager().writeFile写入uni.env.USER_DATA_PATH下的安全路径（如uni.env.USER_DATA_PATH + '/report.docx'） - 写入成功后，把生成的完整路径传给
uni.openDocument，并显式指定fileType: 'docx' - Android 10+ 不需要额外存储权限，但路径必须在沙盒内（
_downloads/或USER_DATA_PATH是安全选择）
最容易被忽略的一点：iOS 上用户看完 Word 后点左上角「完成」才回到你的 App；Android 上部分机型按返回键直接退出预览页，且不会触发任何回调——如果业务依赖「预览后跳转」，必须用 plus.webview.currentWebview().addEventListener('backbutton') 主动拦截。
