微信小程序海报生成全攻略：Canvas绘制、图片预加载与性能优化

微信小程序生成海报这件事，看起来只是把几张图拼在一起、加个二维码、写几行字，但真正做过的人都知道，这里面的坑远比想象中多。我前后在三个不同的小程序项目里落地过海报生成功能，从最初的纯前端 Canvas 手撸，到后来引入离屏画布做预渲染，再到现在用一套相对成熟的组件化方案，中间踩过的坑包括但不限于：真机上文字错位、图片跨域加载失败、导出图片模糊、安卓和 iOS 表现不一致、用户保存到相册时权限被拒等等。这篇文章就把我这些年积累下来的完整方案、核心原理、实操步骤和避坑经验一次性讲清楚，适合正在做或准备做小程序海报功能的开发者参考，也适合想了解 Canvas 绘图机制的前端同学。

1. 先搞清楚海报生成到底难在哪里

很多人接到需求的第一反应是：不就是画个图吗？Canvas 画完导出不就行了？但小程序环境下的 Canvas 和浏览器里的 Canvas 差别很大，如果不提前理解这些差异，后面会反复返工。

1.1 小程序 Canvas 的两套体系：旧版和新版

小程序目前存在两套 Canvas 接口。旧版是<canvas canvas-id="xxx">配合wx.createCanvasContext，这套接口从早期一直沿用至今，优点是兼容性好，缺点是 API 设计比较反直觉，绘制是异步的，需要调用draw()才真正渲染。新版是<canvas type="2d">配合wx.createSelectorQuery获取节点，然后拿到标准的 Canvas 2D 上下文，API 和浏览器几乎一致，支持createImage()、requestAnimationFrame等能力。

我的建议很明确：新项目一律用新版 2D 接口。原因有三个：第一，新版支持离屏 Canvas，可以先把海报画好再一次性渲染到页面上，避免用户看到绘制过程；第二，新版导出图片的质量和尺寸控制更精确；第三，旧版接口在某些安卓机型上有已知的文字渲染偏移问题，官方虽然修过几轮，但新版明显更稳定。

1.2 为什么真机上总是和开发者工具不一样

这是最让人头疼的问题。开发者工具用的是桌面浏览器的渲染引擎，而真机用的是各平台自己的渲染内核。差异主要体现在三个方面：

• 字体渲染：不同系统默认字体不同，iOS 用苹方，安卓用思源黑体或厂商定制字体，同一个字号在不同设备上占用的宽度可能差 10% 到 20%。
• 图片解码时机：开发者工具里图片加载几乎是瞬时的，真机上网络图片需要真实下载和解码时间，如果没等图片加载完就绘制，出来的就是空白。
• 像素比处理：高清屏的devicePixelRatio不同，如果不做缩放处理，导出的图片在部分机型上会模糊。

理解了这些差异，后面的方案设计就有了方向：所有尺寸计算要基于实际测量，所有图片加载要显式等待，所有导出要按像素比放大。

1.3 海报功能的完整链路拆解

一个完整的海报生成功能，实际上包含这些环节：

1. 获取海报配置数据（背景图、商品图、文案、二维码等）
2. 预加载所有图片资源
3. 创建画布并设置正确的尺寸和像素比
4. 按层级依次绘制背景、图片、文字、二维码
5. 导出为临时文件
6. 展示预览并提供保存到相册的能力
7. 处理保存权限和失败重试

任何一个环节出问题，最终用户看到的就是一张残缺或模糊的图。下面我按这个链路逐步展开。

2. 图片预加载：海报生成的第一道坎

海报里的图片通常来自网络，包括背景图、商品主图、用户头像、二维码等。这些图片如果不预加载就直接绘制，结果一定是空白或者部分空白。

2.1 用 createImage 逐个加载并等待

新版 Canvas 提供了canvas.createImage()方法，可以创建一个图片对象。关键是要等onload回调触发后才能绘制。我通常封装一个loadImage函数：

function loadImage(canvas, src) { return new Promise((resolve, reject) => { const img = canvas.createImage(); img.onload = () => resolve(img); img.onerror = (e) => reject(new Error(`图片加载失败: ${src}`)); img.src = src; }); }

然后对所有图片用Promise.all并行加载：

const [bgImg, goodsImg, avatarImg, qrImg] = await Promise.all([ loadImage(canvas, bgUrl), loadImage(canvas, goodsUrl), loadImage(canvas, avatarUrl), loadImage(canvas, qrUrl) ]);

这里有个细节：并行加载虽然快，但如果某张图失败，整个 Promise.all 会直接 reject。实际项目中我建议用Promise.allSettled，然后对失败的图片做降级处理，比如用一张默认占位图代替，而不是让整个海报生成失败。

