更新记录

1.0.0（2026-08-10） 下载此版本

无

平台兼容性

uni-app(3.8.1)

uni-social-login

uni-app 海外社交账号一键登录插件：支持 Facebook / Instagram / X(Twitter)，覆盖 App(iOS/Android) 与 H5 双端，基于标准 OAuth2 授权码流程 + PKCE，无需原生 SDK 打包。

当前状态：核心引擎 + 三渠道 + 可运行 demo 已完成，已按 uni-app 官方 uni_modules 规范组织（可直接上架插件市场），Node 单测 16/16 通过。 用 HBuilderX 打开 demo/ 目录即可运行（默认 debug 模式无需任何凭证）。 后续与你联调真实凭证、真机验证 scheme 回传、打磨 UI 与错误提示。

特性

• 🔑 标准 OAuth2 授权码 + PKCE，公开客户端无需 client_secret，更适合前端/H5 场景
• 📱 App 端用系统浏览器授权 + 自定义 URL Scheme 回传 code（无需自建中转服务）
• 🌐 H5 端标准页面重定向，回调地址可直接填站点根路径，跳回后自动收口（无需回调页、无需服务端重写）
• 🧩 渠道可插拔：新增一个 provider 文件即可扩展（如 Google / Apple / Line）
• 🧪 内置 debug mock 模式，无凭证也能跑通完整 UI 流程
• 📦 归一化返回：无论哪个渠道，统一返回 { provider, openid, nickname, username, email, avatar, accessToken, ... }

目录结构

uniapp-plugin/
├─ demo/                              # 可运行演示工程 —— HBuilderX 打开这一层
│  ├─ manifest.json                   # 已配置 App scheme
│  ├─ App.vue                         # onLaunch：注册 scheme 监听 + H5 回调自动收口
│  ├─ pages/index/index.vue           # 登录演示页
│  ├─ pages/callback/callback.vue     # 可选的独立 H5 回调页（history 路由时用）
│  └─ uni_modules/
│     └─ uni-social-login/            # ★ 插件本体，整个目录即为上架发布物
│        ├─ package.json              # uni_modules 描述（id / 版本 / 平台支持 / 售价）
│        ├─ readme.md / changelog.md  # 插件市场展示用
│        ├─ index.js                  # 入口：configure / login / handleCallback / ...
│        ├─ config.js                 # 配置：debug、scheme、各渠道 appId / redirectUri / scopes
│        ├─ core/
│        │  ├─ engine.js              # 登录编排（构建URL→授权→等回调→换令牌→取资料）
│        │  ├─ oauth.js               # 授权URL构建、回调解析、PKCE 生成
│        │  ├─ http.js                # 统一请求封装（uni.request / fetch / 可注入 mock）
│        │  ├─ platform.js            # 运行平台检测（app / h5 / node）
│        │  ├─ debug.js               # mock 登录
│        │  └─ app-scheme.js          # App 端 scheme 回调监听
│        ├─ providers/
│        │  ├─ facebook.js
│        │  ├─ twitter.js             # X(Twitter)
│        │  ├─ instagram.js           # 经 Facebook Graph 实现
│        │  └─ index.js
│        └─ utils/crypto.js           # PKCE / 随机数（Web Crypto，零依赖）
└─ tests/core.test.mjs                # Node 单测（无需浏览器 / HBuilderX）

插件放在 demo/uni_modules/ 下，是 uni-app 插件工程的标准做法：demo 工程直接引用， 上架时把 uni-social-login 这个目录打包上传即可，使用者下载后会自动落到他项目的同名位置。

快速开始

跑 demo： 用 HBuilderX 打开 demo/ 目录 → 运行到浏览器 / 运行到手机。默认 debug: true，三个按钮点下去会返回 mock 用户，不需要任何凭证。

接入自己的项目：

1. 把 demo/uni_modules/uni-social-login/ 整个目录复制到你项目的 uni_modules/ 下。
2. 在 App.vue 的 onLaunch 中初始化：

   import SocialLogin from '@/uni_modules/uni-social-login/index.js'
   export default {
    onLaunch() {
      SocialLogin.registerSchemeHandler()   // App：监听 scheme 回传
      SocialLogin.autoHandleH5Callback()    // H5：授权跳回时自动完成登录
        .then((res) => res && console.log('登录成功', res))
    }
   }

3. 调用登录：

   import SocialLogin from '@/uni_modules/uni-social-login/index.js'
   const user = await SocialLogin.login('facebook')
   console.log(user) // { provider, openid, nickname, email, avatar, accessToken, ... }

   H5 端 login() 会直接跳走，返回 { redirected: true }；真正的用户对象由 autoHandleH5Callback() 在跳回来之后产出，demo 里通过 uni.$emit 传给页面。

4. 填凭证：编辑 uni_modules/uni-social-login/config.js，把 debug 改为 false。

配置说明（config.js）

redirectUri 推荐：

• App：uniappsociallogin://oauth/callback（与你配置的 scheme 对应）
• H5：直接填站点根地址 https://你的域名/（结尾带斜杠），并在开发者后台登记同样的地址

⚠️ H5 回调地址是最容易踩坑的一步。Facebook / X 后台都不允许 redirect_uri 带 # 片段， 而 uni-app H5 默认 hash 路由，独立回调页的真实地址是 https://xxx/#/pages/callback/callback， 根本没法登记。填根地址后，平台会带着 ?code=&state= 跳回首页， autoHandleH5Callback() 会自动识别并完成换令牌，无需回调页、也不用配服务端 history 重写。

