做前端这么多年，不管是做可视化、海报生成、小游戏还是自定义图表，只要用到Canvas，drawImage图片不显示这个坑，几乎人人都踩过。
控制台不报错、代码逻辑看着没毛病、图片路径也对，可画布上就是一片空白，纯纯玄学bug。今天把这10年踩过的Canvas绘图坑、排查思路、解决方案一次性讲透，遇到同款问题直接抄作业，不用再瞎调试。
适用场景：原生JS Canvas、Vue/React框架内Canvas绘图、本地/跨域图片绘制、动态加载图片
核心结论：drawImage不显示，基本不是API用错，而是图片加载时机、跨域、资源路径、渲染时序这四大问题导致的
先看最典型的错误代码（你大概率也这么写）
很多人写Canvas绘图，直接同步调用drawImage，以为图片立马就能渲染，结果啥也没有：
// 错误写法：同步绘图，图片还没加载就执行绘制
const canvas = document.getElementById('myCanvas')
const ctx = canvas.getContext('2d')
const img = new Image()
// 动态拼接图片路径（和之前鸿蒙动态资源坑异曲同工）
const index = Math.floor(Math.random() * 3) + 1
img.src = `./images/icon${index}.png`
// 直接绘制，图片未加载完成，drawImage白忙活
ctx.drawImage(img, 0, 0, 200, 200)
运行之后，画布干干净净，连个报错都没有，排查半天找不到原因。这就是最经典的图片未加载完成就绘图，也是前端Canvas最容易踩的第一大坑。
一、先排查：这4步走完，快速定位病根
遇到drawImage不显示，别乱改代码，按这个老前端专属排查流程走，1分钟找到问题：
1. 查图片加载状态（90%的坑都在这）
图片是异步加载的，浏览器还没下载完资源，你就调用drawImage，相当于给空白图像绘图，肯定不显示。
验证方法：给img标签加onload、onerror监听，打印日志看是否加载成功：
img.onload = () => {
console.log('图片加载成功，此时再绘图才有效')
ctx.drawImage(img, 0, 0, 200, 200)
}
img.onerror = (err) => {
console.error('图片加载失败', err) // 路径错、跨域、资源不存在都会走这
}
2. 查跨域问题（在线图片必踩坑）
如果图片是第三方域名、CDN资源，没配置跨域，浏览器会拦截图片加载，Canvas出于安全策略，直接把画布污染，drawImage失效。
典型表现：图片能在页面img标签正常显示，但Canvas里画不出来，控制台无显性报错。
3. 查路径/资源问题（低级错误最致命）
- 相对路径错误：框架开发（Vue/React）中，public目录和src目录路径写法混淆
- 大小写/后缀错误：Icon1.png和icon1.png、.jpg和.png写错，本地开发不明显，线上直接失效
- 动态拼接失误：变量拼接路径出错，导致src指向空白资源
4. 查Canvas渲染与尺寸问题
- Canvas宽高没设置，默认300x150，图片被压缩/超出可视区
- drawImage坐标/尺寸参数错误，图片画在画布外
- 画布被清空（clearRect）、覆盖，绘制后被其他逻辑擦掉
二、终极解决方案：3种场景直接套用
场景1：本地静态图片+动态路径（最常用）
核心：必须等onload加载完成再绘图，动态拼接路径要规范，框架项目注意资源存放位置。
// 正确写法：等待图片加载完成后绘制
function drawCanvasImg() {
const canvas = document.getElementById('myCanvas')
// 务必先设置画布宽高，避免默认尺寸异常
canvas.width = 400
canvas.height = 400
const ctx = canvas.getContext('2d')
// 动态生成图片索引（复刻原文动态资源场景）
const randomIdx = Math.floor(Math.random() * 3) + 1
const imgUrl = `/images/icon${randomIdx}.png` // Vue/React/public目录下资源，用绝对路径
const img = new Image()
img.src = imgUrl
// 图片加载成功后再绘制
img.onload = () => {
console.log('图片加载完毕，开始绘制')
// drawImage参数：img, x, y, width, height
ctx.drawImage(img, 50, 50, 300, 300)
}
// 捕获错误，便于排查
img.onerror = (err) => {
console.error('图片加载失败，请检查路径：', imgUrl, err)
}
}
// 页面加载完成后调用
window.addEventListener('load', drawCanvasImg)
场景2：跨域图片/CDN图片绘制
核心：给img设置crossOrigin属性，配合后端/CDN开启跨域配置，解决画布污染问题。
const img = new Image()
// 关键：开启跨域属性，值为anonymous（匿名跨域）
img.crossOrigin = 'anonymous'
img.src = 'https://xxx.cdn.com/images/icon1.png' // 跨域图片地址
img.onload = () => {
ctx.drawImage(img, 0, 0, 200, 200)
}
补充说明：仅前端加crossOrigin不够，CDN/后端必须配置Access-Control-Allow-Origin响应头，否则依然失效。本地测试可禁用浏览器安全策略，上线务必配置跨域。
场景3：框架内绘图（Vue/React）
避坑要点：
- 资源放在public目录，用绝对路径引用，别放src/assets（会被webpack编译）
- 在onMounted（Vue）/useEffect（React）里调用绘图，确保DOM已渲染
- 组件销毁时清除图片监听，避免内存泄漏
三、10年前端压箱底的避坑总结
把这些要点刻进脑子里，以后Canvas绘图再也不会踩坑：
- 异步优先：drawImage必须写在img.onload里面，同步绘图=白给
- 路径规范：动态拼接路径后，打印src校验，杜绝大小写、后缀、目录错误
- 跨域必处理：在线图片先配crossOrigin，再检查后端跨域头
- 画布先定型：先设置canvas宽高，再绘图，避免尺寸异常
- 错误必监听：onerror一定要写，排查问题效率翻倍
其实Canvas绘图没那么多玄学，都是细节没做到位。很多时候看似复杂的问题，本质就是没等图片加载完这一个原因。
如果大家还遇到过其他Canvas奇葩坑，评论区留言，我挨个解答。觉得干货有用的话，点赞+收藏，下次画图遇到问题直接翻这篇～
