qrcode.js 无法直接设置背景色或背景图，因其仅生成透明底的纯图形内容；需通过外部容器、替代库（如 @xkeshi/qrcode）或合成工具（如 html2canvas）实现背景效果。
直接用 qrcode.js 生成的二维码本身不支持背景图或背景色——它只输出纯黑点+透明底的 SVG 或 Canvas，所有“带背景”的效果都得靠外部包裹、叠加或二次绘制实现。别指望改 qrcode 的 options 就能填满背景，那是无效操作。
为什么 qrcode.js 不能直接设 background-color 或 background-image
qrcode.js（如 davidshimjs/qrcodejs）底层是逐像素/逐 path 绘制模块，生成的是无容器的纯图形内容。它不创建外层 <div>，也不设置 style，更不会把自身当作一个可填充的画布区域。你给它父容器加 background-color 是有效的，但加 background-image 会因尺寸错位、缩放失真或定位点被遮盖而扫码失败。
常见错误现象包括：
- 二维码图片导出后背景消失（因为 canvas.toDataURL 只捕获绘制内容，不包含父级 CSS 背景）
- 本地
file://协议下 logo 加载失败，连带整个二维码渲染中断 - 用
html2canvas截图时，跨域背景图被拒绝绘制，留白或报错SecurityError: Failed to execute 'toDataURL' on 'HTMLCanvasElement'
用 @xkeshi/qrcode 添加 logo + 背景色 + 圆角模块（推荐方案）
这个库是目前最轻量、配置最直白的替代方案，npm 或 CDN 引入后，colorLight 参数就是背景色，image 参数可嵌 logo，dotsOptions.type 支持 'rounded' 等视觉优化。
立即学习“前端免费学习笔记（深入）”；
关键注意事项：
-
colorLight必须显式设置，否则默认为透明，背景色不会生效 -
image路径需同源或服务端开启 CORS，crossOrigin: 'anonymous'不可省略 -
margin建议 ≥ 12px，太小会压住三个定位角（L 形方块），大幅降低扫码容错率 - 若要导出高清 PNG，需在调用后手动用
canvas提取：该库内部用 Canvas 渲染，可通过qrcode._el.querySelector('canvas')拿到原生 canvas 元素
示例片段：
const qrcode = new QRCode(document.getElementById('qrcode'), {
text: 'https://example.com',
width: 300,
height: 300,
colorDark: '#1e40af',
colorLight: '#f9fafb', // ← 这才是真正的背景色
image: '/logo.png',
imageOptions: { crossOrigin: 'anonymous', margin: 12, width: 60, height: 60 },
dotsOptions: { type: 'rounded', color: '#1e40af' }
});
用 html2canvas 合成背景图 + 二维码 + 文案（适合海报场景）
当你需要把二维码、品牌背景图、标题、副文案全堆在一个长图里（比如分享海报），html2canvas 是实际落地最稳的方式。但它不是“美化二维码”，而是“合成一张图”。
必须处理的细节：
- 背景图必须用
<img>标签加载，不能用 CSSbackground-image（html2canvas不解析该样式） - 所有文字、二维码容器需用绝对定位或 flex 布局确保层级和位置固定，避免截图偏移
- 设备像素比（DPR）影响清晰度：务必传
scale: window.devicePixelRatio || 1，否则手机截图模糊 - 导出格式优先选
image/jpeg并设 quality=0.95，PNG 在某些安卓机上会因内存溢出失败
典型结构示意：
<div id="poster" style="position: relative; width: 375px; height: 600px;"> <img src="/bg.jpg" style="width: 100%; height: 100%; object-fit: cover;"> <div id="qrcode" style="position: absolute; top: 200px; left: 50%; transform: translateX(-50%);"></div> <p style="position: absolute; top: 400px; left: 0; width: 100%; text-align: center;">扫码领取优惠</p> </div>
纯 CSS “假装”有背景（仅限简单页面展示）
如果只是让网页上的二维码看起来有背景、圆角、阴影，又不想引入新库或截图逻辑，可以用 CSS 包裹“障眼法”：
- 给二维码容器加
padding: 24px和background: linear-gradient(...)，再套一层border-radius和overflow: hidden - 用伪元素
::before绝对定位盖在二维码下方，模拟背景色块或浅纹理 - 注意：这种方案无法导出含背景的图片，打印或截图仍只有二维码本体
- 慎用 box-shadow 模拟“发光”效果——过强阴影会导致扫码器误判边缘
一句话收尾：真正可靠的“带背景二维码”，从来不是靠改二维码库本身，而是靠分层控制——二维码负责编码正确性，容器负责视觉表达，合成工具负责最终交付。别在 qrcode.js 的 options 里死磕 background，那条路不通。
