Canvas圆角矩形绘制指南：roundRect API与手写Path全解析

做 H5 交互页的时候，我经常要跟 Canvas 打交道。不管是游戏里的血条、头像框、抽奖卡片，还是绘图引擎里最基本的图元输出，圆角矩形几乎是绕不开的一块积木。但说真的，画一个圆角矩形这件事，很多人都是“能画出来”和“画得对”之间反复横跳。ctx.roundRect？手动拼 Path？四个角半径不一样怎么处理？圆角太大了会不会炸？这些问题如果不在动手前想清楚，后面每一步都在填坑。这篇文章就围绕 Canvas 画圆角矩形的参数、步骤和高级技巧展开，把我实际项目里踩过的坑、用顺手的方法都写出来。适合正在写 Canvas 游戏、自绘 UI、或者做 H5 动效页面的同学参考。

1. 画圆角矩形前，先想清楚它到底难在哪

1.1 圆角矩形不是“四个圆弧拼起来”这么简单

圆角矩形的本质是四条直线段加四段圆弧。如果只是追求视觉效果，有个偷懒办法：用ctx.arc()画四个角，中间用lineTo接起来。可问题在于，角度稍微一偏，圆弧和直线之间就容易出现重叠或者裂缝。尤其在 Canvas 游戏里，你需要逐帧绘制大量不同尺寸的圆角卡片，路径一多，这种手工拼法很快就会露馅。

更深一层的问题是，填充和描边的边界处理完全不一样。fill只要路径闭合，视觉上基本没问题；stroke会把每一条路径线段和圆弧的交接处，按lineJoin的要求单独处理。如果你把圆角矩形拆成独立的直线和圆弧，lineJoin的设定会影响每一个拐角，稍微没处理好，外边框就会多出一个尖角或者缺口。所以我一直强调，真正可靠的方案是让路径本身首尾相连、按标准顺序走完，而不是“看起来差不多”。

1.2 先按使用场景选择技术路线

在实际项目里，我一般先问自己三个问题：目标浏览器是否支持原生 API？圆角是四个角统一还是要单独控制？绘制频率高不高？

如果目标环境是较新的浏览器或 WebView，直接使用原生ctx.roundRect()是最省事的。如果项目需要兼容旧系统，或者要支持单边圆角、椭圆角这种高度定制需求，手写 Path 反而更灵活。还有一类情况：在 WebGL 或者轻量级 Canvas 绘图引擎里，想直接在 GPU 上画圆角矩形并不简单，通常会先在离屏 Canvas 上烘焙出一张贴图，再作为纹理贴上去。这条路线跟 API 关系不大，但思路可以复用。

我整理了一个简单的选型表，方便快速决策：

2. 原生 roundRect()：参数好记，边界条件不能想当然

2.1 参数逐项拆解

ctx.roundRect(x, y, width, height, radii)是 Canvas 2D API 提供的原生圆角矩形方法。前四个参数就是矩形左上角坐标和宽高，跟ctx.rect()完全一致。最后一个radii是重点：它既可以是数字，也可以是一个数组，甚至可以传包含{x, y}的 DOMPoint 对象。

如果传数字，四个角统一使用这个半径。如果传数组，数组长度从 1 到 4 分别对应不同角：

• 1 个值：四角相同。
• 2 个值：第一个值作用于左上角和右下角，第二个值作用于右上角和左下角。
• 3 个值：第一个给左上角，第二个给右上角和左下角，第三个给右下角。
• 4 个值：按左上、右上、右下、左下顺序排列。

这个顺序跟 CSS 的border-radius是一致的，记住之后就不用每次现查。真正容易踩坑的是“二值数组”的语义：它不是“上边两个角各设多少”，而是对角线分组。如果你只是想给左上角和右上角设置不同半径，直接写[20, 10, 0, 0]更稳妥，不要用二值数组去猜。

DOMPoint 模式平时用得少，但知道它存在很有必要。比如想画一个“水平和垂直半径不一致”的椭圆角，可以这样传：ctx.roundRect(0, 0, 100, 60, { x: 20, y: 10 })。这个能力原生支持很自然，手写路径想模拟就会麻烦不少。

2.2 负数、零和超出边界的半径

