常见问题处理

预览失败几乎不是前端 iframe 本身的问题。绝大多数 case 都集中在四个环节之一：石墨服务端拿不到源文件、拿到了但识别不出类型、能识别但解析不了、或者命中了旧的预览缓存。本文按"先看错误码、再按现象排查"的顺序展开，并在最后给出提工单前需要准备的信息清单。

一、30 秒自检

按下面四个问题依次过一遍，能覆盖 90% 以上的失败：

石墨服务端能否访问 downloadUrl？ 公网或专线打通、能拿到 HTTP 200、返回真实文件而不是 HTML 错误页。

下载响应头或 ext 字段是否准确？ Content-Type / Content-Disposition 任一存在并正确即可，缺失时必须用元信息中的 ext（不带点）兜底。

文件是否在支持范围内？ 格式受支持、未加密、未损坏、未超大小或单元格上限。

文件更新后 fileId 是否换了？ 复用旧 fileId 会命中旧预览缓存。

二、预览的数据流

浏览器 iframe
   │ 1) 加载 iframe（带签名 / 用户身份）
   ▼
石墨预览服务
   │ 2) 调元信息回调 → 接入方返回 downloadUrl、ext、permissions
   │ 3) 用 downloadUrl 下载源文件
   │ 4) 解析、转换、生成预览资源（含 blob: 资源）
   ▼
浏览器渲染

每一步都可能断：

环节	典型失败信号
1 加载 iframe	页面空白、控制台跨域 / 401 / 403
2 元信息回调	控制台或服务端日志报 401 / 5xx，预览任务直接失败
3 下载源文件	错误码 `90035`、预览任务失败
4 解析与渲染	错误码 `90033`（不支持类型）、`90042`（带密码）、`90050/90052/120509`（过大）等

三、按错误码定位

石墨在预览/导入失败时通常会返回明确的错误码。先按下表对号入座：

错误码	含义	主要排查方向
90033	不支持的预览类型	文件真实格式、元信息 `ext` 字段、响应头是否被改写
90035	下载失败	`downloadUrl` 可达性、鉴权、HTTP 状态码、是否被重定向到登录页
90042	文件带密码	先在业务系统侧解密，或提示用户上传未加密版本
90050 / 90052 / 120509	文件过大	提示用户拆分文件，或在业务系统侧做大小限制
120016	文件不支持导入	对照支持格式，先转码为 PDF / docx 再走预览
120502 / 120507	单元格 / 内容超限	拆分表格、清理多余空白单元格

完整错误码及解决方案见文件预览或导入报错如何处理。

如果界面只是空白、没有任何错误码，看下一节"按现象排查"。

四、按现象排查

1. 页面空白、没有错误码

iframe 加载之前就挂了。重点看浏览器侧：

iframe 地址、签名参数、过期时间是否正确

"当前用户"回调（用户身份）是否返回 200 且字段完整

元信息回调是否返回 200，type、downloadUrl、ext、permissions.readable 是否齐全

控制台是否有跨域 / 401 / 403 / 404 / 脚本错误

元信息回调返回的最小样例（参考官方文档）：

{
  "id": "ba13551165cc5066",
  "name": "示例文档.docx",
  "type": "file",
  "permissions": { "readable": true },
  "downloadUrl": "https://example.com/download/test.docx",
  "ext": "docx"
}

注意：2021-12-01 之后 permissions 必须返回，否则预览会因权限校验失败而中断。

2. 错误码 90035 / 下载失败

石墨服务端拿不到源文件。优先验证可达性：

检查响应：

HTTP 状态码必须是 200。302 跳转到登录页是最常见的隐性失败 —— 表面是重定向，最终拿到的是 HTML。

Content-Length 与真实文件大小是否一致。

Content-Type 是文件类型（如 application/vnd.openxmlformats-officedocument.wordprocessingml.document）而不是 text/html。

下载地址不要依赖浏览器 Cookie、内网域名或 SSO 登录态 —— 石墨服务端拿不到这些。

临时签名 URL 的有效期要足够长，至少覆盖一次完整下载 + 解析（建议 ≥ 10 分钟）。

如果响应头里没法给出正确的 Content-Type 或 Content-Disposition，必须在元信息回调里用 ext 字段兜底：

{ "ext": "docx" }   // 正确：不带点
{ "ext": ".docx" }  // 错误：带点会识别失败

