Canvas二次贝塞尔曲线绘制圆角矩形：原理、参数与性能实践

做可视化看板那几年，圆角矩形这个需求出现的频率高得离谱。卡片背景、按钮底、头像裁切、图表容器、提示气泡，全都要圆角。一开始我也图省事，直接四段arc拼，结果半径一改大就错位，斜接处还会冒出一条细缝；后来换arcTo，代码短了，但碰上"只圆上面两个角""四个角半径不一样""要把路径导出成 SVG"这类需求又开始别扭。折腾几轮之后，我基本固定用canvas 二次贝塞尔曲线绘制圆角矩形这套方案：四条直线加四段quadraticCurveTo，路径干净、点数可控、能直接塞进Path2D缓存，还能顺手改造成不规则圆角和超椭圆变体。这篇就把这套东西从几何原理、参数约束、代码落地到踩坑排查完整捋一遍，前端新手能照着抄，做过几年可视化的人也能在精度和性能这两块拿到点新东西。

1. 为什么圆角矩形最后都落到 quadraticCurveTo 上

1.1 三种画法的路线对比

Canvas 里画圆角矩形，能走的路其实就三条，我把它们放在一起对比过很多次，结论是有明确分工的，不是谁绝对比谁好。

第一条是arc拼圆角。思路最直白：四条直线加四段四分之一圆弧，每段圆弧用ctx.arc(cx, cy, r, startAngle, endAngle)单独指定圆心和起止角。问题在于圆心要自己算，四个角的圆心分别是(x+r, y+r)、(x+w-r, y+r)、(x+w-r, y+h-r)、(x+r, y+h-r)，起始角也得跟着角位调整。代码量大概是二次贝塞尔版本的两倍，而且一旦某个角的半径单独变化，角度判断就得重写一遍。我早期写过一版，维护成本很高，后来直接弃了。

第二条是arcTo。它接受两个切线端点和一个半径，浏览器自动帮你算圆弧，确实省事。标准写法四行就能画完一个圆角矩形，很多人也就是这么用的。但arcTo有个隐性的坑：它的行为依赖"当前点"和"第一个参数点"构成的切线方向，如果路径中间插了别的子路径，或者你在循环里复用同一个 ctx 而忘了beginPath，切线方向就错了，画出来的东西会莫名其妙地甩出去一条线。另外arcTo生成的是真正的圆弧段，路径点数比二次贝塞尔多，做Path2D缓存和高频isPointInPath检测时会稍微吃点亏。

第三条就是quadraticCurveTo。每段圆角只需要一次调用、三个点：起点（当前点）、控制点（角点本身）、终点。没有角度计算，没有切线方向推断，四个角的代码结构完全对称，复制粘贴改个坐标就行。这就是它在工程上最大的优势——结构对称意味着好维护、好参数化、好扩展。

1.2 二次贝塞尔画圆角的几何逻辑

很多人第一次看到quadraticCurveTo(x + w, y, x + w, y + r)这种写法会愣一下：控制点为什么放在角点上？答案其实很朴素——圆角在角点附近是"切"进去的，两条边在角点处相交形成一个直角，而圆角的弧线正是被这个直角"夹"出来的。把控制点放在两条边的交点（也就是矩形原始的尖角），曲线就会自然地被拉向那个方向，形成一段从水平边过渡到垂直边的平滑弧。

用生活里的东西打个比方：你手里有一根有弹性的细竹条，两端分别固定在水平边和垂直边的端点上，然后你用手指把竹条往尖角方向顶一下再松开，竹条弹回来的形状就是二次贝塞尔曲线。手指顶的位置就是控制点，顶得越靠近尖角，弧就越"鼓"、越接近直角；顶得越远，弧就越平。

这个直觉非常重要，因为它解释了后面所有的参数调整逻辑：控制点位置决定了圆角的"饱满度"。标准写法把控制点放在角点上，是"最鼓"的一种；如果你觉得圆角看起来比设计稿方了一点，唯一的调节手段就是别把控制点放在角点上，往回收一点。当然这样会破坏"半径等于 r"的语义，所以我一般不动控制点，而是直接换三次贝塞尔，这个在第 4 节展开。