规范里，负的半径会被当作 0 处理，0 就是直角。真正容易出问题的是半径大于矩形短边一半的情况。例如一个100 x 50的矩形，你把 radius 设置成 40，理论上四个 40px 的圆弧会互相打架。标准做法是等比缩放每个角的半径，让曲线仍然平滑，但不同浏览器对极端值的表现会有细微差异，测试时不能只看 Chrome。

我的习惯是传入之前先自己 clamp 一次：

const maxR = Math.min(width, height) / 2; const safeR = Math.min(radius, maxR);

虽然 API 内部大概率也会做处理，但程序里有个明确的边界，排查问题时能少很多“为什么这个角翘起来了”的疑惑。尤其是做动效时，半径是从外部传入的变量，某帧数据稍微越界，画面就会突然变丑，提前 clamp 可以避免这种偶发故障。

width 或 height 为负时也一样。roundRect会沿负方向画矩形，但路径方向和圆角位置会反过来。如果你只是fill，可能看不出问题；一旦用stroke或者给路径加阴影，方向不同带来的差异就变得明显。遇到非正的宽高，我建议先归一化坐标，再用正宽高去画，不要指望 API 帮你处理。

2.3 路径状态：roundRect 不会替你 beginPath

初学者最容易忽略的是：roundRect只是往当前路径对象里加了一个子路径，它不会调用beginPath，也不会保存和恢复上下文状态。如果你在同一个 Canvas 上先画了一条线，又直接调用roundRect再fill，这两段路径会被当成同一块图形处理，轻则颜色混在一起，重则整块区域被错误填充。

所以每次绘制前，先问自己一句“这条路径跟上一帧有没有关系”。大多数情况下，你想要的都是独立圆角矩形，那就老老实实ctx.beginPath()。另外，roundRect生成的子路径是闭合的，路径起点在左上角，终点也会回到左上角附近，不需要额外closePath。

兼容性方面，原生roundRect从 2022 年前后在主流浏览器里逐渐普及，桌面端问题不大，但移动端旧 WebView 仍是重灾区。写公共组件时我建议做能力检测：

if (typeof ctx.roundRect === 'function') { ctx.roundRect(x, y, width, height, radii); } else { drawRoundRectPath(ctx, x, y, width, height, radii); }

把兜底方案藏在同一个入口后面，业务层不需要感知差异。

3. 手写圆角矩形路径：兼容旧环境也能玩出花

3.1 用 arcTo 把四个角拼起来

手写圆角矩形的关键不是arc，而是arcTo。arc需要你算圆心、起始角度和结束角度，四个角就是四套坐标加四套角度，极易算错；arcTo只需要提供“两个控制点”和半径，它会基于当前点自动补一条切线圆弧，语义更接近“给直角倒圆角”。

路径可以从左上角圆弧的起点开始，也就是(x + r, y)，然后先向右画直线，到右上角圆弧的起点，用arcTo转弯，再继续向下。逐角处理，最后closePath收尾。推荐顺序：左上 -> 右上 -> 右下 -> 左下，方向为顺时针，符合大多数 Canvas 工具的默认填充规则。

具体代码可以这样写：

function drawRoundRect(ctx, x, y, w, h, r) { const maxR = Math.min(w, h) / 2; const radius = Math.max(0, Math.min(r, maxR)); ctx.beginPath(); ctx.moveTo(x + radius, y); ctx.lineTo(x + w - radius, y); ctx.arcTo(x + w, y, x + w, y + radius, radius); ctx.lineTo(x + w, y + h - radius); ctx.arcTo(x + w, y + h, x + w - radius, y + h, radius); ctx.lineTo(x + radius, y + h); ctx.arcTo(x, y + h, x, y + h - radius, radius); ctx.lineTo(x, y + radius); ctx.arcTo(x, y, x + radius, y, radius); ctx.closePath(); }

这个函数有两个细节值得注意。第一，我先把半径 clamp 到Math.min(w, h) / 2，避免过大的半径把路径压成麻花。第二，beginPath被放在函数内部，意味着每次调用都会开启一条新路径，这个设计适合“一次函数只画一个矩形”的场景。

3.2 四角不同半径怎么处理