2.2 图片跨域和域名白名单问题

小程序的网络图片必须配置在downloadFile合法域名列表里，否则真机上会加载失败。这个问题在开发者工具里经常被忽略，因为工具里可以勾选"不校验合法域名"，但上线后就会暴露。

我的经验是：海报里用到的所有图片域名，提前在项目配置里全部加好。如果图片来自第三方 CDN 且无法控制，那就需要在服务端做一层中转，把图片转成自己的域名再返回。另外，二维码如果是动态生成的，建议服务端直接返回图片流或者 base64，避免前端再去请求外部域名。

2.3 图片尺寸未知时的处理策略

有时候图片的宽高在加载前是未知的，比如用户上传的头像。这时候有两种处理方式：

• 裁剪填充：按目标区域的宽高比，从原图中心裁剪，保证填满不留白。适合头像、商品图这类需要统一视觉的场景。
• 等比缩放：按原图比例缩放到目标区域内，可能留白。适合二维码、logo 这类不能变形的图。

裁剪填充的计算逻辑是：先算出原图和目标区域的宽高比，如果原图更宽，就按高度缩放，然后水平居中裁剪；如果原图更高，就按宽度缩放，然后垂直居中裁剪。这个逻辑封装成函数后可以复用。

3. 画布尺寸与像素比：决定清晰度的关键

海报模糊是最高频的投诉之一。根本原因通常是画布尺寸设置不对，或者没有考虑设备像素比。

3.1 逻辑尺寸和物理尺寸的关系

假设设计稿给的海报尺寸是 750x1334 像素（这是常见的设计稿宽度）。在代码里，我们需要区分两个概念：

• 逻辑尺寸：画布在页面上占用的 CSS 尺寸，比如 375x667。
• 物理尺寸：画布实际用于绘制的像素尺寸，应该是逻辑尺寸乘以devicePixelRatio。

如果只设置逻辑尺寸，在 2 倍屏或 3 倍屏上，导出的图片就是按逻辑尺寸来的，会明显模糊。正确的做法是：

const dpr = wx.getSystemInfoSync().pixelRatio; const logicalWidth = 375; const logicalHeight = 667; canvas.width = logicalWidth * dpr; canvas.height = logicalHeight * dpr; ctx.scale(dpr, dpr);

这样设置后，所有绘制坐标仍然按逻辑尺寸来写，但实际渲染是按物理像素来的，导出就清晰了。

3.2 导出时的尺寸控制

wx.canvasToTempFilePath支持传入destWidth和destHeight参数。如果不传，默认按画布的物理尺寸导出。我的建议是显式传入设计稿的尺寸，比如 750x1334，这样无论用户设备是什么，导出的海报尺寸都一致，便于后续分享和打印。

但要注意：如果画布物理尺寸小于导出尺寸，放大后会模糊。所以画布的物理尺寸应该大于等于导出尺寸。实践中我会把画布物理尺寸设置为设计稿尺寸的 2 倍，导出时按设计稿尺寸输出，这样既清晰又不会文件过大。

3.3 不同机型的适配策略

虽然海报是固定尺寸的，但展示海报的容器需要适配不同屏幕。我的做法是：海报本身按固定尺寸生成，展示时用image组件的mode="widthFix"或aspectFit来适配容器。这样海报内容不会变形，展示也自然。

如果确实需要海报尺寸随屏幕变化，那就需要动态计算所有元素的坐标和字号。这种方案复杂度高很多，除非产品明确要求，否则不建议。

4. 绘制顺序与文字排版：细节决定成败

画布绘制是有层级顺序的，后画的会覆盖先画的。所以绘制顺序必须是：背景图 → 装饰元素 → 商品图 → 文字 → 二维码 → 水印。

4.1 文字绘制的常见坑

文字是最容易出问题的部分。几个关键点：

• 文字换行：Canvas 没有自动换行，需要手动计算。基本思路是逐字测量宽度，超过最大宽度就换行。但要注意中英文混排时，英文单词不应该被拆断。
• 文字对齐：ctx.textAlign可以设置left、center、right，但要注意设置后所有文字都会受影响，画完记得重置。
• 行高控制：Canvas 没有行高属性，需要手动控制每行文字的 y 坐标，通常是字号乘以 1.4 到 1.6。
• 文字截断：如果文字太长，超出区域后应该用省略号截断，而不是让它溢出。

我封装过一个drawText函数，支持最大宽度、最大行数、超出省略，实际用下来能覆盖 90% 的文案场景。

4.2 圆角图片和圆形头像的绘制

