小程序旧版 canvas 停维,海报功能要改
微信官方已写明旧版 canvas 接口不再维护。本文给出三类项目的决策树、按人天算的改造成本、5 条真机排错表和 8 条验收清单,帮企业负责人判断这次改造谁必须动、谁可以等。
小程序旧版 canvas 停维,海报功能要改
微信官方已写明旧版 canvas 接口不再维护,带海报、分享图、证书生成的小程序都得动。这篇不算改造成本、给决策树、排错表和验收清单:谁必须改,谁可以先等,一天工能不能搞定。
一、先看清楚官方到底说了什么
微信开放文档的《旧版 Canvas 迁移指南》,最后编辑 2026-11-12,第一句就是「小程序的旧版 canvas 接口已经不再维护」。同一张对比表里还写着:旧接口不支持同层渲染、绘制是异步的、性能一栏给的是「低」。
这句话的分量不在「不支持」,在「不再维护」四个字。意思是以后新机型、新基础库上冒出来的问题,官方不会修,也不会给你兜底。
同期还有两条值得放一起看。Skyline 1.4.25 在 2026-11-12 发布,优化了引擎启动流程,安卓和鸿蒙退页时主动释放内存;开发者工具稳定版 2.02.2609250(2026-11-06)修了 Skyline 页面首开偶发黑屏、窗口反复销毁后共享内存膨胀。渲染层在往 Skyline 收,画布能力在往标准 Canvas 2D 收,旧接口是这场收拢里被让掉的那一个。
二、技术上讲,这不是换个属性名
三处硬差异,任何一处没改到位,页面都会「看起来正常、导出来是废图」。
第一处是标签。旧写法用 canvas-id,新写法是 id 加 type="2d":
<!-- 旧 -->
<!-- 新 -->
第二处是取上下文改成异步。旧代码一句 wx.createCanvasContext('poster') 拿到 ctx;新接口要先查节点,再拿上下文:
wx.createSelectorQuery().in(this) // 写在组件里必须带 in(this)
.select('#poster')
.fields({ node: true, size: true })
.exec((res) => {
const canvas = res[0].node
const ctx = canvas.getContext('2d')
const dpr = wx.getWindowInfo().pixelRatio
canvas.width = res[0].width * dpr
canvas.height = res[0].height * dpr
ctx.scale(dpr, dpr)
// 从这一行往下才是绘制
})
第三处是坐标系。新版画布默认 300×150,不设 canvas.width 就按默认走,出图必然是糊的——而且糊得很均匀,容易被当成设计图分辨率问题,这是最费时间的误判。
还有两个隐性变化。旧接口的 draw(false) 表示不保留上次绘制内容,新版没有 draw 了,得在画之前手动 clearRect;wx.canvasGetImageData / wx.canvasPutImageData 也停用了,改成 ctx.getImageData / ctx.putImageData。
导图这一步没变,wx.canvasToTempFilePath 还能用,只是参数要传 canvas 实例,不再是 canvasId。
三、谁必须改,谁可以先等
这是老板最该先看的一段。三类情况,代价完全不同。
必须今年改的:已经切 Skyline、或计划在半年内切 Skyline 的项目。旧接口不支持同层渲染,画布会被原生层压住,优惠券、抽奖浮层、客服按钮全压不上去。这不是性能问题,是功能不可用。
建议这个季度改的:海报、分享图、证书、邀请卡这类高频生成功能。旧接口的异步绘制在低端安卓上会排队,用户点击到出图要等 1-3 秒,中途切后台就白屏。改造后同步绘制,这个等待基本消失。
可以排到明年的:只在一次性活动里用过画布、且三个月内没有新活动的小程序。但要在需求池里挂一条,下一次做活动前处理掉,别等到活动上线前一天发现画不出来。
判断依据不是「旧接口现在还能跑」,而是「出问题的时候你能不能自己修」。官方不修,你不修,那就是线上挂着。
四、成本怎么算,别按「改个属性」报价
按我们的经验值(不是官方口径,仅作预算参考):单个海报模板从改造到验收,0.5-1 人天;五到八个模板的项目,5-7 个工作日;如果模板逻辑散落在多个页面、还引了第三方插件,往上再加 2 天盘点时间。
钱花在哪,列清楚更实在:
| 环节 | 工作量 | 容易低估的地方 |
|---|---|---|
| 盘点调用点 | 0.5 人天 | 插件和第三方组件里藏着 canvas,全局搜 createCanvasContext 才是全部 |
| 抽公共方法 | 1 人天 | dpr、圆角、中文换行、导出,各页面重复写一遍等于把坑复制 N 份 |
| 页面替换 | 每模板 0.5 人天 | 二维码位置、字体基线,全靠调 |
| 真机回归 | 1-2 人天 | iOS、安卓中端机、鸿蒙各一台,模拟器看不出模糊和错位 |
这笔钱的性质要认清:它不是新功能投入,是风险买断。不改,省下的是一天工;改,省下的是每次活动上线前那两小时救火,以及一次「分享图全糊、活动当天没法发」的事故。
五、真踩过的坑,按症状查
| 症状 | 根因 | 处理 |
|---|---|---|
| 图能出,但整体发虚、字边缘发灰 | 没设 canvas.width/height 或漏了 ctx.scale(dpr,dpr) | 先设物理尺寸再缩放,两步都不能省 |
res[0] 是 undefined,代码不报错也不执行 | SelectorQuery 写在自定义组件里没带 in(this),或画布容器 display:none | 补 in(this);隐藏容器先渲染再画 |
| 出图和屏幕显示不一致,长图底部被截 | 画布高度按 CSS 高度算,没按内容实际高度 | 按内容累计高度设置 canvas.height |
| 迁移后上一张图的残影叠在新图上 | 旧代码依赖 draw(false) 自动清屏,新版没有 | 每次绘制前 clearRect(0,0,w,h) |
| 导出拿到空白图 | 同步绘制后立刻导出,图片资源还没 onload | 等 img.onload 再画,再导 |
六、改完怎么算合格
这张清单可以直接拿去验收,八条全过再上线:
- iOS、安卓、鸿蒙各一台真机,出图清晰度与设计稿一致;
- 长图(高度超过两屏)底部内容完整,无截断;
- 连续生成 5 次,无残影、无内存持续上涨;
- 从点击到出图,中端安卓机型在 1 秒内完成;
- 切后台再回前台,生成流程能走完;
- 分享出去的图片在微信内打开不糊边;
- 图片资源加载失败时有兜底,不出现空白海报;
- 线上灰度一周,无新增 JS 报错。
七、结论
该改。给出的判断是:这不是「要不要跟新技术」的选择题,是「要不要留一个自己修不了的接口」的风险题。
时间窗很明确——Skyline 是后续版本的默认方向,切过去那天,没过迁移的 canvas 会从「勉强能用」直接变成「弹层压不住」。建议把这个改造排进当前迭代,别等 Skyline 上线再返工,那时候改的是紧急故障,不是计划任务。
FAQ
Q1:新版还能用 wx.canvasToTempFilePath 吗?
能,参数传 canvas 实例(res[0].node),不再传 canvasId。
Q2:我们只有一处画布,也值得改吗?
值得,但只值半天。一处画布的改造成本低于一次线上事故的沟通成本,顺手改掉就行。
Q3:用了第三方海报插件还要自己改吗?
先看插件是否已适配 type="2d"。没适配就只有两条路:等插件更新,或把生成逻辑收到自己项目里——多数情况后者更快。
延伸阅读
- 小程序常见问题:类目、审核、基础库问题都在这一栏
- 技术专业区:架构与性能类拆解
- 网站常见问题:上线前的备案、域名与服务器配置