很多场景只需要“顶边两个圆角”，比如弹窗卡片、标签页 tab。这种时候四个角共用同一个r就不合适了。数组版本的手写路径并不复杂，只要把每一段直线和圆弧的半径分开传就行。

function roundRectPath(ctx, x, y, w, h, radii) { const maxR = Math.min(w, h) / 2; let [tl, tr, br, bl] = Array.isArray(radii) ? radii : [radii, radii, radii, radii]; tl = Math.max(0, Math.min(tl, maxR)); tr = Math.max(0, Math.min(tr, maxR)); br = Math.max(0, Math.min(br, maxR)); bl = Math.max(0, Math.min(bl, maxR)); ctx.beginPath(); ctx.moveTo(x + tl, y); ctx.lineTo(x + w - tr, y); ctx.arcTo(x + w, y, x + w, y + tr, tr); ctx.lineTo(x + w, y + h - br); ctx.arcTo(x + w, y + h, x + w - br, y + h, br); ctx.lineTo(x + bl, y + h); ctx.arcTo(x, y + h, x, y + h - bl, bl); ctx.lineTo(x, y + tl); ctx.arcTo(x, y, x + tl, y, tl); ctx.closePath(); }

注意这里我对每个角都限制到Math.min(w, h) / 2，简单粗暴，但已经能覆盖绝大多数 UI 需求。如果要做非常极端的不等半径，还需要额外保证“同一条边上的两个半径之和不超过边长”，否则会出现负的直线段。我在处理“弹窗底部两个直角、顶部两个圆角”时，通常就是[12, 12, 0, 0]，逻辑非常清晰。

3.3 arc 和 quadraticCurveTo 能不能替代 arcTo

有人喜欢用ctx.arc()直接画四分之一圆，数学上完全可行，但可读性差。以右上角为例，圆心是(x + w - r, y + r)，从-90°到0°，代码一多就非常难维护。如果你想兼容更老的环境，arc()反而是最古老、最通用的一种思路。

还有一条偏方：用quadraticCurveTo画贝塞尔曲线模拟圆角。例如：

ctx.quadraticCurveTo(x + w, y, x + w, y + r);

控制点放在直角顶点，曲线会让角“软”下来。这个方法不是标准圆角，半径不能精确控制，但优点是代码极短，而且贝塞尔曲线本身非常平滑，在小型图标上几乎看不出跟圆弧的差别。我一般只在做简易占位图或者特殊形状标签时用。

3.4 椭圆角：原生 radius 和手动 scale 的取舍

原生roundRect的radii支持 DOMPoint，例如ctx.roundRect(x, y, w, h, { x: 20, y: 10 })，可以做出椭圆角。手写路径要模拟椭圆角，常见姿势是save+scale后画圆角矩形，但scale会把描边宽度也缩放，不是所有场景都能接受。

更可靠的做法是用ctx.ellipse()在四个角分别画椭圆弧，但这需要你精确控制每段弧的圆心和起止角。坦白说，日常项目里用椭圆角的频次并不高，我通常只在“要做异形弹窗”时才写这种函数，性能上没有惊喜，工程量倒是不小。如果你也遇到这个需求，建议优先保留原生roundRect的 DOMPoint 参数，把椭圆角作为高级特性单独封装，不要跟基础圆角混在一起。

4. 圆角矩形的高阶玩法：渐变、阴影、镂空和动效

4.1 给圆角矩形加渐变和阴影，但不能无脑加

圆角矩形填渐变，很多人直接设置fillStyle为createLinearGradient，然后fill。这个思路没问题，但要注意：渐变的坐标系是整个 Canvas，不是圆角矩形内部。如果你把多个圆角矩形放在不同位置，却想让它们共享同一套渐变方向，直接用createLinearGradient做不到，它只会按 Canvas 坐标计算颜色。

如果想让渐变跟随每个矩形走，最简单的做法是每次用矩形的本地坐标创建渐变：

const gradient = ctx.createLinearGradient(x, y, x, y + h); gradient.addColorStop(0, '#fff'); gradient.addColorStop(1, '#e5e5e5'); ctx.fillStyle = gradient;