Canvas 本身没有直接画圆角图片的 API，需要用clip配合路径来实现。圆形头像的逻辑是：

ctx.save(); ctx.beginPath(); ctx.arc(x + r, y + r, r, 0, Math.PI * 2); ctx.closePath(); ctx.clip(); ctx.drawImage(avatarImg, x, y, size, size); ctx.restore();

圆角矩形类似，用arcTo画路径后裁剪。注意save和restore一定要配对，否则裁剪区域会影响后续绘制。

4.3 二维码的定位与容错

二维码通常放在右下角或底部居中。位置要留足边距，避免被裁切。另外，二维码周围最好留白，不要紧贴其他元素，否则可能影响识别率。如果二维码是动态生成的，建议服务端生成时就把 logo 合成好，前端直接绘制整张二维码图片，减少前端复杂度。

5. 导出、预览与保存：最后一公里的体验

海报画完了，导出和保存环节同样有很多细节。

5.1 canvasToTempFilePath 的正确用法

这个 API 的参数不少，常用的有：

注意：新版接口需要传canvas节点而不是canvasId，这个在迁移时容易搞错。

5.2 保存到相册的权限处理

wx.saveImageToPhotosAlbum需要用户授权scope.writePhotosAlbum。如果用户之前拒绝过，再次调用会直接失败，需要引导用户去设置页手动开启。完整的处理流程是：

1. 调用保存接口
2. 如果失败且错误信息包含"auth deny"，弹出提示引导用户去设置
3. 用户确认后调用wx.openSetting打开设置页
4. 用户开启权限后重新保存

这个流程一定要做完整，否则用户点了保存没反应，体验很差。

5.3 长按保存和分享的补充方案

除了按钮保存，还可以支持长按海报图片保存。用image组件的show-menu-by-longpress属性即可开启。另外，如果海报要用于分享，可以配合onShareAppMessage自定义分享图，但注意分享图有尺寸限制，不能直接用大尺寸海报。

6. 性能优化与异常兜底

海报生成涉及大量绘图操作，如果不做优化，在低端机上可能卡顿甚至闪退。

6.1 离屏 Canvas 预渲染

新版 Canvas 支持wx.createOffscreenCanvas，可以在后台先把海报画好，再一次性绘制到页面画布上。这样做的好处是用户看不到绘制过程，体验更流畅。离屏 Canvas 的用法和普通 Canvas 基本一致，只是不需要绑定到页面节点。

6.2 缓存已生成的海报

如果海报内容不变（比如同一个商品同一个用户），可以把生成的海报临时文件路径缓存起来，下次直接展示，不用重新绘制。缓存可以用全局变量或本地存储，注意设置合理的过期时间。

6.3 异常情况的兜底

海报生成可能失败的环节很多：图片加载失败、画布创建失败、导出失败、保存失败。每个环节都要有兜底：

• 图片加载失败：用占位图代替，并记录日志
• 画布创建失败：提示用户重试
• 导出失败：检查画布尺寸是否过大，尝试降低尺寸重试
• 保存失败：按权限流程处理

我通常会在关键节点加try-catch，并把错误信息上报，方便排查线上问题。

7. 我踩过的几个真实坑和解决方案

最后分享几个实际项目中踩过的坑，都是文档里不会写的。

第一个坑：iOS 上文字偏上。原因是 iOS 的textBaseline默认行为和安卓不同。解决方案是显式设置ctx.textBaseline = 'middle'或'top'，不要依赖默认值。

第二个坑：安卓上导出图片有黑边。原因是画布尺寸设置了小数，某些安卓机型渲染时会出现半像素问题。解决方案是所有尺寸取整，用Math.floor处理。

第三个坑：二维码在部分机型上识别不了。排查后发现是二维码被缩放了非整数倍，导致边缘模糊。解决方案是二维码按原始尺寸绘制，不缩放，或者缩放时用整数倍。

第四个坑：并发生成多张海报时内存暴涨。原因是每次生成都创建了新画布，旧画布没有释放。解决方案是复用同一个画布，或者生成完后手动置空引用。

第五个坑：用户快速点击保存按钮导致重复保存。解决方案是加一个 loading 状态，保存期间禁用按钮。

这些坑看起来都是小问题，但每一个都可能让功能在线上出故障。做海报功能，细心比技术更重要。

关于后续扩展，如果产品需要支持用户自定义海报模板，可以考虑把绘制逻辑抽象成配置驱动的模式，用 JSON 描述每个元素的位置、样式、内容，这样新增模板就不用改代码了。我在一个项目里做过这个方案，维护成本降低了很多，但前期设计配置结构需要花点心思。