CSS mask-position 完全指南：精准控制遮罩图像在元素内的定位

本文详解 CSS mask-position 属性的语法规则、坐标逻辑与常见误区，结合 radial-gradient 和 linear-gradient 实战案例，帮助开发者实现如左对齐半圆镂空、边缘渐隐、聚光灯等精确可控的遮罩效果。

本文详解 CSS `mask-position` 属性的语法规则、坐标逻辑与常见误区，结合 `radial-gradient` 和 `linear-gradient` 实战案例，帮助开发者实现如左对齐半圆镂空、边缘渐隐、聚光灯等精确可控的遮罩效果。

CSS 遮罩（mask）是一种强大的视觉控制机制，它不像 clip-path 那样仅裁剪形状，而是通过“蒙版图像”（如渐变或位图）定义元素的透明度分布——其中不透明区域显示内容，透明区域隐藏内容。而 mask-position 正是决定该蒙版图像相对于元素边界如何摆放的关键属性。

但需注意一个关键前提：mask-position 仅对独立的遮罩图像生效；当遮罩由 mask: radial-gradient(...) 这类简写声明直接内联定义时，mask-position 将被忽略——因为此时渐变的定位信息已内嵌在函数参数中（即 at <position>）。这也是你原始示例未生效的根本原因：

/* ❌ 无效：mask-position 对内联 radial-gradient 无作用 */div {mask: radial-gradient(20px, transparent 100%, black);mask-position: left center; /* 被忽略 */}

✅ 正确做法是将定位信息直接写入 radial-gradient() 的 at 参数中：

/* ✅ 有效：在渐变函数内指定位置 */div {background: green;mask: radial-gradient(50px at left center, transparent 100%, black);/* 等价于：50px 半径的圆形遮罩，中心点锚定在元素左边缘 + 垂直居中处 */}body { background: pink; }

<div style="width: 300px; height: 200px;"></div>

? mask-position 的定位逻辑解析

mask-position 的值遵循与 background-position 相同的语法规范，其默认参照盒为 border-box（可通过 mask-origin 修改）。支持以下形式：

写法	含义	示例
单关键字	水平+垂直均设为该值（center 默认补全）	mask-position: top; → top center
关键字组合	第一值为水平（left/center/right），第二值为垂直（top/center/bottom）	mask-position: left center;
百分比/长度	第一值为 X 偏移（从左起），第二值为 Y 偏移（从上起）	mask-position: 20% 50%;
混合写法	关键字 + 数值（顺序仍为 X Y）	mask-position: left 30px;

注意事项：

1. 若使用多个遮罩层（逗号分隔的 mask-image 列表），mask-position 也需用逗号对应提供多个位置值；
2. Safari 等旧版 WebKit 浏览器需添加 -webkit-mask-position 前缀；
3. mask-position仅在 mask-image 显式声明为独立值时才生效（例如 mask-image: url(mask.png) 或 mask-image: linear-gradient(...)），否则应优先使用渐变函数内的 at 语法。

? 实用技巧：三种典型定位场景

1. 左侧半圆镂空（你的需求）

.masked-left-half {width: 300px; height: 200px;background: #2ecc71;mask: radial-gradient(80px at left center, transparent 0%, black 100%);}

→ at left center 将渐变中心锚定在元素左边界中点，半径 80px 覆盖左侧约 1/3 区域，形成自然“挖空”效果。

2. 右侧聚光灯（动态聚焦）

.spotlight-right {mask: radial-gradient(circle at right 20px center, black 0%, transparent 60%);}

→ at right 20px center 表示从右边缘向内偏移 20px、垂直居中，适合模拟右侧光源照射。

3. 全向边缘渐隐（平滑融合背景）

.soft-edge {mask: linear-gradient(90deg,transparent 0%, black 15%, black 85%, transparent 100%);/* 注意：此处无需 mask-position —— 线性渐变默认铺满，若需偏移可用： *//* mask-position: 10% center; mask-size: 120% 100%; */}

✅ 总结：何时用 mask-position？何时用 at？

场景	推荐方案	原因
使用外部 PNG/SVG 遮罩图	✅ mask-image: url(...); mask-position: left top;	图像需独立定位
使用 linear-gradient 或 radial-gradient	✅ 渐变函数内写 at <position>	更直观、更可靠、兼容性更好
多层遮罩（如渐变+图片叠加）	✅ 组合使用：mask-image: linear-gradient(...), url(...); mask-position: center, right top;	各层可独立控制位置

掌握 mask-position 与渐变 at 语法的分工与协作，是实现专业级 CSS 遮罩效果的基础。记住核心原则：定位信息越靠近数据源（即渐变函数本身），控制越精准、行为越可预测。