uni.openDocument打不开Word/Excel主因是路径不合法或MIME类型不匹配：需先用uni.downloadFile下载文件获tempFilePath，再传入；H5端须降级为a标签或Office Online；Android/iOS需校验后缀、Content-Type及Android 10+存储权限。

uni-app 里 uni.openDocument 打不开 Word/Excel 怎么办

多数情况下不是代码写错了，而是文件没走通「可访问路径」这关。uni-app 的 uni.openDocument 只接受本地临时路径（tempFilePath）或网络直链（需支持 CORS + 不带登录态重定向），但直接传后端返回的 docx/xlsx 下载地址大概率失败——浏览器会跳 302 到登录页，或者跨域拦截，App 端则可能因证书/协议限制拒绝加载。

• 先确认文件是否已下载到本地：uni.downloadFile 必须调用成功，并拿到 tempFilePath，再传给 uni.openDocument
• 不要直接把后端接口 URL 塞进 filePath，哪怕它看起来是 .docx 后缀——那只是个接口地址，不是真实文件路径
• H5 端不支持 uni.openDocument，必须降级：用 <a href="xxx.docx" download></a> 或 iframe 嵌入 Office Online（需公网可访问 + 文件公开）

Android/iOS 上预览失败的常见报错和对应解法

真机调试时看到白屏、闪退或弹出“无法打开文件”，大概率是 MIME 类型或文件扩展名不匹配。系统内置文档查看器（如 iOS Quick Look、Android WPS/Office）依赖扩展名和 header 中的 Content-Type 双重识别。

Work Productivity Word Mail Workflow Helper

构建并排查Microsoft Word邮件合并及DOCX模板工作流，使用合并域、内容控件、文档属性、重复区块、数据等

下载

• 确保 uni.downloadFile 成功后，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 uni.getFileSystemManager().writeFile 写入 uni.env.USER_DATA_PATH 路径才安全

替代方案：不依赖系统查看器的轻量级预览

如果目标是「快速看内容」而非「编辑」，且文档结构较简单（比如报表、通知类 Word），转 PDF 是最稳的路径。服务端生成 PDF（如用 LibreOffice headless 或 python-docx + weasyprint），前端只处理 PDF 预览，兼容性高、无 MIME 陷阱。

• uni.showLoading 后调用 uni.downloadFile 获取 PDF tempFilePath，再用 uni.openDocument 打开——PDF 格式在所有平台支持度远高于 Office 原生格式
• 若必须原格式预览且服务端不可控，可考虑前端解析：用 docx（npm 包）解析 .docx 为 HTML，在 <web-view></web-view> 或 v-html 渲染；但仅适合纯文本/简单表格，复杂样式和公式会丢失
• 微信小程序内可直接用 web-view 加载腾讯文档链接（需将文件上传至腾讯文档 API），但 uni-app 编译到微信时需配置 allowedUrls 白名单

uni-app 条件编译下各端行为差异要点

同一个 uni.openDocument 调用，在不同平台实际走的是完全不同的底层逻辑，不能假设表现一致。

• H5 端：压根不执行，必须用 #ifdef H5 包裹降级逻辑，比如 window.open(url) 或 iframe
• App 端（iOS）：要求文件路径必须在 plus.io.convertLocalFileSystemURL 转换后的沙盒路径内，否则报错 file not found
• App 端（Android）：部分厂商 ROM（如华为 EMUI）会拦截非标准路径的文件打开请求，建议统一用 uni.getFileSystemManager().getSavedFileList 验证文件是否真正落盘成功
• 微信小程序：支持 docx/xlsx，但要求域名备案 + HTTPS + 文件直链可 public 访问；不支持本地临时路径（tempFilePath 无效）

文件预览真正的难点不在调用 API，而在路径可信性、MIME 准确性、以及各端对「文件存在」的定义根本不同——iOS 认为沙盒外=不存在，Android 认为没权限=不存在，H5 认为跨域=不存在。绕开这些坑，比写十行代码更关键。