更新记录

1.0.0（2026-07-06）

• 新增 X OAuth2 Authorization Code Flow with PKCE 授权 URL 生成。
• 新增本地缓存 state / codeVerifier 与回调校验工具。
• 新增 deep link 回调文本解析工具。
• 新增 Android / iOS 打开授权 URL 的工具方法。
• 新增 demo 页面、H5 回调页模板和流程文档。

平台兼容性

uni-app(4.76)

uni-app x(4.76)

x-login

x-login 是一个 uni-app x UTS 工具插件，用于接入 X OAuth2 Authorization Code Flow with PKCE。

插件负责：

• 生成 X 授权 URL
• 生成并本地缓存 state 与 codeVerifier
• 打开授权 URL
• 解析 HTTPS 回调页唤回 App 后携带的 code/state/error

插件不负责：

• 向 X token endpoint 换取 access token
• 请求你的业务后端
• 保存业务登录态

平台支持

安装

将插件目录放入项目：

uni_modules/x-login

X 后台配置

1. 在 X Developer Portal 创建或选择 App。
2. 开启 OAuth 2.0。
3. 获取 Client ID。
4. 配置 HTTPS Callback / Redirect URI，例如：

https://your-domain.com/x-oauth-callback.html

5. 把插件里的 static/h5/x-oauth-callback.html 部署到该 HTTPS 地址。
6. 在回调页中替换 APP_SCHEME、Android 包名等参数。

App scheme 配置

宿主 App 需要配置自定义 scheme，例如 myapp：

{
  "app-android": {
    "distribute": {
      "schemes": "myapp",
      "urlschemes": ["myapp"]
    }
  },
  "app-ios": {
    "distribute": {
      "urlschemes": ["myapp"]
    }
  }
}

回调页会把 X 的 HTTPS 回调转换为：

myapp://oauth-callback?code=...&state=...&oauth_source=x

调用示例

import { getXLogin, openXLoginUrl } from '@/uni_modules/x-login'

const x = getXLogin()
const auth = x.createAuthorizeUrl({
  clientId: '你的 X OAuth2 Client ID',
  redirectUri: 'https://your-domain.com/x-oauth-callback.html',
  scopes: ['tweet.read', 'users.read', 'offline.access'],
  codeChallengeMethod: 'plain'
})

openXLoginUrl(auth.authorizeUrl)

App 被 scheme 唤醒后，从 onLaunch / onShow 的参数或 Android intent data 中取得原始文本，再调用：

const payload = getXLogin().extractCallbackFromText(text)
if (payload != null && payload.error == null) {
  if (getXLogin().verifyState(payload.state ?? '')) {
    const codeVerifier = getXLogin().getPendingCodeVerifier()
    // 把 payload.code 和 codeVerifier 提交给业务服务端换取登录态。
  }
}

API

createAuthorizeUrl(options)

生成授权 URL，并保存本次 state 与 codeVerifier。

parseCallbackUrl(url)

解析标准 URL 中的 code、state、error。

extractCallbackFromText(text)

从 App 启动参数、Android intent data 或 JSON 文本中提取 X 回调参数。

verifyState(state)

校验回调 state 是否等于本地缓存 state。

getPendingCodeVerifier()

读取本次授权保存的 codeVerifier，用于服务端换 token。