mask-image聚光灯核心原理是用径向渐变遮罩“挖洞”并配合半透背景实现光照效果：通过CSS变量绑定鼠标坐标，结合mask-size、mask-repeat、mask-position三要素声明遮罩，且需兼容iOS前缀与高DPR缩放。
什么是 mask-image 聚光灯的核心原理
聚光灯效果本质是「只显示鼠标周围一个圆形区域，其余部分变暗」，mask-image 是最直接的实现方式：它用一张遮罩图控制元素哪些区域可见。配合 radial-gradient 生成圆形透明区 + 全黑背景，再用 CSS 变量动态更新圆心坐标，就能让“光圈”跟着鼠标走。
关键点在于：遮罩本身不发光，它只是“挖洞”；变暗靠的是给目标元素加一层半透黑色背景（比如 background: rgba(0,0,0,0.7)），而“洞”里透出原始内容——这样才像一束光打在页面上。
如何用 CSS 变量绑定鼠标坐标
CSS 本身不能读取鼠标位置，必须靠 JavaScript 把 clientX 和 clientY 写入自定义属性。常见错误是直接写成 style="--x: e.clientX"，但要注意单位和坐标系适配：
- 坐标值需转为像素单位（加
px），否则mask-position不识别 - 推荐用
document.documentElement的scrollLeft/scrollTop补偿滚动偏移，否则滚动后光圈错位 - 不要在
mousemove里频繁设 style —— 改用element.style.setProperty()更可控
示例 JS 片段：
document.addEventListener('mousemove', e => {
const x = e.clientX - window.scrollX;
const y = e.clientY - window.scrollY;
document.documentElement.style.setProperty('--x', `${x}px`);
document.documentElement.style.setProperty('--y', `${y}px`);
});
mask-image 声明中容易漏掉的三个细节
mask-image 单独写不会生效，必须配齐基础声明。漏掉任意一项都会导致遮罩完全不显示：
- 必须设置
mask-size: 300px 300px（或类似固定尺寸），否则radial-gradient默认铺满整个容器，光圈无法“聚焦” - 必须显式写
mask-repeat: no-repeat，不然圆形遮罩会平铺，出现多个光斑 - 必须加
mask-position: var(--x) var(--y)，且确保--x/--y已初始化（例如在 :root 里设--x: 50px; --y: 50px），否则首次渲染时位置异常
完整 CSS 遮罩声明长这样：
.spotlight {
mask-image: radial-gradient(circle at var(--x) var(--y), transparent 0%, black 60%);
mask-size: 300px 300px;
mask-repeat: no-repeat;
mask-position: var(--x) var(--y);
background: rgba(0,0,0,0.7);
}
移动端和高 DPR 屏幕下的兼容性陷阱
这个效果在桌面端流畅，但在 iOS Safari 或高分辨率屏上容易失效，原因很具体：
- iOS Safari 对
mask-image的支持要求-webkit-mask-image前缀，且必须同时存在（仅写标准属性无效） - 高 DPR 设备（如 MacBook Retina）下，
clientX/clientY返回的是逻辑像素，但遮罩尺寸是物理像素，导致光圈模糊或偏小——建议用window.devicePixelRatio缩放mask-size - 某些安卓 WebView 会忽略
mask-position的 CSS 变量，稳妥做法是 JS 中拼接完整mask-position字符串并直接写入 style
所以生产环境建议至少补上前缀：
.spotlight {
-webkit-mask-image: radial-gradient(circle at var(--x) var(--y), transparent 0%, black 60%);
mask-image: radial-gradient(circle at var(--x) var(--y), transparent 0%, black 60%);
}
光圈大小随设备缩放的逻辑，得在 JS 里做判断，而不是只靠 CSS 变量。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
