小程序 UnionID 与账号绑定教程｜多端统一用户与合并排错 – MPForge

一、UnionID 拿不到？先查绑定再改代码

结论先记住：UnionID 拿不到，八成是开放平台绑定没做或主体不一致，与业务代码无关。

UnionID 的机制并不复杂：同一个人在同主体的不同应用里 openid 各不相同，但在开放平台绑定关系下，各端都能换到一个相同的 unionid。所以排查永远从绑定关系开始：

• 查绑定：小程序与公众号是否挂在同一个开放平台账号下，绑定关系生效有时差，刚绑完就测会误判。
• 查主体：各端主体必须一致，跨主体的账号无法靠 unionid 统一，多主体口径参考 小程序多端同主体说明。
• 查链路：小程序侧要先用 code 换 session，公众号侧要走网页授权，链路写错拿到的仍是 openid，会话细节看 小程序登录会话管理。
• 查字段：老接口返回结构有差异，别只盯 unionid 字段名，先确认接口版本与返回体。

给商家的判断口径：让技术把绑定关系页截图发你，一图看清小程序、公众号、App 挂在哪个开放平台账号下，比在群里来回描述快得多。

二、开工前备齐四样材料

账号合并是高风险动作，四样材料缺一样都会停在半路。

• 账号关系图：画出各端应用与开放平台的绑定关系、各自用哪个 AppID，这是所有后续讨论的底图。
• 各端 AppID 清单：正式、测试环境分开列，避免拿测试号的 openid 去对正式库。
• 登录日志（脱敏）：抽样看真实登录链路的返回，确认 unionid 是否稳定出现，日志必须脱敏。
• 历史 openid 迁移方案：老用户的账号数据怎么并入新体系，单独立项排期，别混在功能迭代里顺手做。

三、落地步骤：从换票到灰度验证

顺序不能乱：绑定先核对、换票链路先跑通、合并策略后设计、灰度验证收尾。按这五步走：

1. 核对绑定与主体：截图存档绑定关系，确认各端同主体；缺开放平台账号就先补注册绑定，没有绑定谈不上统一。
2. 梳理登录换票流程：各端统一「code 换 session、session 换 unionid」的路径，Secret 只存服务端，前端出现 Secret 属于高危。
3. 设计账号合并策略：以 unionid 或手机号为锚点建映射表，合并动作对用户可见，保留 小程序手机号快速验证组件 做辅助核验。
4. 灰度验证：先放 5% 流量跑新链路，对比新旧账号数据，异常率达标再全量，节奏参考 小程序灰度发布与回滚。
5. 文档化异常工单：串号、重复会员、换绑纠纷各建一个处理模板，客服照单办事，不靠临场发挥。

四、账号合并与历史用户迁移

结论：合并必须可回滚、可申诉——静默合并是串号事故的根源。

• 建映射不删数据：新旧行为用映射表关联，原 openid 数据保留原样，出问题能立即切回。
• 主键怎么选：手机号当业务主键可行，但必须处理换绑场景；unionid 当锚点更稳，两者配合用。
• 迁移单独立项：历史 openid 迁移要单独排期、单独验收，严禁在线上边跑边赌。
• 人工解绑入口：客服后台必须有解绑与合并申诉功能，自动化合并出错时要能在 10 分钟内人工纠正。

五、审核驳回与线上翻车点

结论：这类问题的翻车点不在审核，而在上线后的串号与数据错乱，三条红线别碰。

• 前端存 Secret：AppSecret 出现在小程序代码或请求里等于泄露，任何人都能拿它换用户数据，发现即紧急重置。
• 静默合并账号：后台悄悄把两个账号并成一个，用户看到别人的订单记录，这是最严重的信任事故。
• 无人工解绑流程：合并出事后只能改数据库，恢复慢且二次伤害大；入口和流程要提前建好。

涉及支付与会员资产的合并更要保守：先冻结争议数据再合并，订单、余额、积分逐项核对，验收口径并入 小程序上线发布检查清单。

六、避坑清单

这三条坑都和「身份」有关：认准锚点、管住密钥、给用户留退路。

• 别拿 openid 当唯一标识：openid 只在单端唯一，跨端对比必然出重复账号，统一层用 unionid。
• 别把 Secret 下发给前端团队：换票只在服务端完成，前端只持有 session 凭证，泄露风险直接归零。
• 别跳过灰度直接全量：账号体系改动波及登录、订单、会员三层，灰度期至少覆盖一个完整活动周期。

七、常见问题 FAQ