微信小游戏登录教程

通过微信小游戏对应的服务端接口完成登录（含 access_token 与 jscode2session 流程）。

1. 获取 access_token

用于调用微信相关服务端能力（服务端带 Redis 缓存）。

• GET /api/minigame/weixin/access_token

请求示例

curl "http://localhost:2567/api/minigame/weixin/access_token"

响应示例

{
  "success": true,
  "message": "操作成功！",
  "data": {
    "access_token": "ACCESS_TOKEN",
    "expires_in": 7200
  }
}

2. 微信登录（jscode2session）

前置条件

• 客户端已调用 wx.login() 拿到 code

请求

• GET /api/minigame/weixin/login

Query 参数：

• jsCode：wx.login() 返回的 code

请求示例

curl "http://localhost:2567/api/minigame/weixin/login?jsCode=WX_LOGIN_CODE"

服务端行为概要

1. 向微信 jscode2session 换取 openid、session_key、可选 unionid。
2. 以 openid（无 openid 时回退 unionid）为键 查找或创建 本地 users 表记录（AuthService.findOrCreateMinigameUser）；新建用户会生成占位 username / email 与随机密码（仅服务端存储，不会在接口中返回）。
3. 签发 JWT 访问令牌 token，payload 中的 userId 为数据库用户主键（UUID），username / email 等为库中字段；刷新令牌与访问令牌会写入 Redis（键为 refresh_token:{userId}、access_token:{userId}，此处 userId 同上）。

响应示例

{
  "success": true,
  "message": "操作成功！",
  "data": {
    "openid": "OPEN_ID",
    "session_key": "SESSION_KEY",
    "unionid": "UNION_ID",
    "errcode": 0,
    "errmsg": "",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "username": "mg_weixin_xxxxxxxx",
      "email": "weixin_xxxxxxxx@minigame.local",
      "nickname": null,
      "avatar": null,
      "openid": "OPEN_ID",
      "guildId": null,
      "status": 1,
      "createdAt": "2026-05-02T12:00:00.000Z",
      "updatedAt": "2026-05-02T12:00:00.000Z",
      "version": 1
    }
  }
}

字段说明（data）

字段	说明
openid / unionid	微信平台标识；成功时至少有 openid（视微信返回而定）。
session_key	微信会话密钥，敏感；仅应在服务端用于解密等能力，不建议依赖前端长期保存。
errcode / errmsg	与微信返回一致；成功时 errcode 常为 0 或省略。
token	本项目 JWT 访问令牌，进入带鉴权房间或调用受保护 HTTP 接口时使用。
user	本地用户资料，查询时 不包含 password 字段（并非「删除后返回」，而是查询列中未选取密码）。

若未能解析出有效用户标识（无 openid/unionid），则 token 与 user 可能为空，需以错误处理分支为准。

3. 后续（接入房间 / HTTP 鉴权）

• 使用响应中的 token（或部分客户端约定的 accessToken）作为 Colyseus joinOrCreate 的 options，以及 HTTP Authorization: Bearer <token>。
• 业务侧展示头像、昵称等，可读写 user 对应库记录；JWT 内 userId 为库主键，若旧逻辑曾把 userId 当作 openid，需改为使用 user.id 或解析 JWT 中的 userId。

4. 安全提示

• session_key 泄露可能导致会话数据被恶意解密，生产环境请评估是否对客户端暴露或改为仅服务端使用。