如何预热预览缓存

你的应用可以在用于在用户打开预览之前请求石墨文档中台的POST /sdk/v2/api/cloud-files/{fileId}/create 接口来实现缓存预热，先让石墨服务端把源文件下载、解析、转换好。用户真正打开 iframe 时直接命中缓存，跳过"首次等待"时间，提升用户体验。

它是同步接口：请求会一直等到预览任务创建完成（成功或失败），石墨文档中台返回的响应里会返回结果。所以适合做后台预热，不适合放在用户的关键路径上同步等待。

适用范围：普通 Office 文件预览（只读）。不会把文件转成可编辑的协同文档；如果需要可编辑文档，请走创建协同文档接口。

一、什么时候应该调用

场景	是否推荐预热
上传完成后，预计用户很快会打开	推荐：上传成功后立即在业务后端异步触发
大文件 / 复杂 PPT / 多 Sheet Excel	强烈推荐：首次解析可能数秒到数十秒
批量导入历史文件	推荐：低峰期批量预热高频文件
用户极少打开的冷数据	不推荐：浪费资源，按需走懒加载即可
文件还可能频繁覆盖更新	不推荐：见下文"缓存失效"，先确定版本策略再预热

两条工作流的对比（完整时序图见官方文档）：

方案 A：用户直接访问（首次慢）

方案 B：服务端预热（推荐）

二、调用前的前置条件

预热调用本身只是触发器，真正能不能成功取决于接入方的几个回调和文件本身。开调用之前请按下面这张清单逐项核对：

GET {endpoint_url}/users/current/info 可用，石墨能用 X-Shimo-Token 识别当前用户

GET {endpoint_url}/files/{fileId} 返回的 type 是 file（普通文件，不是协同文档）

元信息返回的 permissions.readable 为 true

元信息返回了完整的 downloadUrl 和 不带点的 ext（如 docx）

石墨服务端能访问 downloadUrl，下载到的不是 0KB、不是 HTML 错误页

任何一条不满足，预热都会直接报错。downloadUrl 怎么设计、怎么避开防盗链坑，见下载地址与防盗链设计指南。

三、请求与响应

请求形态非常简单 —— fileId 放在路径里，请求体为空：

成功响应（code 和 message 都是空字符串）：

{
  "code": "",
  "message": ""
}

失败响应（code 非空 + 可读的 message）：

{
  "code": "90042",
  "message": "文件格式不正确"
}

注意：HTTP 状态码是 200 不代表预热成功，必须看响应体里的 code 是不是空字符串。

四、缓存命中与失效

这是预热接入里最容易踩坑的地方。

核心心智：石墨的预览缓存是按 fileId 维度建立的。一旦同一个 fileId 完成了首次预览（无论是用户触发还是预热触发），后续即使接入方在元信息回调里返回了新的 downloadUrl、指向新的文件内容，预览结果也不会更新 —— 石墨直接返回旧缓存。

所以：

文件内容变化 → 必须换 fileId。这是唯一可靠的方式。

推荐用 业务文件ID-版本号 或 业务文件ID-内容哈希 作为预览用的 fileId：

预览 fileId = file_38291          # 错：覆盖写时缓存命中旧内容
预览 fileId = file_38291-v3       # 对：每次内容变化版本号 +1
预览 fileId = file_38291-a8c7f2   # 对：用内容 SHA1 前缀

业务侧维护"业务 fileId → 当前预览 fileId"的映射，旧的预览 fileId 可以异步清理，新的走一次预热。

五、失败处理

预热失败不要阻断业务上传流程：用户上传完成的反馈应该独立于预热结果。预热失败时按下面这套来处理：

把 code、message、fileId、文件扩展名、文件大小、downloadUrl 的服务端可达性结果一起写日志，方便后续定位。

根据错误码决定是否重试：

90035（下载失败）通常是 downloadUrl 临时不可达，可以隔几分钟重试一次，最多 2~3 次。

90033（不支持的预览类型）、90042（文件带密码）、120016（不支持导入）这类错误重试也没用，记录后跳过。

90050 / 90052 / 120509（文件过大）/120502 / 120507（单元格超限）属于文件本身的问题，提示业务侧或用户。

即使预热失败，用户后续打开预览时仍会走懒加载方案 A，会看到"等待中 → 失败原因"，体验降级而非完全不可用。

完整错误码及对应排查方向见文件预览失败排查指南。

六、与相关接口的关系

接口	作用	文档
`POST .../cloud-files/{fileId}/create`	预热缓存（本文）	本文
`GET .../cloud-files/{fileID}/page`	用户访问预览的 iframe 入口	访问预览文件
`GET {endpoint_url}/files/{fileId}`	接入方实现的元信息回调	获取文件元信息-预览文档
`GET {endpoint_url}/users/current/info`	接入方实现的当前用户回调	见 SDK 接入文档

七、小结

一句话总结：上传完成后异步预热、按版本号管理 fileId、失败只记日志不阻塞业务，就能在不增加用户感知延迟的前提下覆盖绝大多数预览场景。

容易踩坑的就两个：缓存按 fileId 维度建立、文件内容变化必须换 fileId；下载链路必须对石墨服务端可达（详见防盗链设计指南）。这两条做对，预热接入基本不会出问题。

一、什么时候应该调用#

二、调用前的前置条件#

三、请求与响应#

四、缓存命中与失效#

五、失败处理#

六、与相关接口的关系#