Flutter Web部署至Firebase Hosting后SVG图片无法显示问题

问题特征 #

• 本地localhost调试环境下SVG可正常加载渲染
• 分别使用html、canvaskit两种渲染模式构建部署后，SVG均无法显示
• 浏览器控制台网络面板显示SVG资源请求返回200，资源已完整下载，但页面无对应渲染内容
• 项目使用flutter_svg包处理SVG资源加载

排查及修复步骤 #

1. 修复Firebase Hosting的SVG MIME类型配置（最高概率根因） #

Firebase Hosting默认配置可能给SVG资源返回错误的Content-Type响应头，flutter_svg只有识别到响应头为image/svg+xml时才会正常解析渲染，哪怕资源内容下载完整，类型不匹配也会直接跳过渲染。
修复方式：

• 打开项目根目录下的firebase.json配置文件，在hosting节点添加SVG资源的自定义响应头配置，参考如下：

{
  "hosting": {
    "public": "build/web",
    "ignore": [
      "firebase.json",
      "**/.*",
      "**/node_modules/**"
    ],
    "headers": [
      {
        "source": "**/*.svg",
        "headers": [
          {
            "key": "Content-Type",
            "value": "image/svg+xml"
          }
        ]
      }
    ]
  }
}

• 保存配置后重新执行构建、部署流程：

flutter build web --release
firebase deploy --only hosting

• 部署完成后打开浏览器开发者工具，检查任意SVG资源的响应头，确认Content-Type值为image/svg+xml即配置生效。

2. 校验资源路径大小写一致性 #

本地调试环境（Windows/macOS默认文件系统）对文件路径大小写不敏感，但Firebase Hosting托管的静态资源严格区分大小写：

• 逐一核对代码中引用的SVG资源路径、pubspec.yaml中声明的资源路径、项目目录下实际SVG文件的文件名/目录名大小写，三者必须完全一致。例如代码写的是assets/Icon/Home.svg，实际文件名为home.svg就会出现资源下载成功但无法匹配渲染的问题。
• 构建完成后检查build/web/assets目录下的SVG文件路径，确认和代码引用完全对应。

3. 排查内容安全策略（CSP）拦截 #

如果Firebase Hosting配置了自定义CSP响应头，未放开对应权限的话，flutter_svg在Web端渲染SVG时会被浏览器安全策略拦截：

• 在firebase.json的headers配置中，调整CSP规则至少包含以下权限：

Content-Security-Policy: default-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob:;

• 部署后检查浏览器控制台是否有CSP相关报错，按需调整规则即可，不建议直接关闭CSP。

4. 调整Web构建参数兼容SVG渲染 #

如果以上配置都验证通过仍无法显示，调整构建参数适配flutter_svg的Web端渲染逻辑：

• html渲染模式构建命令（flutter_svg在html模式下原生兼容性更好，优先测试）：
  flutter build web --release --web-renderer html
• canvaskit渲染模式构建命令，指定使用本地打包的canvaskit资源避免跨域或缓存问题：
  flutter build web --release --web-renderer canvaskit --dart-define=FLUTTER_WEB_CANVASKIT_URL=/canvaskit/

快速验证技巧：部署完成后直接在浏览器地址栏访问线上SVG资源的完整路径，如果浏览器本身都无法正常展示SVG内容，优先排查MIME类型配置和资源本身问题；如果浏览器直接访问SVG正常，再排查Flutter代码侧的资源引用和渲染配置。

内容的提问来源于stack exchange，提问作者Szunyogh Tamás