Flutter Web部署Firebase后Syncfusion PDF Viewer显示灰色屏幕求助

排查与修复步骤 #

1. 确认PDF文件路径与打包配置 #

• 调试模式的本地路径在部署后可能失效，确保PDF文件通过pubspec.yaml的assets字段正确声明，加载时使用AssetSource指定相对路径，示例：

  SfPdfViewer.asset('assets/sample.pdf')
  

• 执行flutter build web --release后，检查build/web/assets目录下是否存在目标PDF文件，缺失则重新打包。

2. 校验pdfjs脚本的引入正确性 #

• 确保index.html中pdfjs脚本在main.dart.js之前加载，版本与Syncfusion要求兼容（推荐使用官方指定的稳定版本），示例配置：

  <!-- 放在main.dart.js之前 -->
  <script src="https://cdnjs.cloudflare.com/ajax/libs/pdf.js/3.4.120/pdf.min.js"></script>
  <script>
    pdfjsLib.GlobalWorkerOptions.workerSrc = "https://cdnjs.cloudflare.com/ajax/libs/pdf.js/3.4.120/pdf.worker.min.js";
  </script>
  <script src="main.dart.js" type="application/javascript"></script>
  

• 避免使用本地pdfjs文件，部署后可能因路径问题加载失败。

3. 调整Firebase Hosting缓存与部署配置 #

• 部署前必须执行flutter build web --release生成正式产物，再运行firebase deploy。
• 修改firebase.json添加缓存规则，防止脚本或PDF文件被缓存导致旧资源加载：

  {
    "hosting": {
      "public": "build/web",
      "ignore": [
        "firebase.json",
        "**/.*",
        "**/node_modules/**"
      ],
      "headers": [
        {
          "source": "**/*.{js,css,pdf}",
          "headers": [{"key": "Cache-Control", "value": "no-cache, no-store, must-revalidate"}]
        }
      ]
    }
  }
  

4. 查看浏览器控制台定位报错 #

• 部署后打开浏览器开发者工具（F12），切换到Console标签页，查看具体错误：
  • 显示404说明PDF或脚本路径错误；
  • 出现CORS报错需处理跨域问题；
  • 脚本执行错误则检查pdfjs版本兼容性。

5. 处理跨域PDF加载问题 #

• 若加载外部服务器的PDF，目标服务器需开启CORS；或在Firebase Hosting中配置代理：

  {
    "hosting": {
      "rewrites": [
        {
          "source": "/pdf/**",
          "destination": "https://your-pdf-server.com/**",
          "type": "proxy"
        }
      ]
    }
  }
  

  之后通过/pdf/sample.pdf路径加载PDF。

内容的提问来源于stack exchange，提问作者Xordelish