本地能打开PDF，部署到/portal/后只剩空白区域。排查时需要分别确认：ComPDF运行资源是否存在、PDF能否读取、容器是否可见、许可是否适用。
200响应也可能是错误资源
在浏览器网络面板重新加载页面，检查SDK资源与PDF请求的地址、Content-Type和响应内容。单页应用可能把不存在的资源回退成index.html，此时状态是200，内容却不是脚本或PDF。
资源404或返回HTML，先修正发布目录和路由回退。PDF返回401、403，则检查用户权限或临时地址是否失效。两类问题需要分别处理。
对齐运行资源和path
ComPDF Web SDK的运行文件需要随应用发布。React集成包含资源复制步骤；部署说明用于核对当前版本的运行目录与配置。
本篇以应用部署在/portal/为例，实际SDK资源位于/portal/webviewer/，初始化地址就应与这个部署结果匹配。构建工具的base、静态文件复制目录与SDK的path不是同一个设置。检查构建产物和浏览器实际请求，不只检查源码里的路径。
先用固定教学PDF跑通，再接业务下载接口。这样能把SDK部署与业务授权问题分开定位。
请求正常后，检查布局与许可
确认容器有明确宽高。弹窗未展开或父节点高度为0时，阅读器可能已加载，页面却没有显示空间。检查从隐藏到显示、窗口缩放后的布局。
许可错误单独记录，并核对产品、版本和部署条件。不要把每种失败都显示成"PDF损坏"，也不要把开发环境可用直接当成正式域名可用。
本次子路径构建结果
本次用React 19.2.0、Vite 7.1.9和ComPDF Web SDK 2.9.4构建教学工程，将base设为/portal/，运行资源实际位于该路径下的webviewer/。浏览器访问子路径后成功显示两页教学文件。
这个结果只验证该版本与本地教学部署。正式域名的许可、代理和业务下载接口仍要分别核对，不能由本地成功推断线上环境已经通过。
留下一份可复查的部署记录
不要只写"部署已修好"。记录构建工具版本、SDK版本、应用base、实际资源目录、打开文件地址与重开结果。资源请求返回HTML时，记录响应类型与内容；许可失败则保留对应错误，不能混成同一个"白屏"原因。
图：本轮教学输入的实际检查结果；适用范围与未通过项见正文。
用实际访问方式检查
覆盖根路径、子路径、直接刷新路由、登录失效和错误文件。每次核对页面标题、PDF首页与下载对象，确认都属于同一文档。
部署记录至少留下SDK版本、资源目录、访问路径及错误信息，方便升级后复查。准备正式集成时，可先通过Web SDK核对所需功能和授权条件；先跑通目标环境，再评估替换现有预览方案的成本。