在线预览时Word图片不显示的排查路径：从文档结构到缓存版本的四层核对
上传Word文档后在线预览文字正常、图片空白，下载原文件却完好无损。这说明问题出在上传到预览之间的处理链路。本文按文档结构、转换服务、前端渲染、缓存版本四个环节，提供一套可顺序执行的排查方法，帮助定位图片丢失的具体位置。
一、先判断问题出在哪个阶段
遇到预览图片空白，第一步不是急着改代码，而是先区分两种表现：
图片区域完全没有占位元素：通常意味着转换阶段就没有提取出图片资源，后端拿到的文档解析结果里压根没有图片。
占位元素存在但始终加载不出内容：说明转换阶段可能已经识别到图片位置，问题更可能出在前端加载环节。
这个初步判断能帮你把排查范围缩小一半。接下来按顺序核对四个层面。
二、第一层：核对文档本身的图片存放方式
Office文档本质上是一个压缩包。图片在文档里可能有两种存在形式：
嵌入方式：图片数据直接存放在文档内部的媒体目录中。
链接方式：文档里只有一个指向外部路径的引用，图片数据并不在文档内。
如果作者当初插入图片时选择的是“链接到文件”，那么转换服务读取文档时自然取不到图片数据。这不是转换程序的问题，而是文档结构本身就没有把图片带进来。
核对方法：把文档后缀改为压缩包格式后解压，查看媒体目录下是否存在对应图片文件，同时检查关系文件中的引用条目是否完整。关系文件缺失或指向错误，都会让转换程序认为这份文档没有图片。
三、第二层：核对转换服务的资源提取策略
转换程序读取文档后，通常会把图片释放到一个资源目录，并在生成的预览页面中写入引用路径。这一步常见的问题包括：
资源目录生成了，但引用路径与实际存放位置不一致；
大小写差异导致路径匹配失败；
层级多一层或少一层，前端按路径找不到文件。
核对方法：打开转换日志，确认提取到的图片数量与文档内实际数量是否一致。再对照生成的页面源码，看每个图片地址能否在资源目录中找到对应文件。数量对不上，说明提取阶段有遗漏；数量对得上但路径找不到，说明引用写入环节有偏差。
四、第三层：核对前端渲染的加载与占位逻辑
图片地址正确，前端仍可能因为以下原因加载失败：
路径重写规则导致实际请求地址被改变；
跨域限制拦截了图片请求；
访问权限配置不允许当前用户读取资源文件。
核对方法：在浏览器开发者工具中查看图片请求的返回状态。如果是403或404，说明请求根本没有拿到资源；如果是200但内容为空，则要检查资源文件是否在传输过程中被截断。
此外，部分预览组件对占位图的处理策略是“失败后不再重试”。这种情况下，即使后端后来恢复正常，页面也不会自动补图，需要手动刷新或重新触发渲染。
五、第四层：核对缓存与版本绑定
旧版本的预览结果可能被缓存下来。新上传的文档虽然已经重新转换，但页面读取的仍是旧缓存中的资源清单，于是出现文字更新、图片沿用旧状态的现象。
核对方法：查看缓存键是否包含文档版本号或修改时间。如果缓存键只与文档ID绑定，而没有区分版本，就容易出现新旧资源混用。必要时手动清理该文档对应的缓存条目，再重新触发一次转换。
六、按顺序执行的排查清单
把以上四层整理成一份可复用的检查清单：
解压原文档：确认图片是嵌入还是链接，关系文件是否完整。
查看转换日志：核对提取数量与资源目录中的实际文件数。
检查浏览器请求：在开发者工具中查看图片请求的状态码与响应内容。
确认缓存键：检查缓存是否与文档版本号或修改时间绑定。
每一步都留下记录，就能把偶发故障变成可复用的检查项。it数运在网站维护中处理这类问题时，会把每次核对的结果按文档、转换、渲染、缓存四个环节归档，形成一份可追溯的检查记录，下次遇到类似反馈就能直接按顺序比对，减少反复试错的时间。
结语
在线预览图片不显示，问题往往不在文件本身，而在处理链路的某一个环节。按“文档结构→转换提取→前端加载→缓存版本”的顺序逐层核对，大多数情况下都能定位到具体原因。把每次排查的结果记录下来，下一次遇到同类问题时，就不需要从零开始猜测。