1.3 什么时候该选它，什么时候不该

我给自己定的判断标准很简单：只要这个圆角矩形需要作为一条完整路径被复用——缓存成Path2D、参与clip裁剪、做命中检测、导出成 SVG 的d属性、或者后续还要跟别的路径做addPath合并——那就用二次贝塞尔。因为它是纯路径描述，没有任何"当前状态"依赖，把它包成一个函数，随便什么时候调用都能得到同样的结果。

反过来，如果是那种一次性画完就扔的场景，比如临时在某个 demo 里画个框，我可能直接arcTo四行了事，懒得写函数。另外，如果项目对圆弧精度有硬性要求（比如要做工业零件轮廓示意、要跟设计稿做像素级比对），那也应该绕开二次贝塞尔，直接上arc或者用三次贝塞尔的做法。

还有一点要说清楚：现代浏览器已经有原生的ctx.roundRect()了，参数是(x, y, w, h, radii)，radii 支持数字和数组，行为跟 CSS 的border-radius基本对齐。如果你的目标环境确定支持，直接用原生最省事。但它有两个现实约束：一是较老的浏览器版本没有，二是它在某些实现细节上（比如负半径、超大半径的收缩逻辑）跟老代码可能不一致。所以我现在的做法是：业务代码里优先探测ctx.roundRect，没有就回落到自己写的二次贝塞尔版本，两套逻辑保持一致的半径归一化规则，这样视觉上不会出现差异。

注意：不要在同一段绘制逻辑里混用原生roundRect和手写路径，两者的超大半径收缩策略不一样。比如w=100, h=40, r=50，手写版本如果不做约束会画出交叉的"麻花"，而原生版本会自动压成胶囊形。混用会导致同一个组件在不同浏览器上形状对不上。

2. 把圆角矩形拆成八段线段和四个控制点

2.1 顺时针走一圈的路径顺序

画路径这件事，最忌讳的就是"边画边想"。我的习惯是先在纸上把八个关键点标出来，确认顺序无误再动键盘。以左上角为(x, y)、宽w、高h、四角统一半径r为例，顺时针一圈的八个点是：

1. 上边起点：(x + r, y)
2. 上边终点：(x + w - r, y)
3. 右边起点：(x + w, y + r)
4. 右边终点：(x + w, y + h - r)
5. 下边起点：(x + w - r, y + h)
6. 下边终点：(x + r, y + h)
7. 左边起点：(x, y + h - r)
8. 左边终点：(x, y + r)

四段直线依次连接 1→2、3→4、5→6、7→8，四段曲线依次连接 2→3、4→5、6→7、8→1。每一段曲线的控制点就是它经过的那个角点，比如 2→3 这段的控制点是右上角(x + w, y)。

这个"八点四段"的结构一旦记住，后面加不规则半径、加单边缺口、改成超椭圆，全都只是在这个骨架上改坐标，不会乱。

路径方向为什么一定要顺时针？因为这牵涉到后面的closePath和填充规则。Canvas 默认用 nonzero（非零环绕）规则填充，如果同一个路径里既有顺时针的外圈又有顺时针的内圈，内圈不会被挖空。做"圆角矩形挖孔"这类效果时，内圈必须反向绘制（逆时针），或者干脆改用ctx.fill('evenodd')。这个细节我在第 4 节还会再提一次。

2.2 半径的四条边界约束

半径这块是最容易出事的地方，也是我见过最多线上 bug 的地方。理论上r可以取任意正数，但视觉上它有三个硬边界：

• r > w / 2时，左右两个圆角的弧会互相越界，上边的直线段长度变成负数，画出来是一个交叉的"蝴蝶结"；
• r > h / 2时，上下两个圆角的弧互相越界，右边直线段长度变负，效果一样；
• r < 0时，曲线会朝反方向鼓出去，形状完全不可预测。

所以不管调用方传什么，函数内部必须做一次收敛：r = Math.min(r, w / 2, h / 2)，同时r = Math.max(r, 0)。这一行代码看着不起眼，但它把"调用方传错参数"从"线上事故"降级成了"视觉上变成胶囊"，性质完全不同。