阴影是另一个重灾区。shadowBlur、shadowColor用起来很顺手，但每帧修改shadowBlur会强制 Canvas 在绘制时做大量采样，帧率掉得很快。我的做法是：静态内容先画到离屏 Canvas，再drawImage贴回主画布；动态内容则尽量不用阴影，或者用一段半透明渐变模拟阴影，物理计算量要小得多。

4.2 镂空圆角矩形：一个哪怕没有官方方法也能做到的效果

镂空效果在抽奖转盘、仪表盘、遮罩蒙层里特别常见。思路是用evenodd填充规则：先画一个覆盖全屏的大矩形，再在里面画一个圆角矩形，填色时用“奇偶规则”，重叠区域就会被掏空。

ctx.beginPath(); ctx.rect(0, 0, canvas.width, canvas.height); roundRectPath(ctx, 100, 80, 200, 120, 16); ctx.fillStyle = 'rgba(0, 0, 0, 0.5)'; ctx.fill('evenodd');

用这个方式做蒙层，比save+clip+restore干净得多。clip方式需要先裁剪再绘制，如果你只是想盖一层半透明遮罩，fill('evenodd')一行就完成了。这个技巧在 Canvas 绘图引擎里尤其有用，因为引擎层经常要屏蔽“遮罩模版”的细节。

4.3 圆角半径的动态变化与单角动画

圆角矩形动效最常见的形态是“普通矩形”和“胶囊形”之间切换，也就是半径从 0 变化到短边一半。用requestAnimationFrame逐帧改半径，每次调用手写路径函数，就能得到很顺畅的过渡。这个过程的性能瓶颈不在路径计算，而在fill和stroke，所以不要每帧都新建渐变色对象。

function animateCard(canvas) { const ctx = canvas.getContext('2d'); let progress = 0; function tick() { progress += 0.02; const r = Math.abs(Math.sin(progress)) * 30; ctx.clearRect(0, 0, canvas.width, canvas.height); drawRoundRect(ctx, 40, 40, 200, 60, r); ctx.fillStyle = '#4f8ff7'; ctx.fill(); requestAnimationFrame(tick); } tick(); }

更精细的单角动画，比如弹窗底部两个角慢慢变成直角，可以用数组半径实现。动画里维护tl、tr、br、bl四个值，每一个都做线性插值，roundRectPath本身不用改。这里有一个经验：半径变化过程不要用固定公式硬套，因为不同屏幕尺寸下最大半径不一样，用“当前半径 / 最大半径”作为进度更容易统一。

4.4 高分屏、响应式布局怎么保证圆角不发虚

Canvas 在高分屏上发虚，几乎都是因为canvas.width没跟上设备像素比。正确做法是把 canvas 的位图尺寸设置成 CSS 尺寸乘以devicePixelRatio，再用ctx.scale(dpr, dpr)恢复逻辑坐标系。这样所有坐标和半径仍然用 CSS 像素写，圆角尺寸不会因为屏幕缩放而缩水。

function setupCanvas(canvas, cssWidth, cssHeight) { const dpr = window.devicePixelRatio || 1; canvas.width = cssWidth * dpr; canvas.height = cssHeight * dpr; canvas.style.width = cssWidth + 'px'; canvas.style.height = cssHeight + 'px'; const ctx = canvas.getContext('2d'); ctx.scale(dpr, dpr); return ctx; }

响应式布局时还需要注意：resize 后 Canvas 上下文会被重置，scale和transform全部恢复默认，需要重新设置。如果你把圆角半径写成固定值，在一些窄屏小卡片上可能出现半径大于短边一半的边界情况，所以计算半径时要结合当前矩形宽度动态取min。实测下来，只要把 clamp 逻辑放在公共函数里，这类问题基本能一次性解决。

5. 一个能直接上线的圆角矩形组件与填坑复盘

5.1 封装：优先原生，自动降级

把原生roundRect和手写路径揉进同一个入口，是维护起来最舒服的方式。下面这个drawRoundRect函数支持统一半径和数组半径，自动做能力检测，同时把fill、stroke、lineWidth暴露出来，按需使用。