3. 错误码 90033 / 不支持的预览类型

两种可能：扩展名错了，或者真实内容与扩展名不一致。

排查清单：

ext 字段是否在支持范围内：doc / docx / xls / xlsx / ppt / pptx / pdf / txt / md / jpg / png / gif / svg / ofd。

文件真实格式和 ext 是否一致 —— 用 file 命令验证：

文件是否被加密保护（带密码的 docx / pdf 会报 90042，看上去也像"格式不支持"）。

文件是否损坏（用本地 Office 软件能否打开）。

不在支持范围内的格式，在业务系统侧先转码为 PDF 或 docx 再走预览。

4. 预览内容不是最新版

几乎一定是 fileId 复用导致命中了旧的预览缓存。

正确做法：文件内容每次变化，都应生成新的 fileId。

如果业务上确实需要稳定的 ID，可以采用"业务 ID + 内容指纹"组合作为预览用的 fileId，例如 {businessId}-{sha1(content).slice(0,8)}。这样既能定位回业务对象，又能让石墨在内容变更时识别为新文件。

另外要检查的：

downloadUrl 是否还指向旧文件（对象存储覆盖写时 URL 不变，但内容变了，依旧会命中缓存）。

业务侧 CDN / 浏览器缓存是否影响到了 downloadUrl 的下载结果。

5. PC 正常，移动端失败

通常是 WebView 或 Hybrid 容器能力不全。石墨在转换 PDF / 多媒体时会生成 blob: 资源，很多容器默认屏蔽。

处理建议（详见移动端不支持 blob 协议导致预览失败）：

Android WebView：升级至 Chromium 64+，放行 blob: scheme。

iOS WKWebView：保持默认 dataDetectorTypes，允许 blob: scheme。

安全壳 / Hybrid 容器：把 blob: 加入白名单。

容器实在不支持 blob 时，提示用户用系统浏览器打开。

同时确认元信息回调返回的 Content-Type / Content-Disposition / ext 准确 —— 头信息缺失会让 SDK 退回到 blob 缓存，间接放大不兼容问题。

五、关键字段与响应头对照

接入方需要保证的"正确性源"集中在两处：元信息回调的返回值，和 downloadUrl 的下载响应。

元信息回调必填字段

字段	说明	易错点
`id`	文件在业务系统中的 ID	内容变化时建议换 ID，避免命中旧缓存
`type`	固定填 `file`	误填为 `doc` 等其他值会触发协同文档分支
`permissions.readable`	当前用户是否可读	2021-12-01 后强制必填
`downloadUrl`	公网可达的下载地址	不能依赖 Cookie / SSO，签名 URL 有效期足够长
`ext`	文件扩展名	不带点，仅在响应头无法识别时兜底，但强烈建议总是返回

下载响应头建议

HTTP/1.1 200 OK
Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document
Content-Disposition: attachment; filename="示例文档.docx"
Content-Length: 24631

Content-Type 和 Content-Disposition 任一存在且正确即可；都不准确时由元信息中的 ext 兜底。完整 Header 要求见石墨官方文档。

六、还没有解决？

假如排查到这一步仍然无法定位故障原因，可以尝试提供下面这些信息给石墨文档售后，让石墨协助你排查问题。

基本定位：fileId、用户 ID、问题发生时间

环境信息：浏览器版本 / WebView 版本 / App 容器、操作系统

完整 iframe 地址（脱敏后保留签名结构）

元信息回调的请求和响应原文

当前用户回调的请求和响应原文

在服务端环境对 downloadUrl 发起 curl -I 的结果（状态码 + 响应头）

文件真实大小、真实 MIME 类型（file --mime-type 输出）

石墨返回的错误码、错误信息、taskId

七、小结

预览失败时，请按下面这个固定顺序走，绝大多数问题不超过两步就能定位：

看错误码 → 对照第三节表格

没有错误码 → 按第四节"现象"分支

仍未定位 → 收集第六节邀请石墨协助排查

一、30 秒自检#

二、预览的数据流#

三、按错误码定位#

四、按现象排查#

1. 页面空白、没有错误码#

2. 错误码 90035 / 下载失败#

3. 错误码 90033 / 不支持的预览类型#

4. 预览内容不是最新版#

5. PC 正常，移动端失败#

五、关键字段与响应头对照#

六、还没有解决？#

七、小结#