有个细节值得单独说：约束的时候要不要保持圆角的"比例感"？比如w=200, h=60, r=100，按min(w/2, h/2)收敛会得到r=30，画出来是个胶囊形，但用户脑子里的预期可能是"两个大圆角加一段直边"。这两种理解都没错，取决于业务语义。我的一般做法是：如果是用户拖拽滑块调半径的交互，就用min(h/2, w/2)硬夹住，让滑块拖到底就是胶囊，直观；如果是设计稿里给定的固定半径，那就在开发阶段就确认好，不要在运行时偷偷改。

2.3 半径参数的归一化设计

真实项目里，半径很少是"一个数字"。CSS 的border-radius支持10px、10px 20px、10px 20px 30px、10px 20px 30px 40px四种写法，分别对应 1/2/3/4 个值的展开规则：一个值是四角相同，两个值是"左上右下 / 右上左下"，三个值是"左上 / 右上左下 / 右下"，四个值是"左上 / 右上 / 右下 / 左下"顺时针。

我的归一化函数严格按这个规则来，输出一个长度为 4 的数组[tl, tr, br, bl]。这样设计的好处是：上层调用方可以直接把 CSS 字符串里解析出来的半径扔进来，也可以传数组、传数字，接口统一。而且半径顺序固定为"左上、右上、右下、左下"，跟路径顺时针遍历的顺序天然一致，写代码的时候不用来回查索引。

还有一个容易被忽略的点：归一化必须发生在收敛之前，还是之后？我的答案是每个角独立收敛，而不是先取全局最小值。因为不规则圆角场景下，tl=40, tr=0, br=0, bl=0这种"只圆左上角"的写法是真实存在的（比如聊天气泡的尾巴），如果先取全局最小会把所有角都抹成 0，功能就废了。所以代码里是map一次，逐个夹到min(w/2, h/2)和 0 之间。

function normalizeRadius(radius, w, h) { const max = Math.min(w, h) / 2; let r; if (typeof radius === 'number') { r = [radius, radius, radius, radius]; } else if (Array.isArray(radius)) { const src = radius.length === 1 ? [radius[0], radius[0], radius[0], radius[0]] : radius.length === 2 ? [radius[0], radius[1], radius[0], radius[1]] : radius.length === 3 ? [radius[0], radius[1], radius[2], radius[1]] : radius.slice(0, 4); r = src; } else { r = [0, 0, 0, 0]; } return r.map(v => Math.max(0, Math.min(Number(v) || 0, max))); }

这段代码我用了很久没改过，唯一需要注意的是Number(v) || 0这个写法会把NaN和null都变成 0，是刻意为之的容错，不是偷懒。

3. 手写一版能直接用的圆角矩形函数

3.1 函数签名与整体骨架

函数签名我试过好几个版本，最后定成了traceRoundRect(target, x, y, w, h, radius)，第一个参数叫target而不是ctx。这个命名的原因很实在：Canvas 的CanvasRenderingContext2D和Path2D都实现了moveTo、lineTo、quadraticCurveTo、closePath这四个方法，签名完全一致，所以同一个函数可以同时服务"直接画到画布上"和"先缓存成路径对象"两种用法。把参数叫ctx会让人误以为只能传上下文，叫target就没这个心理障碍。

另外一个刻意的设计是：函数内部不调用beginPath()。原因很简单，Path2D压根没有beginPath这个方法。而且把beginPath交给调用方，意味着你可以在同一个路径里先画圆角矩形、再用addPath或者rect追加别的东西，最后一次性填充，做复合形状的时候非常方便。代价是调用方必须自己记得写beginPath，这个坑我在第 5 节的排查表里专门列了一条。

整体骨架就是八个点、四段直线、四段曲线、一个closePath。四段直线的顺序是"上边、右边、下边、左边"，四段曲线紧跟在对应的直线后面，这样读代码的时候是一条连续的动线，不会来回跳。