function drawRoundRect(ctx, options) { const { x, y, width, height, radii, fill, stroke, lineWidth } = options; ctx.beginPath(); if (typeof ctx.roundRect === 'function') { ctx.roundRect(x, y, width, height, radii); } else if (Array.isArray(radii)) { roundRectPath(ctx, x, y, width, height, radii); } else { drawRoundRect(ctx, x, y, width, height, radii); } if (fill) { ctx.fillStyle = fill; ctx.fill(); } if (stroke) { ctx.strokeStyle = stroke; ctx.lineWidth = lineWidth || 1; ctx.stroke(); } }

这里有一个取舍：beginPath放在函数最前面，好处是调用方不用每次记得清理旧路径；坏处是如果你真的想在一个大路径里连续画多个圆角矩形，这种方式会打断路径。分页列表、图表柱状图这种场景，我一般会再提供一个不主动beginPath的变体，把控制权交还给调用方。

5.2 我实际踩过的几个坑

第一个坑是忘记beginPath。封装函数里我统一调用了一次，但在异步绘制或批量绘制 list 时，很容易在调用处又画了其他路径，最终填充出一团乱码。建议把beginPath的位置根据调用方式明确写进注释，不要让使用者猜。

第二个坑是数组半径的顺序。UI 同学给的视觉稿标注“左上 12、右上 12、右下 0、左下 0”，我一开始直接传[12, 12, 0, 0]，正好对上了原生的[tl, tr, br, bl]顺序。但如果你用的是[12, 0, 0, 12]这类非对称值，最好在函数文档里写清楚顺序，否则几个月后回来看代码很容易记错。这个坑尤其在多人协作的 Canvas 项目里常见。

第三个坑是stroke会把圆角外沿吃掉。Canvas 的描边是沿着路径中心线往两边扩展的，所以一个矩形如果fill是 100px 宽、stroke是 4px，实际视觉宽度会变成 104px。如果你要求整体尺寸严格不超界，可以先fill，再通过clip或偏移路径来画内描边。这个问题在圆角矩形上比直角矩形更隐蔽，因为圆弧处会显得特别粗。

第四个坑是雷达图、仪表盘这类图形里，圆角矩形经常被用来画刻度槽。刻度的头部和尾部如果都使用同一个半径，视觉上会显得不对称。正确做法是两端用不同半径的数组形式传入，例如[2, 8, 8, 2]，让刻度“一头尖一头圆”，观感会舒服很多。

5.3 性能实测的一点结论

我拿原生roundRect和手写roundRectPath在同一个项目里做过一次简单对比：连续绘制 1 万个半径为 8 的圆角矩形，两种方式的耗时差距在个位数毫秒以内，真正的开销基本都集中在fill操作的像素填充上。所以不要迷信“原生一定比手写快”，也不要觉得手写路径就很慢。

真正的性能问题出在高频动画和大量独立渐变上。如果你要在 Canvas 游戏里画几百个悬浮气泡，每个气泡都是圆角矩形加阴影，那最稳的方案是把气泡预先画到离屏 Canvas，再按位置drawImage，而不是每帧重新fill。离屏 Canvas 的额外内存大约等于位图宽乘高乘 4 字节，控制数量级之后是划算的。

如果目标平台是 WebGL 或混合渲染引擎，更常见的做法是提前把圆角矩形烘焙成一张四角透明的贴图，然后用矩阵变换贴到任意位置。这种方式跟 Canvas 2D 的 Path 完全是两条路线，但绘制速度会有质的提升。遇到渲染管线层面的圆角需求时，可以考虑直接切过去。

5.4 一点个人经验，不是标准答案

说了这么多，我最想强调的还是“先理解路径，再谈 API”。原生roundRect是个好东西，但它不是银弹；手写路径也不是老古董，它让你真正拥有对每个角、每条边的控制权。现在这个时代，做 Canvas 游戏和绘图引擎的同学越来越多，圆角矩形这种基础图元反而值得花时间打磨清楚。项目不忙的时候，我会把这类基础函数放到自己的工具库里反复调优，等下次真要用的时候，直接抄自己过去验证过的版本。最后再分享一个小习惯：调试圆角矩形时，先用ctx.strokeStyle = 'red'; ctx.stroke();把路径轮廓打出来，确认每个角的切点位置，再考虑填充和阴影。这个习惯帮我省下了大量“为什么圆角不圆”的排查时间。