在Web开发中，利用Canvas在图像上绘制矩形是一项基础而常见的需求，广泛应用于图像标注、区域选取、截图框选等场景。然而，不少开发者在实际操作中会遇到这样的困惑：图像正常显示，但绘制的矩形却“凭空消失”。近日，这一技术难题在多个开发者社区引发热议。本文将从Canvas原理出发，梳理图像上绘制矩形的几种方法，并深入剖析矩形不显示的根本原因及解决策略。
一、绘制矩形的三种主流方式
Canvas API为矩形绘制提供了三条核心路径：
fillRect(x, y, width, height)：直接填充一个实心矩形，不依赖路径上下文。strokeRect(x, y, width, height)：绘制矩形边框，同样无需手动创建路径。rect(x, y, width, height)+fill()/stroke()：先创建矩形路径，再填充或描边，适用于需要组合多个形状的复杂场景。
这三种方法均基于Canvas 2D上下文（getContext('2d')），理论上简单易用。但在图像叠加场景下，顺序和状态管理稍有疏忽，矩形便会“隐身”。
二、典型错误：图像加载与绘制顺序陷阱
“矩形不显示”的最常见症结在于异步图像加载。许多开发者习惯将绘图代码直接写在Image.onload事件外部，导致在图像尚未完成加载时就尝试绘制矩形。
错误示范：
const canvas = document.getElementById('canvas');
const ctx = canvas.getContext('2d');
const img = new Image();
img.src = 'example.jpg';
// 图像尚未加载，但矩形已绘制
ctx.drawImage(img, 0, 0);
ctx.fillStyle = 'red';
ctx.fillRect(50, 50, 100, 100);
上述代码中，图像绘制实际发生在drawImage被调用的瞬间，而此时img的complete属性可能为false，浏览器会忽略尚未加载的源。正确的做法是将所有绘图操作放入img.onload回调中，确保图像数据就绪。
正确示例：
img.onload = function() {
ctx.drawImage(img, 0, 0);
ctx.fillStyle = 'red';
ctx.fillRect(50, 50, 100, 100);
}
三、坐标系与样式缺失：看不见的“隐形矩形”
即使图像成功加载，矩形仍可能“消失”于以下细节：
1. 坐标越界
若矩形的x、y坐标或宽高超出Canvas可视区域（如负坐标、超过canvas.width/canvas.height），Canvas会直接裁剪掉这部分内容。开发者应确保矩形完全位于Canvas边界内，或使用ctx.clip()限定绘制区域。
2. 未设置填充/描边样式
调用fillRect前未设置fillStyle（默认为'#000000'即黑色），或调用strokeRect前未设置strokeStyle（默认为'#000000'）。若图像本身包含大量黑色区域，矩形可能与其融为一体。建议显式指定鲜艳的颜色或半透明色，例如ctx.fillStyle = 'rgba(255, 0, 0, 0.5)'。
3. 路径状态污染
在使用rect()方法时，若未调用ctx.beginPath()清除上次路径，之前绘制的形状会与当前矩形叠加渲染，造成视觉混乱甚至覆盖。每次新建路径前都应重置路径上下文。
四、进阶场景：动态矩形与交互标注
在实际应用中，开发者常需根据鼠标事件动态绘制矩形（如拖拽选框）。此时，canvas.getBoundingClientRect()与鼠标坐标的换算、requestAnimationFrame的合理使用、以及清除画布的时机均会影响矩形是否呈现。建议在每次绘制前调用ctx.clearRect(0, 0, canvas.width, canvas.height)来重置画布，再重绘图像和矩形，避免叠加残留。
五、专家建议：调试工具与最佳实践
针对“矩形不显示”问题，资深前端工程师李伟表示：“应当将Canvas视为一个状态机，时刻关注绘图上下文的状态和绘制顺序。推荐使用浏览器开发者工具的‘检查器’功能，对Canvas元素进行实时截图比较，或添加console.log(ctx.fillStyle)确认样式生效。”
此外，开发者还可以考虑以下替代方案：
- CSS叠加层：通过div的background-image配合position: absolute实现矩形框，无需Canvas。
- SVG overlay：在Canvas上方覆盖一个SVG元素，利用<rect>标签绘制图形，避免Canvas API的异步问题。
六、结语
在图像上绘制矩形看似简单，实则涉及Canvas的异步加载机制、样式定义、路径管理和坐标计算等多重因素。当矩形“不显示”时，开发者应系统检查：图像是否完全加载？坐标系是否越界？样式是否设置？路径是否重置？唯有踩准每一个技术节点，矩形才能如期呈现在图像之上。希望本文的分析能为遇到同类问题的开发者提供清晰的解决路径。