SVG无法遮罩图片问题求助（React+CSS Modules环境）

1. SVG遮罩结构不规范 #

SVG遮罩必须通过<mask>元素包裹遮罩图形，且需配置正确的坐标单位，同时给遮罩设置唯一ID供引用。直接放置<rect>无法起到遮罩作用：

• 错误示例：

<!-- 无<mask>包裹，仅作为普通图形存在 -->
<svg>
  <rect x="0" y="0" width="100%" height="100%" fill="rgba(0,0,0,0.5)" />
</svg>

• 正确结构：

<!-- 设为0宽高并绝对定位，避免占用布局空间 -->
<svg width="0" height="0" style="position:absolute;">
  <mask id="imageMask">
    <!-- 用黑白色阶控制透明度：白色完全显示，黑色完全隐藏，灰色对应半透明 -->
    <rect x="0" y="0" width="100%" height="100%" fill="#888" />
    <rect x="20%" y="20%" width="60%" height="60%" fill="#fff" />
  </mask>
</svg>

2. 内联样式中mask属性语法错误 #

React内联样式里的mask属性需正确引用SVG遮罩，且要兼容Webkit前缀，同时需指定遮罩模式确保透明度生效：

• 错误写法：仅添加webkitMask但未配置模式，导致图片消失
• 正确写法：

<img
  src="/your-image.jpg"
  style={{
    width: '100%',
    height: 'auto',
    mask: 'url(#imageMask)',
    WebkitMask: 'url(#imageMask)',
    maskMode: 'alpha', // 强制使用遮罩的透明度控制图片显示
    WebkitMaskMode: 'alpha'
  }}
/>

3. CSS Modules的ID作用域冲突 #

CSS Modules会自动修改DOM元素的ID以实现样式隔离，若SVG是组件内元素，其遮罩ID会被重命名（如imageMask_abc123），但内联样式仍引用原ID，导致遮罩无法匹配。
解决方法：

• 将SVG放置在全局作用域（如public/index.html），避免ID被重命名；
• 用useRef动态获取遮罩ID，生成正确引用路径：

import { useRef, useEffect, useState } from 'react';

function MaskedImage() {
  const maskRef = useRef(null);
  const [maskUrl, setMaskUrl] = useState('');

  useEffect(() => {
    if (maskRef.current) {
      setMaskUrl(`url(#${maskRef.current.id})`);
    }
  }, []);

  return (
    <>
      <svg width="0" height="0" style={{position: 'absolute'}}>
        <mask ref={maskRef} id="imageMask">
          <rect x="0" y="0" width="100%" height="100%" fill="rgba(0,0,0,0.3)" />
          <rect x="10%" y="10%" width="80%" height="80%" fill="rgba(0,0,0,0.8)" />
        </mask>
      </svg>
      <img
        src="/test.jpg"
        style={{
          width: '500px',
          height: 'auto',
          mask: maskUrl,
          WebkitMask: maskUrl,
          maskMode: 'alpha'
        }}
      />
    </>
  );
}

4. 遮罩尺寸与图片不匹配 #

部分浏览器需明确配置遮罩的单位规则，确保遮罩尺寸适配图片：

<mask id="imageMask" maskUnits="objectBoundingBox" maskContentUnits="objectBoundingBox">
  <!-- 用0-1的相对值设置尺寸，自动适配图片 -->
  <rect x="0" y="0" width="1" height="1" fill="rgba(0,0,0,0.5)" />
</mask>

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