小程序开发走到画布这一层基本就告别了拖拽组件、拼拼页面的舒适区。画布API是小程序里少数几个需要你真正理解坐标系、渲染时机和异步回调的地方也是很多开发者从能写页面到能做产品之间的一道坎。这份画布API汇总的第四篇我打算把重心放在那些真正会在项目里反复用到、又特别容易踩坑的能力上——绘图上下文的状态管理、路径绘制与裁剪、图片合成、文字排版、渐变填充以及导出与跨端适配。不管你是刚接触画布、想搞清楚createCanvasContext到底怎么用还是已经写过几个画布项目、被真机与开发者工具的差异折磨过这篇内容都能给你一些可以直接抄作业的代码和避坑经验。画布API汇总这个系列写到第四篇前面几篇铺垫了基础绘图和坐标体系这一篇更偏向组合拳讲的是多个API怎么配合起来完成一个完整功能。1. 画布能力集成的整体设计与选型思路1.1 为什么画布API值得单独拿出来做汇总小程序里的画布能力本质上是一套命令式绘图接口——你调用fillRect、stroke、drawImage这些方法把绘制指令压进一个队列最后由框架统一提交给底层渲染。这个模型和浏览器里的Canvas 2D Context非常接近但又有明显差异小程序的画布上下文是异步的很多操作需要配合draw回调或者canvasToTempFilePath的success才能拿到结果。理解这一点是理解整个画布API体系的前提。我在实际项目里见过太多这样的场景开发者按照Web端的习惯写了一段绘图代码在开发者工具里跑得好好的一上真机就白屏或者错位。问题往往不在API本身而在于对绘制指令何时生效画布尺寸与样式尺寸的关系图片加载与绘制的时序这几个核心机制理解不到位。所以这份汇总不打算做成API文档的搬运工而是按能力域来组织——把状态管理、路径、图片、文字、渐变、导出这几块拆开讲每块都配上能直接跑的代码和真机验证过的注意事项。从选型角度看小程序画布目前主要有两套接口旧版的CanvasContext通过wx.createCanvasContext获取和新版的Canvas 2D通过canvas节点的getContext(2d)获取。旧版接口兼容性好、上手快但性能和部分高级特性受限新版接口更接近标准Canvas 2D支持requestAnimationFrame、离屏画布等能力适合做复杂动画和高频重绘。这份汇总以旧版接口为主线因为它在存量项目里占比最大同时在关键处标注新版接口的差异方便你做迁移判断。1.2 能力域拆解一份画布项目到底需要哪些API把画布API按能力域拆开能帮你建立一张知识地图遇到需求时知道该去查哪一块。我通常把它分成六层能力域核心API典型用途上下文与状态createCanvasContext、save、restore、setFillStyle管理绘图状态、隔离样式路径绘制beginPath、moveTo、lineTo、arc、closePath、clip图形、图表、裁剪蒙版图片处理drawImage、getImageData、putImageData图片合成、水印、像素处理文字排版setFontSize、fillText、measureText、setTextAlign海报、证书、动态文案渐变与填充createLinearGradient、createCircularGradient、addColorStop背景、按钮、视觉增强导出与适配canvasToTempFilePath、draw、canvasId与节点查询保存图片、跨端一致性这张表不是让你背下来而是让你在动手前先想清楚这个需求落在哪一层需要哪几个API组合。比如做一张分享海报就同时涉及图片处理底图、头像、文字排版昵称、标语、渐变填充背景装饰和导出生成临时文件是一个典型的多能力域协作场景。1.3 旧版与新版画布接口的取舍逻辑选旧版还是新版不是新的就一定好这么简单。我一般按三个维度判断项目存量如果项目里已经有大量基于wx.createCanvasContext的代码贸然迁移成本高、风险大除非遇到明确的性能瓶颈否则维持现状更稳妥。性能要求需要做高频重绘比如实时滤镜、粒子动画时新版Canvas 2D配合requestAnimationFrame优势明显旧版在真机上容易出现掉帧。特性依赖需要离屏画布、getImageData做像素级处理、或者更精细的合成模式时新版接口支持更完整。注意新旧两套接口的坐标系原点、尺寸获取方式、draw的调用时机都有差异混用极易出错。一个项目里尽量统一用一套迁移时按页面逐个替换不要新旧混写。2. 上下文状态管理与路径绘制实操要点2.1 save与restore画布状态隔离的核心机制画布的绘图状态包括填充色、描边色、线宽、字体、变换矩阵、裁剪区域等。save把当前状态压栈restore弹出栈顶状态恢复。这个机制的价值在于局部修改不影响全局——你可以在一个函数里随意改样式函数结束前restore外层的绘图状态完全不受污染。我见过不少项目从头到尾不写save/restore全靠手动把每个样式改回去代码越写越乱最后没人敢动。正确的做法是任何一段会修改状态的绘制逻辑进入时save退出时restore形成一个封闭的作用域。这跟函数作用域的思路是一样的——局部变量不外泄。const ctx wx.createCanvasContext(myCanvas) // 外层状态红色填充 ctx.setFillStyle(#e74c3c) ctx.fillRect(0, 0, 100, 100) // 内层绘制独立作用域 ctx.save() ctx.setFillStyle(#3498db) ctx.translate(50, 50) ctx.rotate(Math.PI / 4) ctx.fillRect(-25, -25, 50, 50) ctx.restore() // 回到外层状态仍是红色 ctx.fillRect(150, 0, 100, 100) ctx.draw()这段代码里内层的旋转和蓝色填充被save/restore包裹外层的红色填充不受影响。如果去掉save/restore第二次fillRect会继承旋转矩阵画出来的方块就是歪的——这是新手最常遇到的为什么我的图形位置不对的根源之一。2.2 路径绘制的顺序陷阱与beginPath的必要性路径是一系列子路径的集合beginPath清空当前路径moveTo开启新子路径lineTo、arc等追加线段或弧线closePath闭合当前子路径最后fill或stroke渲染。这里最容易踩的坑是忘记beginPath路径会不断累积上一次的图形和这一次连在一起fill出来的形状完全失控。// 错误示范没有beginPath两个三角形连成一片 ctx.moveTo(10, 10) ctx.lineTo(60, 10) ctx.lineTo(35, 50) ctx.closePath() ctx.fill() ctx.moveTo(80, 10) ctx.lineTo(130, 10) ctx.lineTo(105, 50) ctx.closePath() ctx.fill() // 这里会把第一个三角形也重新填充一遍正确写法是每次绘制独立图形前调用beginPath。另外要注意closePath和beginPath的区别closePath只是把当前子路径首尾相连不清空路径beginPath才是真正的清空重来。做图表这类需要绘制大量独立图形的场景beginPath的调用位置直接决定渲染结果对不对。2.3 裁剪clip做圆角头像和异形蒙版的利器clip把当前路径设为裁剪区域之后的所有绘制都被限制在这个区域内。做圆角头像的经典写法就是画一个圆或圆角矩形路径clip再drawImage头像图超出部分自动被裁掉。ctx.save() ctx.beginPath() ctx.arc(60, 60, 50, 0, Math.PI * 2) ctx.clip() ctx.drawImage(avatarPath, 10, 10, 100, 100) ctx.restore()这里save/restore是必须的——clip会永久改变裁剪区域不恢复的话后续所有绘制都被限制在圆内。我踩过的坑是裁剪区域一旦设置连clearRect都受它约束导致想清空画布却清不干净。所以凡是用了clip务必用save/restore包起来。提示clip的路径必须在clip调用前用beginPath重新构建否则会继承之前的路径裁剪区域和预期不符。这是真机上特别容易出问题的地方。2.4 坐标变换translate、rotate、scale的组合顺序坐标变换是画布做复杂布局的基础但组合顺序会显著影响结果。translate平移原点rotate绕原点旋转scale缩放坐标轴。关键规则是变换按调用顺序累积后调用的变换作用在前一次变换的基础上。举个实际例子要在画布上画一个绕自身中心旋转的矩形ctx.save() ctx.translate(cx, cy) // 先把原点移到矩形中心 ctx.rotate(angle) // 绕新原点即矩形中心旋转 ctx.fillRect(-w / 2, -h / 2, w, h) // 以中心为基准绘制 ctx.restore()如果顺序反过来先rotate再translate平移的方向会被旋转矩阵影响矩形跑到意想不到的位置。我的经验是先平移把原点挪到目标位置再做旋转和缩放最后以原点为中心绘制这个顺序最符合直觉也最容易调试。3. 图片合成与文字排版的完整实现流程3.1 drawImage的三种调用形式与图片加载时序drawImage支持三种参数形式三参数图片、x、y、五参数图片、x、y、宽、高、九参数图片、源图x、y、宽、高、目标x、y、宽、高。九参数形式是做图片裁剪合成的关键——你可以只取源图的一部分绘制到目标区域。但比参数更容易出问题的是图片加载时序。drawImage的图片参数可以是临时文件路径、网络图片需先下载或本地资源。如果图片还没加载完就调用drawImage真机上大概率画不出来开发者工具里却可能碰巧成功造成工具正常、真机白屏的经典问题。稳妥的做法是先把所有图片加载完再统一绘制function loadImage(src) { return new Promise((resolve, reject) { wx.getImageInfo({ src, success: res resolve(res.path), fail: reject }) }) } async function composePoster() { const [bg, avatar] await Promise.all([ loadImage(bgUrl), loadImage(avatarUrl) ]) const ctx wx.createCanvasContext(posterCanvas) ctx.drawImage(bg, 0, 0, 375, 600) ctx.drawImage(avatar, 20, 20, 80, 80) ctx.draw() }wx.getImageInfo不仅能拿到本地路径还能拿到图片的原始宽高这对保持图片比例、计算裁剪区域非常有用。网络图片必须先通过它或wx.downloadFile转成本地路径才能稳定绘制。3.2 文字排版measureText与多行文本换行画布里的文字不会自动换行长文本必须手动计算断行位置。measureText返回文本的宽度信息配合画布宽度就能实现自动换行。核心逻辑是逐字累加宽度超过最大宽度就换行。function wrapText(ctx, text, maxWidth, lineHeight, x, y) { let line let currentY y for (let i 0; i text.length; i) { const testLine line text[i] const metrics ctx.measureText(testLine) if (metrics.width maxWidth line ! ) { ctx.fillText(line, x, currentY) line text[i] currentY lineHeight } else { line testLine } } ctx.fillText(line, x, currentY) }这里有几个细节值得注意measureText在旧版接口里返回的宽度是同步可用的但字体设置必须在测量前完成否则测出来的是默认字体的宽度中英文混排时逐字断行可能在英文单词中间断开追求效果的话可以按空格和标点做断词优化setTextAlign和setTextBaseline会影响fillText的定位基准做居中排版时先设好对齐方式再计算坐标。3.3 图片与文字的图层叠加顺序画布是后画的盖住先画的图层顺序完全由绘制调用顺序决定。做海报这类合成场景正确的顺序是背景图 → 装饰图形 → 头像/图片 → 文字 → 水印。任何一步顺序错了要么被遮挡要么遮挡了不该遮挡的内容。我习惯在代码里用注释明确标注图层并且把每一层的绘制封装成独立函数主流程只负责按顺序调用。这样调整图层时只需要挪动函数调用位置不用在几百行代码里找哪句drawImage该放前面。注意draw是异步提交绘制指令的多次调用draw之间如果没有等待可能出现指令交错。合成场景建议所有绘制完成后只调用一次draw需要分阶段渲染时用draw的回调串起来。4. 渐变填充、导出与跨端适配的问题排查4.1 线性渐变与径向渐变的参数计算createLinearGradient(x0, y0, x1, y1)定义渐变的方向和范围addColorStop(offset, color)添加色标offset取值0到1。渐变对象创建后赋给setFillStyle或setStrokeStyle即可生效。const grd ctx.createLinearGradient(0, 0, 0, 200) grd.addColorStop(0, #ff9a9e) grd.addColorStop(1, #fad0c4) ctx.setFillStyle(grd) ctx.fillRect(0, 0, 375, 200)参数计算的关键是理解渐变线的几何意义渐变沿着从(x0,y0)到(x1,y1)的直线方向变化垂直于这条线的方向上颜色相同。做水平渐变就让y坐标相同、x坐标不同做对角线渐变就让两个坐标都变化。径向渐变createCircularGradient(x, y, r)以(x,y)为圆心、r为半径从中心向外渐变做光晕、按钮高光很合适。一个常见误区是渐变坐标用了画布的样式尺寸比如375但画布实际绘制尺寸是另一套值导致渐变范围对不上。渐变坐标必须和绘制坐标使用同一套尺寸体系这一点在做了scale变换后尤其要注意。4.2 canvasToTempFilePath导出图片的完整流程导出是画布项目最常见的收尾动作canvasToTempFilePath把画布内容转成临时文件可以预览、保存或上传。它的参数里canvasId旧版或canvas节点新版、x/y/width/height导出区域、destWidth/destHeight输出分辨率是关键。wx.canvasToTempFilePath({ canvasId: posterCanvas, x: 0, y: 0, width: 375, height: 600, destWidth: 750, destHeight: 1200, success: res { // res.tempFilePath 即生成的图片路径 wx.previewImage({ urls: [res.tempFilePath] }) }, fail: err console.error(导出失败, err) })destWidth/destHeight设成绘制尺寸的两倍是为了在高分屏上导出更清晰的图片——画布按逻辑像素绘制导出时按物理像素输出相当于做了2倍图。但要注意内存尺寸越大导出耗时和内存占用越高超过一定阈值在低端机上可能失败。4.3 真机与开发者工具差异的排查清单画布相关的工具正常、真机异常问题我整理了一张速查表基本覆盖了八成以上的排查场景现象可能原因排查方向真机白屏图片未加载完就绘制用getImageInfo预加载Promise.all等待图形错位画布样式尺寸与绘制尺寸不一致统一用节点查询拿实际尺寸文字不显示字体设置晚于fillText先setFontSize再绘制导出模糊destWidth未按倍率放大按设备像素比设置输出尺寸裁剪失效clip前未beginPath重建路径后再裁剪渐变异常渐变坐标与绘制坐标体系不一致检查是否受scale影响真机排查的核心方法是分段验证把复杂绘制拆成几个简单步骤逐步draw看哪一步开始出问题。另外真机的画布尺寸获取建议用wx.createSelectorQuery查询节点实际宽高而不是硬编码这样能适配不同屏幕。提示旧版画布的draw在部分机型上有延迟连续快速调用可能丢帧。需要动画时优先考虑新版Canvas 2D配合requestAnimationFrame旧版更适合静态合成场景。5. 我在画布项目里踩过的坑与实操心得5.1 尺寸体系混乱是万恶之源画布有两套尺寸样式尺寸CSS里写的宽高和绘制尺寸canvas标签的width/height属性或绘制时用的坐标系。旧版接口里绘制坐标系默认以样式尺寸为准但导出时又涉及物理像素三者不统一就会错位。我的做法是页面加载时用节点查询拿到画布实际宽高存成变量所有绘制坐标都基于这个变量计算绝不硬编码数字。这样换机型、换布局都不用改绘图代码。5.2 异步时序要用Promise串起来画布绘制涉及图片加载、字体加载、导出等多个异步环节用回调嵌套写出来的代码又长又难维护。我习惯把每个异步操作封装成Promise用async/await组织主流程出错时统一catch。这样不仅代码清晰排查问题时也能快速定位是哪个环节失败。5.3 复杂画布要拆函数、加注释、留调试开关一个几百行的绘图函数改一个颜色都要找半天。我的经验是按图层拆函数每个函数只负责一层函数名体现图层含义关键坐标用常量或变量命名不写魔法数字留一个调试开关打开时给每个图层画边框方便定位错位问题。这些习惯在项目后期维护时能省下大量时间。画布API看着零散但按能力域梳理清楚、把状态管理和异步时序这两个核心机制吃透大部分需求都能稳稳落地。真正拉开差距的不是记住了多少API而是对绘制指令何时生效坐标体系如何统一这些底层逻辑的理解深度。 
长河君 · 2026/10/27 15:34:19 · 阅读 1.2k 小程序画布API实战：状态管理、图片合成与跨端适配避坑指南
小程序开发走到画布这一层基本就告别了拖拽组件、拼拼页面的舒适区。画布API是小程序里少数几个需要你真正理解坐标系、渲染时机和异步回调的地方也是很多开发者从能写页面到能做产品之间的一道坎。这份画布API汇总的第四篇我打算把重心放在那些真正会在项目里反复用到、又特别容易踩坑的能力上——绘图上下文的状态管理、路径绘制与裁剪、图片合成、文字排版、渐变填充以及导出与跨端适配。不管你是刚接触画布、想搞清楚createCanvasContext到底怎么用还是已经写过几个画布项目、被真机与开发者工具的差异折磨过这篇内容都能给你一些可以直接抄作业的代码和避坑经验。画布API汇总这个系列写到第四篇前面几篇铺垫了基础绘图和坐标体系这一篇更偏向组合拳讲的是多个API怎么配合起来完成一个完整功能。1. 画布能力集成的整体设计与选型思路1.1 为什么画布API值得单独拿出来做汇总小程序里的画布能力本质上是一套命令式绘图接口——你调用fillRect、stroke、drawImage这些方法把绘制指令压进一个队列最后由框架统一提交给底层渲染。这个模型和浏览器里的Canvas 2D Context非常接近但又有明显差异小程序的画布上下文是异步的很多操作需要配合draw回调或者canvasToTempFilePath的success才能拿到结果。理解这一点是理解整个画布API体系的前提。我在实际项目里见过太多这样的场景开发者按照Web端的习惯写了一段绘图代码在开发者工具里跑得好好的一上真机就白屏或者错位。问题往往不在API本身而在于对绘制指令何时生效画布尺寸与样式尺寸的关系图片加载与绘制的时序这几个核心机制理解不到位。所以这份汇总不打算做成API文档的搬运工而是按能力域来组织——把状态管理、路径、图片、文字、渐变、导出这几块拆开讲每块都配上能直接跑的代码和真机验证过的注意事项。从选型角度看小程序画布目前主要有两套接口旧版的CanvasContext通过wx.createCanvasContext获取和新版的Canvas 2D通过canvas节点的getContext(2d)获取。旧版接口兼容性好、上手快但性能和部分高级特性受限新版接口更接近标准Canvas 2D支持requestAnimationFrame、离屏画布等能力适合做复杂动画和高频重绘。这份汇总以旧版接口为主线因为它在存量项目里占比最大同时在关键处标注新版接口的差异方便你做迁移判断。1.2 能力域拆解一份画布项目到底需要哪些API把画布API按能力域拆开能帮你建立一张知识地图遇到需求时知道该去查哪一块。我通常把它分成六层能力域核心API典型用途上下文与状态createCanvasContext、save、restore、setFillStyle管理绘图状态、隔离样式路径绘制beginPath、moveTo、lineTo、arc、closePath、clip图形、图表、裁剪蒙版图片处理drawImage、getImageData、putImageData图片合成、水印、像素处理文字排版setFontSize、fillText、measureText、setTextAlign海报、证书、动态文案渐变与填充createLinearGradient、createCircularGradient、addColorStop背景、按钮、视觉增强导出与适配canvasToTempFilePath、draw、canvasId与节点查询保存图片、跨端一致性这张表不是让你背下来而是让你在动手前先想清楚这个需求落在哪一层需要哪几个API组合。比如做一张分享海报就同时涉及图片处理底图、头像、文字排版昵称、标语、渐变填充背景装饰和导出生成临时文件是一个典型的多能力域协作场景。1.3 旧版与新版画布接口的取舍逻辑选旧版还是新版不是新的就一定好这么简单。我一般按三个维度判断项目存量如果项目里已经有大量基于wx.createCanvasContext的代码贸然迁移成本高、风险大除非遇到明确的性能瓶颈否则维持现状更稳妥。性能要求需要做高频重绘比如实时滤镜、粒子动画时新版Canvas 2D配合requestAnimationFrame优势明显旧版在真机上容易出现掉帧。特性依赖需要离屏画布、getImageData做像素级处理、或者更精细的合成模式时新版接口支持更完整。注意新旧两套接口的坐标系原点、尺寸获取方式、draw的调用时机都有差异混用极易出错。一个项目里尽量统一用一套迁移时按页面逐个替换不要新旧混写。2. 上下文状态管理与路径绘制实操要点2.1 save与restore画布状态隔离的核心机制画布的绘图状态包括填充色、描边色、线宽、字体、变换矩阵、裁剪区域等。save把当前状态压栈restore弹出栈顶状态恢复。这个机制的价值在于局部修改不影响全局——你可以在一个函数里随意改样式函数结束前restore外层的绘图状态完全不受污染。我见过不少项目从头到尾不写save/restore全靠手动把每个样式改回去代码越写越乱最后没人敢动。正确的做法是任何一段会修改状态的绘制逻辑进入时save退出时restore形成一个封闭的作用域。这跟函数作用域的思路是一样的——局部变量不外泄。const ctx wx.createCanvasContext(myCanvas) // 外层状态红色填充 ctx.setFillStyle(#e74c3c) ctx.fillRect(0, 0, 100, 100) // 内层绘制独立作用域 ctx.save() ctx.setFillStyle(#3498db) ctx.translate(50, 50) ctx.rotate(Math.PI / 4) ctx.fillRect(-25, -25, 50, 50) ctx.restore() // 回到外层状态仍是红色 ctx.fillRect(150, 0, 100, 100) ctx.draw()这段代码里内层的旋转和蓝色填充被save/restore包裹外层的红色填充不受影响。如果去掉save/restore第二次fillRect会继承旋转矩阵画出来的方块就是歪的——这是新手最常遇到的为什么我的图形位置不对的根源之一。2.2 路径绘制的顺序陷阱与beginPath的必要性路径是一系列子路径的集合beginPath清空当前路径moveTo开启新子路径lineTo、arc等追加线段或弧线closePath闭合当前子路径最后fill或stroke渲染。这里最容易踩的坑是忘记beginPath路径会不断累积上一次的图形和这一次连在一起fill出来的形状完全失控。// 错误示范没有beginPath两个三角形连成一片 ctx.moveTo(10, 10) ctx.lineTo(60, 10) ctx.lineTo(35, 50) ctx.closePath() ctx.fill() ctx.moveTo(80, 10) ctx.lineTo(130, 10) ctx.lineTo(105, 50) ctx.closePath() ctx.fill() // 这里会把第一个三角形也重新填充一遍正确写法是每次绘制独立图形前调用beginPath。另外要注意closePath和beginPath的区别closePath只是把当前子路径首尾相连不清空路径beginPath才是真正的清空重来。做图表这类需要绘制大量独立图形的场景beginPath的调用位置直接决定渲染结果对不对。2.3 裁剪clip做圆角头像和异形蒙版的利器clip把当前路径设为裁剪区域之后的所有绘制都被限制在这个区域内。做圆角头像的经典写法就是画一个圆或圆角矩形路径clip再drawImage头像图超出部分自动被裁掉。ctx.save() ctx.beginPath() ctx.arc(60, 60, 50, 0, Math.PI * 2) ctx.clip() ctx.drawImage(avatarPath, 10, 10, 100, 100) ctx.restore()这里save/restore是必须的——clip会永久改变裁剪区域不恢复的话后续所有绘制都被限制在圆内。我踩过的坑是裁剪区域一旦设置连clearRect都受它约束导致想清空画布却清不干净。所以凡是用了clip务必用save/restore包起来。提示clip的路径必须在clip调用前用beginPath重新构建否则会继承之前的路径裁剪区域和预期不符。这是真机上特别容易出问题的地方。2.4 坐标变换translate、rotate、scale的组合顺序坐标变换是画布做复杂布局的基础但组合顺序会显著影响结果。translate平移原点rotate绕原点旋转scale缩放坐标轴。关键规则是变换按调用顺序累积后调用的变换作用在前一次变换的基础上。举个实际例子要在画布上画一个绕自身中心旋转的矩形ctx.save() ctx.translate(cx, cy) // 先把原点移到矩形中心 ctx.rotate(angle) // 绕新原点即矩形中心旋转 ctx.fillRect(-w / 2, -h / 2, w, h) // 以中心为基准绘制 ctx.restore()如果顺序反过来先rotate再translate平移的方向会被旋转矩阵影响矩形跑到意想不到的位置。我的经验是先平移把原点挪到目标位置再做旋转和缩放最后以原点为中心绘制这个顺序最符合直觉也最容易调试。3. 图片合成与文字排版的完整实现流程3.1 drawImage的三种调用形式与图片加载时序drawImage支持三种参数形式三参数图片、x、y、五参数图片、x、y、宽、高、九参数图片、源图x、y、宽、高、目标x、y、宽、高。九参数形式是做图片裁剪合成的关键——你可以只取源图的一部分绘制到目标区域。但比参数更容易出问题的是图片加载时序。drawImage的图片参数可以是临时文件路径、网络图片需先下载或本地资源。如果图片还没加载完就调用drawImage真机上大概率画不出来开发者工具里却可能碰巧成功造成工具正常、真机白屏的经典问题。稳妥的做法是先把所有图片加载完再统一绘制function loadImage(src) { return new Promise((resolve, reject) { wx.getImageInfo({ src, success: res resolve(res.path), fail: reject }) }) } async function composePoster() { const [bg, avatar] await Promise.all([ loadImage(bgUrl), loadImage(avatarUrl) ]) const ctx wx.createCanvasContext(posterCanvas) ctx.drawImage(bg, 0, 0, 375, 600) ctx.drawImage(avatar, 20, 20, 80, 80) ctx.draw() }wx.getImageInfo不仅能拿到本地路径还能拿到图片的原始宽高这对保持图片比例、计算裁剪区域非常有用。网络图片必须先通过它或wx.downloadFile转成本地路径才能稳定绘制。3.2 文字排版measureText与多行文本换行画布里的文字不会自动换行长文本必须手动计算断行位置。measureText返回文本的宽度信息配合画布宽度就能实现自动换行。核心逻辑是逐字累加宽度超过最大宽度就换行。function wrapText(ctx, text, maxWidth, lineHeight, x, y) { let line let currentY y for (let i 0; i text.length; i) { const testLine line text[i] const metrics ctx.measureText(testLine) if (metrics.width maxWidth line ! ) { ctx.fillText(line, x, currentY) line text[i] currentY lineHeight } else { line testLine } } ctx.fillText(line, x, currentY) }这里有几个细节值得注意measureText在旧版接口里返回的宽度是同步可用的但字体设置必须在测量前完成否则测出来的是默认字体的宽度中英文混排时逐字断行可能在英文单词中间断开追求效果的话可以按空格和标点做断词优化setTextAlign和setTextBaseline会影响fillText的定位基准做居中排版时先设好对齐方式再计算坐标。3.3 图片与文字的图层叠加顺序画布是后画的盖住先画的图层顺序完全由绘制调用顺序决定。做海报这类合成场景正确的顺序是背景图 → 装饰图形 → 头像/图片 → 文字 → 水印。任何一步顺序错了要么被遮挡要么遮挡了不该遮挡的内容。我习惯在代码里用注释明确标注图层并且把每一层的绘制封装成独立函数主流程只负责按顺序调用。这样调整图层时只需要挪动函数调用位置不用在几百行代码里找哪句drawImage该放前面。注意draw是异步提交绘制指令的多次调用draw之间如果没有等待可能出现指令交错。合成场景建议所有绘制完成后只调用一次draw需要分阶段渲染时用draw的回调串起来。4. 渐变填充、导出与跨端适配的问题排查4.1 线性渐变与径向渐变的参数计算createLinearGradient(x0, y0, x1, y1)定义渐变的方向和范围addColorStop(offset, color)添加色标offset取值0到1。渐变对象创建后赋给setFillStyle或setStrokeStyle即可生效。const grd ctx.createLinearGradient(0, 0, 0, 200) grd.addColorStop(0, #ff9a9e) grd.addColorStop(1, #fad0c4) ctx.setFillStyle(grd) ctx.fillRect(0, 0, 375, 200)参数计算的关键是理解渐变线的几何意义渐变沿着从(x0,y0)到(x1,y1)的直线方向变化垂直于这条线的方向上颜色相同。做水平渐变就让y坐标相同、x坐标不同做对角线渐变就让两个坐标都变化。径向渐变createCircularGradient(x, y, r)以(x,y)为圆心、r为半径从中心向外渐变做光晕、按钮高光很合适。一个常见误区是渐变坐标用了画布的样式尺寸比如375但画布实际绘制尺寸是另一套值导致渐变范围对不上。渐变坐标必须和绘制坐标使用同一套尺寸体系这一点在做了scale变换后尤其要注意。4.2 canvasToTempFilePath导出图片的完整流程导出是画布项目最常见的收尾动作canvasToTempFilePath把画布内容转成临时文件可以预览、保存或上传。它的参数里canvasId旧版或canvas节点新版、x/y/width/height导出区域、destWidth/destHeight输出分辨率是关键。wx.canvasToTempFilePath({ canvasId: posterCanvas, x: 0, y: 0, width: 375, height: 600, destWidth: 750, destHeight: 1200, success: res { // res.tempFilePath 即生成的图片路径 wx.previewImage({ urls: [res.tempFilePath] }) }, fail: err console.error(导出失败, err) })destWidth/destHeight设成绘制尺寸的两倍是为了在高分屏上导出更清晰的图片——画布按逻辑像素绘制导出时按物理像素输出相当于做了2倍图。但要注意内存尺寸越大导出耗时和内存占用越高超过一定阈值在低端机上可能失败。4.3 真机与开发者工具差异的排查清单画布相关的工具正常、真机异常问题我整理了一张速查表基本覆盖了八成以上的排查场景现象可能原因排查方向真机白屏图片未加载完就绘制用getImageInfo预加载Promise.all等待图形错位画布样式尺寸与绘制尺寸不一致统一用节点查询拿实际尺寸文字不显示字体设置晚于fillText先setFontSize再绘制导出模糊destWidth未按倍率放大按设备像素比设置输出尺寸裁剪失效clip前未beginPath重建路径后再裁剪渐变异常渐变坐标与绘制坐标体系不一致检查是否受scale影响真机排查的核心方法是分段验证把复杂绘制拆成几个简单步骤逐步draw看哪一步开始出问题。另外真机的画布尺寸获取建议用wx.createSelectorQuery查询节点实际宽高而不是硬编码这样能适配不同屏幕。提示旧版画布的draw在部分机型上有延迟连续快速调用可能丢帧。需要动画时优先考虑新版Canvas 2D配合requestAnimationFrame旧版更适合静态合成场景。5. 我在画布项目里踩过的坑与实操心得5.1 尺寸体系混乱是万恶之源画布有两套尺寸样式尺寸CSS里写的宽高和绘制尺寸canvas标签的width/height属性或绘制时用的坐标系。旧版接口里绘制坐标系默认以样式尺寸为准但导出时又涉及物理像素三者不统一就会错位。我的做法是页面加载时用节点查询拿到画布实际宽高存成变量所有绘制坐标都基于这个变量计算绝不硬编码数字。这样换机型、换布局都不用改绘图代码。5.2 异步时序要用Promise串起来画布绘制涉及图片加载、字体加载、导出等多个异步环节用回调嵌套写出来的代码又长又难维护。我习惯把每个异步操作封装成Promise用async/await组织主流程出错时统一catch。这样不仅代码清晰排查问题时也能快速定位是哪个环节失败。5.3 复杂画布要拆函数、加注释、留调试开关一个几百行的绘图函数改一个颜色都要找半天。我的经验是按图层拆函数每个函数只负责一层函数名体现图层含义关键坐标用常量或变量命名不写魔法数字留一个调试开关打开时给每个图层画边框方便定位错位问题。这些习惯在项目后期维护时能省下大量时间。画布API看着零散但按能力域梳理清楚、把状态管理和异步时序这两个核心机制吃透大部分需求都能稳稳落地。真正拉开差距的不是记住了多少API而是对绘制指令何时生效坐标体系如何统一这些底层逻辑的理解深度。