直接使用SVG与Sprite引用SVG显示不一致问题排查

将组件内直接渲染的SVG图标迁移至Sprite后，多数图标显示效果一致，但少数图标出现显示差异——左侧为Sprite引用的图标，右侧为直接渲染的SVG（与Figma原始图标效果一致）：

直接渲染SVG代码 #

export const FooterIcon: React.FC = () => (
  <svg width="20" height="20" viewBox="0 0 20 20" fill="none" xmlns="http://www.w3.org/2000/svg">
    <mask id="path-1-inside-1_3642_58626" fill="white">
      <rect x="2" y="10" width="16" height="8" rx="1" />
    </mask>
    <rect x="2" y="10" width="16" height="8" rx="1" stroke="#969598" strokeWidth="4" mask="url(#path-1-inside-1_3642_58626)"
    />
    <circle cx="3" cy="8" r="1" transform="rotate(-180 3 8)" fill="#D3D3D5" />
    <circle cx="3" cy="5" r="1" transform="rotate(-180 3 5)" fill="#D3D3D5" />
    <circle cx="3" cy="2" r="1" transform="rotate(-180 3 2)" fill="#D3D3D5" />
    <circle cx="6.5" cy="2" r="1" transform="rotate(-180 6.5 2)" fill="#D3D3D5" />
    <circle cx="10" cy="2" r="1" transform="rotate(-180 10 2)" fill="#D3D3D5" />
    <circle cx="13.5" cy="2" r="1" transform="rotate(-180 13.5 2)" fill="#D3D3D5" />
    <circle cx="17" cy="2" r="1" transform="rotate(-180 17 2)" fill="#D3D3D5" />
    <path
      d="M16 5C16 4.44772 16.4477 4 17 4C17.5523 4 18 4.44772 18 5C18 5.55228 17.5523 6 17 6C16.4477 6 16 5.55228 16 5Z"
      fill="#D3D3D5"
    />
    <circle cx="17" cy="8" r="1" transform="rotate(-180 17 8)" fill="#D3D3D5" />
  </svg>
);

Sprite代码及引用方式 #

Sprite定义 #

<svg xmlns="http://www.w3.org/2000/svg">
    <symbol id="footer" viewBox="0 0 20 20" fill="none">
        <mask id="path-1-inside-1_3642_58626" fill="white">
          <rect x="2" y="10" width="16" height="8" rx="1" />
        </mask>
        <rect x="2" y="10" width="16" height="8" rx="1" stroke="#969598" stroke-width="4" mask="url(#path-1-inside-1_3642_58626)"
        />
        <circle cx="3" cy="8" r="1" transform="rotate(-180 3 8)" fill="#D3D3D5" />
        <circle cx="3" cy="5" r="1" transform="rotate(-180 3 5)" fill="#D3D3D5" />
        <circle cx="3" cy="2" r="1" transform="rotate(-180 3 2)" fill="#D3D3D5" />
        <circle cx="6.5" cy="2" r="1" transform="rotate(-180 6.5 2)" fill="#D3D3D5" />
        <circle cx="10" cy="2" r="1" transform="rotate(-180 10 2)" fill="#D3D3D5" />
        <circle cx="13.5" cy="2" r="1" transform="rotate(-180 13.5 2)" fill="#D3D3D5" />
        <circle cx="17" cy="2" r="1" transform="rotate(-180 17 2)" fill="#D3D3D5" />
        <path
          d="M16 5C16 4.44772 16.4477 4 17 4C17.5523 4 18 4.44772 18 5C18 5.55228 17.5523 6 17 6C16.4477 6 16 5.55228 16 5Z"
          fill="#D3D3D5"
        />
        <circle cx="17" cy="8" r="1" transform="rotate(-180 17 8)" fill="#D3D3D5" />
    </symbol>
</svg>

引用代码 #

<svg width={size} height={size}>
  <use xlinkHref={`${icons}#${variant}`} />
</svg>

原因分析 #

核心问题是mask的ID全局冲突：

• 直接渲染时，mask的ID仅在当前SVG的局部作用域内生效，浏览器能精准匹配到对应mask；
• 当多个图标放入同一个Sprite文件时，若不同图标使用了相同的mask ID（比如这里的path-1-inside-1_3642_58626），浏览器会优先匹配第一个出现的同名mask，导致后续图标错误应用了其他图标的mask，最终显示异常。

另外，直接渲染SVG中strokeWidth是驼峰写法，Sprite中改为了stroke-width，这不是核心问题（SVG属性支持两种写法），但统一写法能减少潜在问题。

修复方案 #

1. 为Sprite内的mask设置唯一ID #

给每个<symbol>内的mask添加图标相关前缀，确保ID全局唯一：

<symbol id="footer" viewBox="0 0 20 20" fill="none">
    <mask id="footer-mask-path-1" fill="white">
      <rect x="2" y="10" width="16" height="8" rx="1" />
    </mask>
    <rect x="2" y="10" width="16" height="8" rx="1" stroke="#969598" stroke-width="4" mask="url(#footer-mask-path-1)"
    />
    <!-- 其他元素保持不变 -->
</symbol>

2. 统一SVG属性写法 #

将Sprite中的stroke-width改为和直接渲染一致的strokeWidth，保持代码风格统一。

3. 验证Sprite引用路径 #

确保${icons}变量指向的Sprite文件路径正确，避免因路径错误导致的图标加载异常。

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