SVG <use>标签无法渲染渐变样式的原因及解决方法

问题根源 #

Chrome和Edge对外部SVG通过<use>引用时的ID作用域处理逻辑与Firefox不同：外部SVG内的url(#lg1)原本指向自身文档的渐变定义，但<use>会将外部内容加载到当前页面的shadow DOM中，此时url()会在主文档上下文查找ID，而非外部SVG的上下文，导致渐变无法被找到。Firefox则会保留外部SVG的ID作用域，所以能正常渲染。

解决方案 #

方案1：将外部SVG内容内联到当前文档

把外部SVG的所有定义（包括渐变）和需要引用的元素复制到当前页面的隐藏SVG的<defs>中，让元素与渐变处于同一文档上下文，确保ID引用正常生效。

示例代码：

<!-- 隐藏的内联SVG，存放渐变和元素定义 -->
<svg style="position: absolute; width: 0; height: 0; visibility: hidden;">
  <defs>
    <linearGradient id="lg1" x1="0%" y1="0%" x2="100%" y2="100%">
      <stop offset="0%" stop-color="#ff0000" />
      <stop offset="100%" stop-color="#00ff00" />
    </linearGradient>
    <rect id="gradientRect" width="200" height="100" fill="url(#lg1)" />
  </defs>
</svg>

<!-- 使用<use>引用内联的元素 -->
<svg width="200" height="100">
  <use href="#gradientRect" />
</svg>

方案2：在当前文档中引用外部SVG的渐变

如果不想内联整个SVG，可在当前页面的<defs>中通过href引用外部SVG的渐变，让<use>加载的元素能在主文档上下文找到对应的渐变ID。

当前页面代码：

<svg style="position: absolute; width: 0; height: 0; visibility: hidden;">
  <defs>
    <!-- 引用外部SVG的渐变 -->
    <linearGradient id="lg1" href="external.svg#lg1" />
  </defs>
</svg>

<!-- 引用外部SVG的矩形元素 -->
<svg width="200" height="100">
  <use href="external.svg#gradientRect" />
</svg>

外部SVG（external.svg）内容：

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 200 100">
  <defs>
    <linearGradient id="lg1" x1="0%" y1="0%" x2="100%" y2="100%">
      <stop offset="0%" stop-color="#ff0000" />
      <stop offset="100%" stop-color="#00ff00" />
    </linearGradient>
  </defs>
  <rect id="gradientRect" width="200" height="100" fill="url(#lg1)" />
</svg>

方案3：用CSS变量传递渐变定义

这种方式更灵活，兼容<use>和<object>/<embed>两种引用场景：外部SVG单独使用时用自身的渐变，通过<use>引用时则使用当前页面定义的渐变。

外部SVG（external.svg）内容：

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 200 100">
  <style>
    .gradient-rect {
      /* 默认使用自身的渐变，可被CSS变量覆盖 */
      fill: var(--gradient, url(#lg1));
    }
  </style>
  <defs>
    <linearGradient id="lg1" x1="0%" y1="0%" x2="100%" y2="100%">
      <stop offset="0%" stop-color="#ff0000" />
      <stop offset="100%" stop-color="#00ff00" />
    </linearGradient>
  </defs>
  <rect id="gradientRect" class="gradient-rect" width="200" height="100" />
</svg>

当前页面代码：

<style>
  /* 定义CSS变量，指向当前页面的渐变 */
  .svg-wrapper {
    --gradient: url(#lg1);
  }
</style>

<svg style="position: absolute; width: 0; height: 0; visibility: hidden;">
  <defs>
    <linearGradient id="lg1" x1="0%" y1="0%" x2="100%" y2="100%">
      <stop offset="0%" stop-color="#ff0000" />
      <stop offset="100%" stop-color="#00ff00" />
    </linearGradient>
  </defs>
</svg>

<div class="svg-wrapper">
  <svg width="200" height="100">
    <use href="external.svg#gradientRect" />
  </svg>
</div>

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