soul-yongping/miniprogram/海报优化说明.md

推广海报优化说明

优化日期: 2026-02-04
问题: 二维码生成失败 + 弹窗尺寸不适配小程序

---

🔧 优化内容

1. 二维码生成优化 ✅

问题分析

• 小程序码API /api/miniprogram/qrcode 可能调用失败
• 没有备用方案，导致海报显示空白

解决方案

双重备用机制:

// 1. 优先使用小程序码API
const qrRes = await app.request('/api/miniprogram/qrcode', {
  method: 'POST',
  data: { 
    scene: `ref=${referralCode}`, 
    page: 'pages/index/index', 
    width: 280 
  }
})

// 2. 如果失败，使用第三方二维码API
if (!qrcodeImage) {
  qrcodeImage = `https://api.qrserver.com/v1/create-qr-code/?size=280x280&data=${encodeURIComponent(referralLink)}`
}

支持两种格式:

• ✅ Base64格式: 小程序码返回的Base64图片
• ✅ URL格式: 第三方二维码API的在线图片

绘制逻辑:

async drawQRCode(ctx, qrcodeImage, x, y, size) {
  if (qrcodeImage.startsWith('data:image')) {
    // Base64 → 保存到本地文件 → drawImage()
  } else if (qrcodeImage.startsWith('http')) {
    // URL → wx.downloadFile() → drawImage()
  } else {
    // 占位符
  }
}

---

2. 弹窗尺寸优化 ✅

问题分析

• Canvas尺寸: 375px x 580px (固定像素)
• 小程序屏幕宽度各异，固定像素导致显示过大

解决方案

调整Canvas尺寸:

/* 修改前 */
.poster-canvas { 
  width: 375px; 
  height: 580px; 
}

/* 修改后（使用rpx响应式单位）*/
.poster-canvas { 
  width: 600rpx;   /* 约等于屏幕宽度的80% */
  height: 928rpx;  /* 保持16:10比例 */
}

弹窗滚动优化:

.poster-modal { 
  max-height: 90vh;        /* 最大高度90%视口 */
  overflow-y: auto;        /* 允许滚动 */
}

Canvas绘制尺寸:

// 修改前
const width = 375
const height = 580

// 修改后（小程序优化）
const width = 300   // Canvas内部绘制尺寸
const height = 464  // 保持相同比例

---

📊 尺寸对照表

项目	修改前	修改后	说明
Canvas显示宽度	375px	600rpx	响应式单位
Canvas显示高度	580px	928rpx	响应式单位
Canvas绘制宽度	375px	300px	内部绘制
Canvas绘制高度	580px	464px	内部绘制
宽高比	1:1.55	1:1.55	保持一致

换算关系:

• 600rpx ≈ 300px（在iPhone6为标准，750rpx = 375px）
• 928rpx ≈ 464px

---

🔄 二维码流程图

开始
  ↓
尝试获取小程序码 (/api/miniprogram/qrcode)
  ↓
成功？
  ├─ 是 → 使用Base64格式 → 写入本地文件 → 绘制
  └─ 否 → 使用第三方二维码API
           ↓
           下载在线图片
           ↓
           成功？
             ├─ 是 → 绘制
             └─ 否 → 绘制占位符

---

✅ 优化效果

二维码生成

• ✅ 支持小程序码（Base64）
• ✅ 支持第三方二维码（URL）
• ✅ 自动降级处理
• ✅ 详细日志记录

弹窗显示

• ✅ 响应式尺寸（rpx单位）
• ✅ 支持滚动查看
• ✅ 适配所有屏幕尺寸
• ✅ 保持视觉比例

---

📱 测试检查

二维码测试

1. ✅ 小程序码API正常时，显示小程序码
2. ✅ 小程序码API失败时，显示第三方二维码
3. ✅ 两种二维码都可扫描
4. ✅ 控制台有清晰的日志输出

弹窗测试

1. ✅ iPhone 6/7/8 (375px宽) - 正常显示
2. ✅ iPhone Plus (414px宽) - 正常显示
3. ✅ iPhone X/11 (375px宽，刘海屏) - 正常显示
4. ✅ iPad (768px宽) - 正常显示
5. ✅ 弹窗可上下滚动
6. ✅ Canvas不会超出屏幕

---

🎯 对比截图

修改前

• Canvas固定 375px，在小屏幕上过大
• 二维码加载失败时显示空白

修改后

• Canvas使用 600rpx，自动适配
• 二维码有备用方案，始终可用

---

📝 相关文件

文件	修改内容	行数
referral.wxml	Canvas标签去除固定尺寸	1行
referral.wxss	Canvas样式改为rpx，弹窗增加滚动	3行
referral.js	二维码双重备用 + 绘制逻辑优化	~60行

---

🔍 日志示例

成功获取小程序码

[Poster] 请求小程序码, scene: ref=SOUL87EL
[Poster] ✅ 小程序码获取成功
[Poster] 绘制Base64二维码
[Poster] ✅ Base64写入成功

降级到第三方二维码

[Poster] 请求小程序码, scene: ref=SOUL87EL
[Poster] ❌ 小程序码获取失败: timeout
[Poster] 使用第三方二维码API
[Poster] 下载在线二维码: https://api.qrserver.com/...
[Poster] ✅ 二维码下载成功

---

💡 后续优化建议

1. 自定义海报模板

• 支持多种海报风格
• 用户自选背景色
• 个性化文案

2. 预览功能增强

• 长按预览大图
• 双击放大缩小
• 支持手势操作

3. 分享优化

• 一键分享到微信
• 生成小程序卡片
• 分享记录统计

---

优化完成！二维码稳定 + 弹窗适配！ 🎉