各平台接入步骤

Facebook

1. 打开 https://developers.facebook.com ，创建应用（类型选「消费者」）。
2. 添加 Facebook Login 产品，在「设置 > 有效 OAuth 重定向 URI」填入你的 redirectUri。
3. 记下 App ID（填到 config.providers.facebook.appId）。
4. 隐私政策 URL、应用图标等按审核要求补齐。

X (Twitter)

1. 打开 https://developer.x.com ，创建 Project & App。
2. 在 App 的 User authentication settings 启用 OAuth2，类型选 Public client（PKCE）。
3. 回调地址填你的 redirectUri；勾选所需 scopes（tweet.read / users.read / offline.access）。
4. 记下 Client ID（填到 config.providers.twitter.appId）。

Instagram（重要）

Meta 已停用 Instagram Basic Display API。当前可用的方式是 Facebook Login + Instagram 权限：

1. 复用同一个 Facebook App，在 Facebook Login 的 scope 中申请 instagram_basic / instagram_content_publish 等。
2. 目标 Instagram 账号需为 Business / Creator，并已关联到某个 Facebook 主页。
3. 插件会先用 Facebook 令牌取 FB 身份，再经 Graph API 解析关联的 IG 业务账号。
4. 若账号未关联 IG 业务账号，会优雅降级（返回 FB 身份并标记 instagramLinked:false）。

App 端 scheme 配置（manifest.json）

app-plus 中需配置与 config.scheme 一致的 scheme：

"app-plus": {
  "scheme": "uniappsociallogin",
  "distribute": {
    "android": { "scheme": "uniappsociallogin" },
    "ios": { "urltypes": [{ "urlidentifier": "com.demo.unisociallogin", "urlschemes": ["uniappsociallogin"] }] }
  }
}

（demo 工程已写好，直接参考。）

H5 端回调的两种接法

方式 A（推荐，零配置）：redirectUri.h5 填站点根地址，App.vue 里调用 autoHandleH5Callback()。 跳回来时它会从地址栏取出 code/state，换令牌、取资料，并把 URL 上的敏感参数抹掉（防止刷新重复消费 code）。

方式 B（history 路由 + 服务端重写）：redirectUri.h5 指向独立回调页 https://你的域名/pages/callback/callback，在该页面手动收口：

// pages/callback/callback.vue
async onLoad(query) {
  const res = await SocialLogin.handleCallback(query) // query 含 code & state
  // res 即归一化用户对象
}

（demo 已包含该页面；需把 manifest 的 h5.router.mode 改为 history，并让服务器把未知路径回落到 index.html。）

跨页面重定向导致的上下文丢失，插件内部已用 sessionStorage 兜住（存 verifier / redirectUri / providerKey），处理完自动清理。

运行测试（无需浏览器）

node tests/core.test.mjs
# 或 npm test

使用 mock HTTP client 验证 16 项：授权 URL 构建、回调解析、PKCE、三渠道完整登录与归一化、 各平台鉴权风格差异（Graph 用 query token / X 用 Bearer 头）、H5 sessionStorage 恢复与清理、 GET 请求参数并入 query、错误响应的可读提示。

API

SocialLogin.configure({ debug, scheme, providers })   // 覆盖配置（可用于服务端下发 appId）
SocialLogin.login(providerKey, opts?)                 // 发起登录，返回归一化用户
SocialLogin.handleCallback(url | query)               // 处理授权回调（App scheme / H5 回调页）
SocialLogin.autoHandleH5Callback()                    // H5：自动从地址栏收口，无回调参数时返回 null
SocialLogin.registerSchemeHandler()                   // App 端注册 scheme 监听（onLaunch 调用一次）
SocialLogin.setHttpClient(fn)                         // 注入自定义/mock 请求实现
SocialLogin.getProvider(key)                          // 取渠道定义（扩展渠道时有用）

归一化返回结构：

{
  provider: 'facebook' | 'twitter' | 'instagram',
  openid: string,
  nickname: string,
  username?: string,   // @handle（不含 @），X / Instagram 有
  email: string,
  avatar: string,
  accessToken: string,
  expiresIn?: number,
  refreshToken?: string,
  instagramLinked?: boolean,  // Instagram 专属：是否成功解析到 IG 业务账号
  raw: any                  // 渠道原始返回，方便按需取额外字段
}

已知限制 / 后续优化点（待与你联调）

• [ ] App 端真实打包后需在真机验证 scheme 回传（逻辑已实现，待你用真实 AppID 联调）
• [x] H5 回调地址带 # 无法登记的问题 —— 已用 autoHandleH5Callback() 解决
• [ ] Instagram 依赖 Business/Creator 账号，普通个人号无法取到 IG 资料
• [ ] H5 真实模式当前在前端直接换令牌（PKCE 公开客户端）；若需更高安全可加中转服务端
• [ ] 可扩展 Google / Apple / Line 等渠道（新增 provider 文件即可）
• [ ] 令牌持久化（登录态保持）、刷新令牌、登出等增值能力
• [ ] 错误提示与多语言、UI 组件化（可做成可拖拽的登录按钮组件）

作为付费插件发布

发布物就是 demo/uni_modules/uni-social-login/ 这一个目录，已按 uni_modules 规范准备好 package.json / readme.md / changelog.md。上架前记得改这几处：

上架说明建议突出：三渠道、App+H5 双端、PKCE 无需 secret、零依赖不增包体、debug 模式可先试用、 以及各平台开发者后台的配置要点（这部分是买家最容易卡住、也最值钱的内容）。