最近在做一个移动端H5的活动模块，遇到一个很常见但坑不少的需求：在页面里生成一张二维码，并让用户能保存或分享出去。最初方案很直接，让后端返回一个二维码图片地址，丢进img标签就行。但做到后面发现根本不够，运营要往二维码上叠加背景图、Logo和标题文案，用户还要保存到相册，前端还得把最终图片上传给后端。最后一个落地做法就是标题里写的这条链路：react APP内置移动端h5，用canvas画布绘制二维码，再把canvas转成base64链接。这篇文章把完整实现流程、踩过的坑和排查方法都整理出来，希望对正在做类似功能的人有帮助。
1. 为什么绕一圈：canvas画二维码而不是直接放img
1.1 先复盘一下真实需求场景
我做的是一个App内置H5页面，核心功能是给用户生成一张专属二维码，扫码后可以跳转到活动落地页。二维码内容里面有一串活动ID和用户标识，每个用户的内容都不一样。表面上需求很简单：页面中间放个二维码图片，用户截图保存就行。
但走到产品评审阶段，运营提了几个要求：二维码要能放在一张活动海报上，海报要带背景图、品牌Logo、用户昵称和一句邀请文案；用户点击“保存海报”之后，手机上落地的是一张完整图片，而不是只有二维码；同时，这张图还要能被上传到我们的文件服务，方便生成分享链接。这就意味着，前端不能只展示一张后端生成好的二维码图，还需要自己去拼装图片内容，再导出成一个文件。
后端生成图片的方案我也考虑过。服务端用图表库画图、拼上背景、文字，再输出图片流，确实是可行的。但有一个问题：用户角度每一次请求都要实时生成图片，而且前端如果改了模板或者文案，后端要跟着改逻辑，沟通成本很高。尤其是我们后期准备做多个活动模板，前端可以随时切换样式，这个方案就变得很僵。把图片合成放到前端，至少模板和排版完全可控。
1.2 直接渲染img的两个痛点
第一个痛点是样式定制能力太弱。img标签只能展示一张静态图片，想把二维码放在某个坐标位置、给码眼换个颜色、调整周围留白，全部无从下手。有人说可以用CSS做圆角、加边框、加阴影，但那些都是围绕整个img节点的视觉装饰，不是对二维码本身进行定制。真正的海报合成场景，不光是把图片塞进页面，而是要把二维码画在背景图上方某个位置，这需要像素级控制。
第二个痛点是不利于二次加工和上传。当时我们要做一个“保存海报到相册”的功能，如果页面里只是一张img，在移动端基本只能靠用户长按图片保存。Android普通浏览器大多可以，但很多App内WebView里，长按事件会被WebView拦截，系统无法弹出保存菜单。iOS的Safari对长按图片的支持也不稳定，尤其图片是用data URL或者异步加载出来的，经常弹不出“存储图像”的选项。最后我不得不换思路：既然最终要保存的是一张完整海报，不如直接用canvas把所有内容画出来，再导出成文件，走文件下载或调用原生桥接保存。
还有一个隐藏问题：如果图片需要上传，img节点本身没法直接变成文件，你得再通过canvas或fetch去拿图片数据，绕了一圈代码更多。比较干净的链路是从canvas直接导出数据，再转成文件上传。
1.3 为什么选canvas + base64这条链路
canvas提供了一个可控的2D画布，你可以控制画什么、画在哪里、用什么颜色，最后统一导出。我们最终拿到的base64链接，本质上是一段字符串，可以给img的src赋值，也可以传给fetch，还可以直接塞进表单提交。整个过程不依赖外部图片地址，不增加HTTP请求，在移动端H5里非常直接。
有人会问：那直接用canvas.toBlob不更好吗，Blob比base64更轻量。实测是：toBlob确实更适合文件上传，但兼容性和调试方便性不如toDataURL。我的习惯是先在代码里把base64打印出来看格式，确认画布内容没问题，再考虑转成Blob给后端。而且很多内嵌WebView的桥接方法，原生端拿到的也是字符串形式的图片数据，base64反而是最通用的传递格式。
还有一层原因：二维码并不是只有黑白色块，很多时候我们需要在canvas里画好二维码矩阵，再叠一层背景、Logo，甚至做圆角蒙版。只有canvas能让我们在绘制环节直接介入，img做不到。
2. 技术选型与前置知识
2.1 二维码生成库怎么选
实现二维码绘制，最原始的做法是自己写编码器，把字符串转成二维码矩阵，计算纠错码，再做掩码操作。这不是不能做，但工作量大到足够开一个新项目了。实测没必要，成熟的库能节省大量时间。
我调研后选中了npm包qrcode。它在浏览器端可以直接把内容绘制到canvas节点上，核心API是QRCode.toCanvas(canvas, text, options, callback)。它还支持设置容错级别L/M/Q/H、尺寸、边距、颜色等，覆盖了我们的需求。
另一类选择是React组件形库，比如qrcode.react，可以直接写<QRCodeCanvas value="..." />。它的优点是声明式，缺点是你很难在组件内部精确控制绘制时机。后来我项目里有需要等背景图加载完再绘制二维码的场景，用声明式组件反而别扭。所以我选择了偏底层的qrcode库，手写一个小封装。
用库要注意运行环境。qrcode包在Node端也能用，比如生成SVG、字符串流等。但在SSR或服务端渲染页面时，千万不要在服务器端调用canvas绘制，因为没有真实DOM。canvas相关操作必须限制在客户端Effect内执行。
2.2 base64链接的本质和适用范围
base64链接也叫data URL，标准格式是：
data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...前段是MIME类型，中间是编码方式，后面是图片数据的base64字符串。浏览器看到这个协议，不会发起HTTP请求，直接解码字符串渲染图片。它最大的优点是“一张图片变成一段文字”，方便嵌入到各种接口、存储端、桥接消息里。缺点也很明显：同样一张图片，它的体积比原始二进制大约1.33倍。如果画布很大，base64字符串会非常长，可能造成页面卡顿和传输压力。
所以拿到base64之后，要判断下一步怎么用。如果只是页面里展示，没毛病。如果要传给后端，建议转成Blob/File再上传。如果是要保存到相册，也需要转成文件，再通过下载或桥接方法处理。我习惯把它看作一种交互中间态，而不是最终产品数据。
2.3 React生命周期和Canvas绘制时机
很多第一次写canvas的人，会在组件render函数里直接调用绘制方法，结果拿到的canvas是空的。原因很简单：render阶段还没有把真实DOM挂到页面上，此时通过ref拿到的节点可能是null，或者刚创建但还没有完成布局。
正确做法是把绘制逻辑放在useEffect里，等React提交DOM之后再执行。同时要注意Effect的依赖数组。二维码内容变了要重绘，尺寸变了要重绘，异步数据加载完后也要触发一次重绘。常见写法：
const canvasRef = useRef(null); const [dataUrl, setDataUrl] = useState(''); useEffect(() => { if (!canvasRef.current || !text) return; QRCode.toCanvas(canvasRef.current, text, { width: 240, margin: 2 }, (err) => { if (err) { console.error(err); return; } try { const url = canvasRef.current.toDataURL('image/png'); setDataUrl(url); } catch (e) { console.error('canvas export failed', e); } }); }, [text]);需要注意一个细节：QRCode.toCanvas在浏览器里是异步绘制，它的回调函数表示绘制完成。如果你在它调用之后立刻执行toDataURL，大概率拿到的是空白画布。所以toDataURL必须放在回调里执行，或者用Promise包装一下。
3. 核心实现：从canvas到base64的完整流程
3.1 搭建一个最小可运行的React组件
我建议实际项目里单独抽一个组件，职责就是“输入字符串，输出base64”。下面是最小实现的骨架：
import { useEffect, useRef, useState } from 'react'; import QRCode from 'qrcode'; function QrCanvas({ content, size = 280, margin = 2 }) { const canvasRef = useRef(null); const [dataUrl, setDataUrl] = useState(''); useEffect(() => { let cancelled = false; async function draw() { if (!canvasRef.current || !content) return; try { await new Promise((resolve, reject) => { QRCode.toCanvas(canvasRef.current, content, { width: size, margin, errorCorrectionLevel: 'M', }, (err) => { if (err) reject(err); else resolve(); }); }); if (!cancelled) { const url = canvasRef.current.toDataURL('image/png'); setDataUrl(url); } } catch (e) { console.error('二维码生成失败', e); } } draw(); return () => { cancelled = true; }; }, [content, size, margin]); return ( <div> <canvas ref={canvasRef} style={{ width: size, height: size }} /> {dataUrl && ( <img src={dataUrl} alt="二维码预览" style={{ width: size, height: size }} /> )} </div> ); }这个组件的思路是：canvas负责实际绘制，img负责展示base64的情况。开发调试时看到base64能正常显示，心里才踏实。
3.2 移动端高清适配：处理devicePixelRatio
移动端屏幕的CSS尺寸和物理像素不是一个概念。比如iPhone的逻辑宽度是375px，但物理像素可能是750px或者1125px。如果你只给canvas设置宽高为280px，浏览器会把它拉伸到物理像素尺寸，二维码边缘会出现明显锯齿。二维码本身是黑白格图，锯齿会让识别率下降。
解决办法是让canvas的位图像素放大到设备像素比，绘制时再缩放坐标系：
const dpr = window.devicePixelRatio || 1; const drawSize = Math.floor(size * dpr); canvas.width = drawSize; canvas.height = drawSize; const ctx = canvas.getContext('2d'); ctx.scale(dpr, dpr);然后QRCode.toCanvas里的宽高参数继续用逻辑尺寸。这样画出来的二维码，一个逻辑像素对应dpr个物理像素，清晰度非常高。
注意dpr不是越大越好。画布宽高每乘一次dpr，内存占用是按平方增长的。如果dpr是3，280px的画布变840px，面积接近原来的9倍。二维码本身是色块，2到2.5倍就已经非常清晰，没必要盲目追满3倍。我现在的做法是设定一个上限值：Math.min(dpr, 2.5)。
3.3 颜色、边距、容错级别怎么配
二维码能扫出来，核心是靠黑白色块的对比和定位图形。容错级别决定了二维码在部分遮挡或破损时还能否被正确解码。一般选M级就够了，可以在7%左右的区域被遮挡时继续识别。如果二维码要叠加Logo，建议选Q或H级别，预留更多容错空间。
边距也很重要。标准二维码周围需要留白，也就是所谓的quiet zone，建议至少留2到4个模块的宽度。直接用库里的margin参数设置，不要自己再画白色边框去凑。实测中，margin太小会让扫码器更容易识别失败，尤其是用户用弱光环境或者老手机时。
背景颜色方面，移动端Canvas默认是透明背景。二维码本身是黑色块，透明背景在网页上看没问题，但到了深色海报上就完蛋，对比度不够，扫都扫不动。所以在绘制前先给画布铺一层白色或浅色背景：
ctx.fillStyle = '#ffffff'; ctx.fillRect(0, 0, canvas.width, canvas.height);这里有个顺序问题：填充背景必须在调用QRCode.toCanvas之前。如果顺序反了，二维码会被白色矩形盖住，相当于白画。我一开始就踩过这个坑，画了一大粘贴不出内容。
3.4 toDataURL的三种典型隐患
把canvas转成base64，就是调用canvas的toDataURL(type, quality)方法。type默认是image/png，也可以传image/jpeg和压缩质量。最常见的三个隐患是：
第一，透明背景问题。前面说了，直接toDataURL会把透明背景一起编码到图片里。如果二维码要在浅色海报上展示，问题不大；但放到深色海报上就会扫不出来。所以要么先画白底，要么转成JPEG，因为JPEG会强制去掉透明信息。
第二，跨域污染问题。一旦canvas里绘制了跨域图片资源，并且该图片没有以CORS方式加载，画布就会被标记为“被污染”。被污染之后，你调用toDataURL会抛SecurityError。这个问题我后面具体展开。
第三，字符串过大问题。PNG格式无损，体积大；canvas尺寸越大，base64越长。如果你只是生成一个二维码，几百毫秒没问题。但如果画布是整屏海报尺寸，字符串可能上MB，此时React setState渲染一个大字符串，页面会卡到掉帧。建议这种方式下改用toBlob导出文件，只在需要预览时生成一次base64。
4. 进阶：base64不仅仅是“链接”
4.1 把base64转换成可上传的File对象
前后端联调时，后端一般更喜欢接收multipart文件，而不是一个拼进JSON里的超长base64字符串。所以前端拿到base64后，通常还要转成File对象。
手写转换函数最稳：
function dataURLtoBlob(dataUrl) { const arr = dataUrl.split(','); const mime = arr[0].match(/:(.*?);/)[1]; const bstr = atob(arr[1]); let n = bstr.length; const u8arr = new Uint8Array(n); while (n--) { u8arr[n] = bstr.charCodeAt(n); } return new Blob([u8arr], { type: mime }); } function blobToFile(blob, fileName) { return new File([blob], fileName, { type: blob.type }); }用起来：
const blob = dataURLtoBlob(dataUrl); const file = blobToFile(blob, `qr-${Date.now()}.png`); const formData = new FormData(); formData.append('file', file); // 然后走你常用的上传请求还有一种更现代的写法是const blob = await (await fetch(dataUrl)).blob();，但低版本Android WebView对fetch的兼容性不算好。如果你要兼容老机型，还是用手动函数靠谱。
4.2 保存到相册和分享的实现思路
拿到了base64或者Blob，如何让用户真正保存下来？PC网页可以创建a标签，设置href为文件地址，download属性为文件名，然后模拟点击下载。移动端情况复杂很多。
在部分App内WebView里，最可靠的方式是把base64或者Blob通过桥接方法传给原生端，让原生端直接把图片写入相册。因为原生代码有权限和能力调用系统相册接口，Web端反而处处受限。如果没有桥接，也可以用URL.createObjectURL(blob)生成一个临时链接，然后交给浏览器或WebView的下载逻辑处理。
实测下来，iOS对data URL长按保存支持不稳定，但对Blob URL的下载按钮兼容性稍微好一点。不过最终方案还是要回归到你的具体平台：常规浏览器可以用a标签加click模拟；App内H5尽量走桥接；如果是第三方社交平台分享，图片需要先有公网地址，那就得把文件上传后拿URL，再发给分享组件。
4.3 与后端协作时到底传什么
跟后端对接时，先把接口约定问清楚，不要想当然。如果后端接受multipart，就传File对象，这是最通用、体积最小的方式。如果后端硬性要求JSON里带base64，那就传base64，但要注意图片大小，尽量压缩到合理范围。压缩时优先考虑减少画布尺寸，再考虑JPEG压缩质量；二维码图层不要压缩过度，否则识别率下降。
如果传base64，后端解码前通常要处理前缀。base64字符串里的data:image/png;base64,这段内容是MIME信息，不是图片数据本身。后端要么去掉前缀，要么对此做兼容。最好在接口文档里写清楚，避免前端省事全传，后端却按纯base64解析导致文件损坏。
5. 常见问题与排查实录
5.1 SecurityError：画布被污染
这个问题是我自己亲历的。页面上除了二维码，还要合成一张从CDN加载的活动背景图。CDN图片跟我们的站点不同域，我用new Image()加载它并画到canvas上，没有设置crossOrigin属性。结果第一次执行toDataURL，控制台就抛了SecurityError。
原因是浏览器为了安全，禁止从被污染的canvas读取像素数据。一旦canvas里画了跨域图片且没做跨域处理，整个画布都不可导出。解决办法分两步：
第一步，给图片对象设置img.crossOrigin = 'anonymous'，再赋src加载。第二步，确保图片服务器返回了正确的CORS响应头，比如Access-Control-Allow-Origin: *。如果你的CDN不支持，那就没办法从远端直接画，只能把图片先转为base64或者通过同域代理下载。
排查技巧是分层：先只导出纯二维码，看是不是正常的；再加入背景图，看是不是开始报错。这样能快速定位是哪一步污染了画布。
5.2 iOS下二维码生成出来是空白或黑块
有段时间真机测试发现，部分iPhone上如果设置canvas尺寸不是整数，会渲染异常。比如canvas.width = 280 * 1.5结果是480，这是整数，没问题。但如果dpr返回1.25，乘出来是350，实际浏览器可能会四舍五入，再加上后续绘制坐标偏移，就会出现空白或糊成一片的黑色块。
建议所有canvas宽高都做一次取整：Math.floor(size * dpr)。绘制时用逻辑尺寸，不要直接拿物理尺寸做CSS样式。二维码绘制不适合用小数坐标，尽量保证每一步尺寸都是整数。
还有一个情况是，如果QRCode.toCanvas的选项里margin设置过大，二维码自身会被压得很小，扫码器识别不到。真机上尤其明显。建议先保留默认边距或设为2，不要为了美观加太多。
5.3 base64太大导致页面卡顿
我做过一次海报导出，画布宽1080、高1440，合成背景图和二维码之后toDataURL('image/png')返回了接近4MB的base64。在React state里存这个字符串，再渲染预览图，整个页面滚动和点击都明显卡顿。
优化办法是把画布尺寸降到750宽度，背景用JPEG压缩导出，二维码单独用PNG导出再叠合。二维码区域不参与JPEG压缩，否则噪点会影响识别。另外，如果不需要立刻预览，尽量不要把base64放进state，可以先转成Blob，用URL.createObjectURL生成临时链接再展示。Blob URL比data URL更轻量，React渲染也更快。
5.4 React StrictMode下重复绘制
开发环境如果开了React.StrictMode，Effect会执行两次，canvas上的绘制内容会被画两次。二维码本身叠加绘制不会有大问题，但背景图或者文字一旦是半透明，就会出现颜色变深或文字重影。
清理方法是在Effect的return函数里重置canvas。重置宽高是最干净的清空方式：
return () => { if (canvasRef.current) { canvasRef.current.width = canvasRef.current.width; } };这么写会触发画布清空，同时也把之前的绘制状态全部丢掉。下次Effect执行再重新画一遍，不会重复叠加。
6. 再扩展一步：从单二维码到合成海报
6.1 绘制顺序决定最终效果
掌握了canvas转base64，基本就掌握了海报合成的核心。实际项目里，我们需要把背景图、标题文字、二维码、Logo、用户头像都画到一个canvas里。绘制顺序特别重要：先画最底层的背景大图，再画中间层的装饰框、文案，最后画二维码。如果顺序反了，二维码会被后续内容盖住。
画渐变背景时，注意要设置一个基本的白色底色。否则透明背景在导出PNG后，放到深色社交平台里显示会很奇怪。渐变本身可以用createLinearGradient创建，再填充一个矩形区域。
6.2 异步资源加载的竞态处理
画海报经常要加载图片资源，比如背景图、用户头像。图片是异步加载的，如果用户快速点击生成，或者快速切换模板，上一次的异步请求可能还没完成，就被下一次触发覆盖。如果不做处理，最终生成的海报可能混着上一次的背景图。
我的方案是给每次生成操作加一个自增序号，或者用一个latestToken。每次触发绘制前记录当前token，回调返回后检查token是否还是最新。不是最新就丢弃，不更新state。这个做法在React和原生应用里都通用，代码也不复杂。
6.3 性能与内存释放
移动端canvas操作对内存比较敏感。每创建一个大尺寸canvas，或者生成一个很大的dataURL，都会占用到几百KB甚至几MB内存。如果用户连续多次点击生成，React state里还存着历史base64，内存会快速上涨。
我现在的习惯是：临时展示只用Blob URL，不把base64长期挂在state里；每次生成新图片前，先调用URL.revokeObjectURL释放旧的Blob URL；海报导出完，把画布引用手动置空，方便垃圾回收。真机上用一段时间的DevTools面板看内存曲线，如果持续上升，基本就是有资源没有释放。
7. 这套方案的适用边界和我的真实体会
这套canvas转base64的方案，最适合的场景是移动端H5里的动态二维码、活动海报、分享卡片生成。它对前端控制力要求高，又不希望后端做太多图片处理。如果你的场景只是静态展示一个固定二维码图片，完全没必要用canvas，直接放图片地址就好。如果场景是大量二维码需要服务端生成并分发，后端批量处理可能更合适。
我在实际项目中最大的体会是，一定要把“base64导出”这个环节放在真机上尽早测试。开发者工具里canvas渲染一切正常，不代表iOS Safari、安卓WebView都正常。尤其是跨域图片、dpr取整、透明背景这三个点，都是真机才容易暴露的问题。
如果让我给后来者一个建议：先把二维码识别率当成第一优先级，不要为了好看牺牲对比度和容错。二维码生成和base64转换都是手段，用户扫码能不能一次成功、图片有没有真正保存到相册，才是通关标准。先跑通一个小案例，再逐步叠加背景、Logo和上传逻辑，最后再考虑性能优化，这套链路会走得非常稳。