function traceRoundRect(target, x, y, w, h, radius) { const [tl, tr, br, bl] = normalizeRadius(radius, w, h); target.moveTo(x + tl, y); // 上边：左上角之后 -> 右上角之前 target.lineTo(x + w - tr, y); // 右上角 if (tr) { target.quadraticCurveTo(x + w, y, x + w, y + tr); } // 右边 target.lineTo(x + w, y + h - br); // 右下角 if (br) { target.quadraticCurveTo(x + w, y + h, x + w - br, y + h); } // 下边 target.lineTo(x + bl, y + h); // 左下角 if (bl) { target.quadraticCurveTo(x, y + h, x, y + h - bl); } // 左边 target.lineTo(x, y + tl); // 左上角，收口 if (tl) { target.quadraticCurveTo(x, y, x + tl, y); } target.closePath(); }

3.2 四段曲线部分的关键代码

四段曲线里每一段的三个点是固定模式：起点是上一条直线的终点，控制点是那个角的尖角坐标，终点是下一条直线的起点。以右上角为例，起点(x + w - tr, y)是上边的终点，控制点(x + w, y)是右上角点，终点(x + w, y + tr)是右边的起点。三个点构成一个"L"形，曲线被夹在里面。

我特意在每段曲线外面包了if (tr)这样的判断，而不是无脑调用。原因有两个：一是半径为 0 的时候quadraticCurveTo会画一段退化曲线，虽然视觉上看不出来，但路径里多了一个曲线段，某些场景下会影响isPointInPath的边界判定和 SVG 导出字符串的长度；二是在做"动态隐藏某个角"这类交互时，判断存在能省掉一些无意义的路径操作。这个习惯是做了几年路径动画之后养成的，属于"不影响功能但影响长期可维护性"的细节。

还有一个容易忽略的收口问题：最后一段曲线画完之后，路径回到了最开始的moveTo位置，closePath()会补一条直线过去——但因为起点终点本来就重合，这条直线长度是 0，实际不产生任何绘制。但如果四个角半径都是 0，路径就是四条直线围成的矩形，closePath补的那条线正好闭合了右边，这时候closePath是必须的，不能删。有些人为了"减一次调用"把closePath去掉，结果填充时缺一条边，看着像个缺口的三角形。

3.3 调用与渲染验证

最小可运行的调用是这样的：

const canvas = document.getElementById('stage'); const ctx = canvas.getContext('2d'); ctx.beginPath(); traceRoundRect(ctx, 20, 20, 200, 120, 16); ctx.fillStyle = '#1f2a37'; ctx.fill();

如果要缓存成路径对象反复用：

const cardPath = new Path2D(); traceRoundRect(cardPath, 20, 20, 200, 120, [16, 16, 4, 4]); // 每帧只需要 fill 一个现成对象，不重新构造路径 ctx.fillStyle = '#1f2a37'; ctx.fill(cardPath);

验证画得对不对，我有个土办法但特别有效：先只描边不填充，把lineWidth设成 1，四个角放大看。如果某个角出现一小段直线叠在弧上，说明半径归一化算错了；如果两个角的弧线在中间"打个叉"，说明半径超过了短边一半而没做收敛；如果整个图形偏移了半个像素、边缘发虚，那就是坐标对齐问题，第 5 节会讲。

另一个验证手段是打印路径点数。用new Path2D()构造之后你没法直接读点数，但我习惯在开发阶段临时加一个计数变量，在每次lineTo/quadraticCurveTo时累加，正常情况应该是：四角都有半径时是 8 段（4 直线 + 4 曲线），四角都是 0 时是 4 段。数字对不上就说明有分支跑错了。

4. 把精度和适用面再往上推一档

4.1 二次贝塞尔和真圆弧差多少

这块内容我在网上很少看到有人认真算，但它直接决定了"要不要换方案"。用二次贝塞尔的参数方程在t = 0.5处取值，可以得到曲线中点：B(0.5) = 0.25 * P0 + 0.5 * P1 + 0.25 * P2。以右上角为例，P0 = (x+w-r, y)，P1 = (x+w, y)，P2 = (x+w, y+r)，代入得到中点坐标是(x + w - 0.25r, y + 0.25r)。

这个点到角点(x+w, y)的距离是√(0.25² + 0.25²) * r ≈ 0.3536r。而真正的四分之一圆弧，在 45 度方向上那个点到角点的距离是r * (√2 - 1) ≈ 0.4142r。

两者相减，差值约等于0.0606r。翻译成人话：在圆角的正中间位置，二次贝塞尔画出来的边比理论圆弧向外鼓了大约 6% 的半径。

这个数字意味着什么？r = 8px时偏差 0.48px，视网膜屏下完全无感；r = 20px时偏差 1.2px，正常观看距离下也看不出来；但r = 120px那种大卡片、大按钮，偏差达到 7px 以上，跟设计稿放在一起对比时，肉眼是能看出"这个角有点方"的。所以我的经验阈值是：半径在 40px 以内随便用二次贝塞尔；超过 80px 且要求跟设计稿严丝合缝的，换成三次贝塞尔。

4.2 换成三次贝塞尔的控制点系数

三次贝塞尔近似 90 度圆弧有一个经典系数：k = 4/3 * tan(θ/4)，其中θ是圆弧的角度，90 度就是π/2，代入得k = 4/3 * tan(π/8) ≈ 0.5522847。控制点放在距离端点k * r的位置，沿着切线方向延伸。

以右上角为例，弧的起点是(x + w - r, y)，切线方向是水平向右，所以第一个控制点是(x + w - r + k*r, y)；终点是(x + w, y + r)，切线方向是垂直向下，反推第二个控制点是(x + w, y + r - k*r)。用bezierCurveTo串起来就是：

const K = 0.5522847498; function arcCornerTR(target, x, y, w, h, r) { const cx = x + w; const cy = y; target.bezierCurveTo( cx - r + K * r, cy, cx, cy + r - K * r, cx, cy + r ); }

这样画出来的弧和真圆弧的最大偏差在 0.03% 量级，基本可以认为是一致了。代价是路径段数没变，但每段的控制点从 1 个变成 2 个，路径数据量翻倍，SVG 导出字符串会明显变长。我通常的做法是：小半径用二次，大半径用三次，用一个阈值（比如 60px）在函数内部自动切换，这样既省数据又保精度。

4.3 描边、裁剪、命中检测的三个实操场景

场景一：圆角卡片描边。这里最大的坑是"半像素模糊"。Canvas 的stroke是沿着路径中心线向两侧各扩lineWidth / 2，当lineWidth = 1且路径坐标是整数时，笔画正好跨越两个像素各一半，浏览器做抗锯齿平均之后，颜色被摊薄，看起来发灰、发虚。

解决办法有两种：一是把整个路径平移 0.5px，让笔画落在整数像素边界上；二是在高 DPI 屏上先按devicePixelRatio放大画布再缩放上下文，让 1 个 CSS 像素对应多个物理像素，模糊问题自然消失。我一般用第二种，因为第一种在lineWidth变化时要重新计算，容易忘。

const dpr = window.devicePixelRatio || 1; const cssW = 240, cssH = 140; canvas.width = cssW * dpr; canvas.height = cssH * dpr; canvas.style.width = cssW + 'px'; canvas.style.height = cssH + 'px'; ctx.scale(dpr, dpr);

场景二：圆角裁图。头像、缩略图这类需求，标准做法是save→ 建路径 →clip→drawImage→restore。

ctx.save(); ctx.beginPath(); traceRoundRect(ctx, 0, 0, 96, 96, 48); ctx.clip(); ctx.drawImage(img, 0, 0, 96, 96); ctx.restore();

这里的restore是必须的，而且必须保证save和restore成对出现。我见过最典型的 bug 是：某个分支里clip之后提前return了，restore没执行，导致整个画布后续所有绘制都被裁在那 96×96 的圆角里，排查半天以为是图层问题。所以现在我的习惯是clip一定包在save/restore之间，中间不写任何return，要提前退出就先把结果算好再统一处理。

场景三：命中检测。做圆角按钮的点击判定，ctx.isPointInPath(x, y)是首选。但它有个非常隐蔽的坑：当上下文做过scale(dpr, dpr)缩放之后，isPointInPath的入参并不是简单的 CSS 坐标，多数浏览器实现里它拿的是未经当前变换矩阵放大的画布位图坐标。也就是说，你scale(2, 2)之后路径的实际坐标被放大了两倍，判定点也得跟着放大两倍，否则点哪儿都不中。

function hitTest(canvas, ctx, path, evt) { const rect = canvas.getBoundingClientRect(); const scaleX = canvas.width / rect.width; const scaleY = canvas.height / rect.height; const px = (evt.clientX - rect.left) * scaleX; const py = (evt.clientY - rect.top) * scaleY; return ctx.isPointInPath(path, px, py); }

我给的建议是：别凭记忆写，先在目标浏览器里打印一次验证。写一个明显在路径内的点和一个明显在路径外的点，跑一遍看结果对不对，把这个结论固化到自己的工具函数里。不同版本规范在这个点上确实调整过，实测优先于文档。

5. 高频问题与排查实录

5.1 问题速查表

下面这张表是我这几年积累的，基本覆盖了 90% 的现场问题。遇到画得不对，先按表里的"现象"对号入座，比从头审代码快得多。

5.2 几个文档里不会写的避坑经验

第一条：半径数组一定要有"语义锚点"。我吃过一次亏，某个组件里半径数组的索引顺序在不同函数里不一致，一处当成[tl, tr, bl, br]，另一处当成[tl, tr, br, bl]，因为大部分时候四个角半径相同，问题藏了两个月才在下单页的一个特定卡片上暴露出来。现在的做法是：所有涉及半径的函数，参数统一命名为tl, tr, br, bl，并且在文件顶部写一行注释说明这是顺时针顺序，不允许缩写。这种"用命名约束语义"的习惯，比写注释管用。

第二条：不要用浮点数做半径的累加。做拖拽调半径的交互时，r += 0.1这种写法会累积浮点误差，拖一会儿之后r变成15.999999999，虽然视觉上看不出来，但如果你的半径参与了缓存 key 的生成，就会导致缓存永远命中不了、每帧重建路径。我现在的做法是交互层只存整数，需要平滑的话在渲染层做插值。

第三条：路径复用时留意Path2D的变换继承。new Path2D(oldPath)复制的是路径数据，不复制变换。如果你在ctx上做过translate，然后new Path2D()里塞坐标，塞进去的是"当前变换空间"的坐标，之后的绘制会再叠加一次变换，图像就跑飞了。所以缓存路径的时候，坐标一定要用未变换的绝对坐标，把变换留给ctx.setTransform处理。

第四条：做圆角动画时，只改半径不要重建路径对象。早期我做过一个"卡片展开"的动画，每帧都beginPath然后重新调traceRoundRect，帧率掉得厉害。后来改成每帧只更新半径变量、重画一次路径，其实差别不大，真正省下来的是那些可以做Path2D缓存的部分——静态的、半径不变的元素全部预生成路径，动画只改translate和透明度，帧率立刻稳了。这个思路在做列表滚动、图表刷新的时候特别有用。

第五条：一次性检查"视觉所有边界"。我这几年养成的验收习惯是：把半径拖到 0、拖到刚好等于短边一半、拖到超过短边一半，这三个状态各看一眼。0 的时候看是不是直角，一半的时候看是不是标准胶囊，超过的时候看有没有交叉。这三个状态全对，基本可以认为代码没有边界问题。比只测一个"正常值"靠谱得多。

第六条：把圆角矩形函数当成一个"基础件"来对待。它其实跟rect、arc是一个级别的原语，项目里应该只有一份实现，放在公共工具目录里，带单元测试（对，画布也能测，用Path2D构造之后比路径数据的快照）。我见过太多项目里散落着五六份不同的圆角矩形实现，每份的半径收敛策略都不一样，最后视觉对不齐，改一处漏五处。统一成一份，哪怕它不够完美，也比六份各自为政要强。

我个人在做大屏和图表容器的这些年，圆角矩形这个函数被复制进过至少十几个项目。最后一次重构的时候我把二次贝塞尔版本和三次贝塞尔版本合成了一个函数，内部按半径阈值自动选精度，调用方完全无感。真正让这个函数稳定的不是那段数学，而是那些看起来跟绘制无关的东西：半径的归一化规则、beginPath的归属、save/restore的包裹、DPR 的处理。这些细节写进代码之后，这个函数就再也没在线上出过问题。