unionid 是微信生态中实现 跨应用用户身份统一识别 的核心机制，是打通 公众号、小程序、企业微信 等多个应用的关键桥梁。

---

一、unionid 知识体系

1. 核心定位

• 微信为同一用户在 同一开放平台账号下 的全局唯一标识
• 解决：同一个用户在不同公众号/小程序中 openid 不同的问题
• 是实现 用户数据打通、统一画像、私域运营 的基础

---

2. 知识体系组成

模块	说明
用户标识体系	openid、unionid、session_key 的区别与关系
获取条件	必须绑定到同一个“微信开放平台”账号
适用场景	公众号 + 小程序用户打通、企业微信客户管理
获取方式	网页授权登录、小程序登录、企业微信授权
数据结构	字符串（如 o1234567890abcdef）
安全性	不可逆、不暴露用户隐私
与 openid 的关系	一个 unionid 对应多个 openid
开放平台绑定	多个公众号/小程序/企业微信绑定到同一开放平台
API 支持	网页授权、小程序登录、企业微信回调
典型应用	统一会员系统、积分打通、跨平台消息推送
限制与坑点	未绑定开放平台则无 unionid
调试与验证	使用微信开发者工具、打印日志

---

二、unionid 的底层原理

1. 为什么需要 unionid？

微信生态中：

• 同一个用户关注了你的服务号 A 和小程序 B
• 在服务号 A 中：openid = oA123
• 在小程序 B 中：openid = oB456
• ❌ 无法识别是同一个用户

unionid 就是为了解决这个问题而生的：让开发者知道“这是同一个人”

---

2. unionid 的生成逻辑

• unionid 由微信服务器在用户首次授权时生成
• 只要应用属于同一个开放平台账号，同一用户的 unionid 相同
• openid 仍然保持应用独立

---

3. 获取 unionid 的前提条件

✅ 必须满足以下任一条件：

条件	说明
所有应用绑定到同一个微信开放平台	最常见方式（推荐）
企业微信与微信互通	企业微信客户添加后可获取 unionid
使用开放平台的第三方平台授权	代开发场景

❌ 如果没有绑定开放平台，即使同一个用户，也无法获取 unionid

---

4. 获取 unionid 的方式

（1）公众号网页授权登录（OAuth2.0）

GET https://open.weixin.qq.com/connect/oauth2/authorize?
  appid=wx123456&
  redirect_uri=https%3A%2F%2Fexample.com%2Fcallback&
  response_type=code&
  scope=snsapi_userinfo&
  state=123#wechat_redirect

回调后获取 access_token 和 openid，再调用：

GET https://api.weixin.qq.com/sns/userinfo?access_token=ACCESS_TOKEN&openid=OPENID&lang=zh_CN

返回：

{
  "openid": "o123456",
  "nickname": "张三",
  "headimgurl": "...",
  "unionid": "u1234567890"
}

⚠️ 必须使用 snsapi_userinfo 授权，snsapi_base 不返回 unionid

---

（2）小程序登录

// 小程序前端
wx.login({
  success(res) {
    const code = res.code;
    // 发送到后端
    wx.request({
      url: 'https://yourserver.com/wx/login',
      data: { code }
    });
  }
});

后端调用：

POST https://api.weixin.qq.com/sns/jscode2session?
  appid=APPID&
  secret=SECRET&
  js_code=JSCODE&
  grant_type=authorization_code

返回：

{
  "openid": "oABC123",
  "session_key": "xxx",
  "unionid": "u1234567890"
}

✅ 只要小程序绑定开放平台，就会返回 unionid

---

（3）企业微信客户添加

当企业微信员工添加微信好友时，可通过回调获取：

{
  "ChangeType": "add_external_contact",
  "UserID": "zhangsan",
  "ExternalUserID": "wm123456",
  "UnionID": "u1234567890"
}

---

5. unionid vs openid 对比

对比项	openid	unionid
唯一性	用户在单个应用中的唯一标识	用户在同一开放平台下的全局唯一标识
是否跨应用	❌ 不同应用不同	✅ 相同
获取条件	关注/授权即可	必须绑定开放平台
是否敏感	中等	高（可用于用户打通）
是否可变	否	否
典型用途	发送模板消息、记录行为	用户画像、积分打通、统一登录

---

6. 典型应用场景

✅ 场景一：公众号 + 小程序用户打通

• 用户在公众号关注后，跳转小程序下单
• 通过 unionid 识别是同一人，自动登录，继承会员等级

✅ 场景二：企业微信 SCRM

• 客户通过公众号添加企微员工
• 通过 unionid 关联历史订单、服务记录

✅ 场景三：多小程序统一会员

• 集团有多个小程序（商城、服务、社区）
• 使用 unionid 实现积分、优惠券、收藏打通

✅ 场景四：数据中台用户合并

• 将不同来源的用户行为数据按 unionid 聚合
• 构建完整用户画像

---

7. 常见问题与坑点

问题	原因	解决方案
获取不到 unionid	应用未绑定开放平台	登录开放平台绑定
unionid 不一致	不同开放平台	统一到一个开放平台
小程序登录无 unionid	未绑定开放平台	在小程序后台绑定
企业微信无 unionid	未开启客户联系	开通“客户联系”权限
unionid 泄露风险	被用于用户追踪	不对外暴露，不用于 URL 传参

---

三、最佳实践

实践	说明
✅ 绑定开放平台	所有公众号、小程序统一绑定
✅ 使用 unionid 作为用户主键	在数据库中建立 unionid 字段
✅ 避免依赖 openid 做唯一识别	会误判为不同用户
✅ 记录 openid 映射表	unionid → 多个 openid
✅ 安全存储	unionid 视为敏感信息，不日志打印
✅ 统一登录服务	基于 unionid 实现单点登录
✅ 监控打通率	统计多少用户成功获取 unionid

---

四、总结

知识体系全景

unionid
├── 核心：跨应用用户唯一标识
├── 前提：绑定微信开放平台
├── 获取方式：
│   ├── 公众号网页授权（snsapi_userinfo）
│   ├── 小程序登录（jscode2session）
│   └── 企业微信客户添加
├── 与 openid 关系：1 vs N
├── 应用场景：
│   ├── 公众号 + 小程序打通
│   ├── 企业微信 SCRM
│   ├── 多小程序统一会员
│   └── 用户画像构建
├── 安全性：敏感信息，需保护
├── 常见问题：获取不到、不一致
└── 最佳实践：绑定开放平台 + 统一用户主键

底层原理核心

unionid 是微信在“同一开放平台账号”下为同一用户生成的全局唯一标识，其底层原理是“以开放平台为信任锚点，将用户在不同应用中的 openid 映射到同一个 unionid”。它通过 OAuth2.0 授权、小程序登录、企业微信回调等机制分发，是实现跨应用用户身份统一识别的基石，支撑了微信生态中的私域运营、会员打通、数据中台等高级能力。

---

掌握 unionid 的知识体系，你就能真正实现微信生态内的 用户身份统一，构建完整的私域流量闭环，是企业级微信开发的核心能力。