更新记录

1.0.2（2025-10-22）

修复已知问题

1.0.1（2025-09-26）

支持Harmony平台

1.0.0（2025-09-23）

支持Android & iOS 支付宝极简版SDK所有功能

平台兼容性

uni-app(4.36)

uni-app x(4.36)

tt-alipay-lite

🚀 轻量级支付宝SDK插件，为 uni-app x & uni-app 提供支付宝授权登录解决方案

📱 支持平台：uni-app x (TypeScript) 和 uni-app (JavaScript)

📖 目录

• SDK版本信息
• 环境配置
• 快速开始
• 功能介绍
  • 支付宝授权登录
• 错误处理
• 常见问题

功能支持矩阵

📚 推荐阅读:

• 支付宝登录使用说明
• 极简版授权请求参数和返回

🚨 重要提示

⚠️ 必须使用自定义基座运行，否则无法找到插件方法

🚫 支付功能限制：本插件为轻量级版本，不支持支付宝支付功能。如需支付功能，请使用 tt-alipay-pro 插件，避免打包冲突。

环境配置

前置条件

1. 在支付宝开放平台申请移动应用
2. 获取 AppID
3. 配置应用包名和签名

Android平台配置

配置插件AndroidManifest.xml

直接修改插件根目录的 uni_modules/tt-alipay-lite/utssdk/app-android/AndroidManifest.xml 文件：

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android" xmlns:tools="http://schemas.android.com/tools"
    package="uts.sdk.modules.ttAlipayLite">

    <application>
        <activity android:name="uts.sdk.modules.ttAlipayLite.AlipayResultActivity" android:exported="true" tools:node="merge">
            <intent-filter tools:node="replace">
                <action android:name="android.intent.action.VIEW"/>
                <category android:name="android.intent.category.DEFAULT"/>
                <category android:name="android.intent.category.BROWSABLE"/>
                <!-- 这里的 __alipaysdkdemo__ 需要替换成您的App特有的Scheme -->
                <!-- 建议设置为 ali + appid的md5值，确保唯一性 -->
                <data android:scheme="tt-alipay-demo"/>
            </intent-filter>
        </activity>
    </application>
</manifest>

重要说明：

• 将 tt-alipay-demo 替换为您的实际scheme
• 建议使用 ali + appid的md5值 作为scheme，确保唯一性
• scheme必须与代码中使用的完全一致
• 确保在支付宝开放平台配置中保持一致

HarmonyOS平台配置

配置项目module.json5

在项目根目录的 harmony-configs/entry/src/main/module.json5 文件中添加支付宝相关配置：

{
  "module": {
    "name": "entry",
    "type": "entry",
    "description": "$string:module_desc",
    "mainElement": "EntryAbility",
    "deviceTypes": [
      "phone",
      "tablet",
      "2in1"
    ],
    "deliveryWithInstall": true,
    "installationFree": false,
    "pages": "$profile:main_pages",
    "querySchemes": [
      "apmqpdispatch"  // 支付宝回调scheme，必须添加
    ],
    "abilities": [
      {
        "name": "EntryAbility",
        "srcEntry": "./ets/entryability/EntryAbility.ets",
        "description": "$string:EntryAbility_desc",
        "icon": "$media:layered_image",
        "label": "$string:EntryAbility_label",
        "startWindowIcon": "$media:startIcon",
        "startWindowBackground": "$color:start_window_background",
        "exported": true,
        "skills": [
          {
            "entities": [
              "entity.system.home"
            ],
            "actions": [
              "action.system.home"
            ]
          }
        ]
      }
    ],
    "requestPermissions": [
      {
        "name": "ohos.permission.INTERNET"
      }
    ]
  }
}

重要说明：

• 必须在 querySchemes 中添加 "apmqpdispatch"，这是支付宝回调的必要配置
• 确保网络权限已正确配置
• 支付宝授权通过系统服务调用，需要正确的scheme配置
• HarmonyOS平台仅支持授权登录功能，不支持电子发票和代扣业务

iOS平台配置

配置插件Info.plist

直接修改插件根目录的 uni_modules/tt-alipay-lite/utssdk/app-ios/Info.plist 文件：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>CFBundleURLTypes</key>
    <array>
      <dict>
        <key>CFBundleTypeRole</key>
        <string>Editor</string>
        <key>CFBundleURLName</key>
        <string>alipay</string>
        <key>CFBundleURLSchemes</key>
        <array>
           <!-- 建议设置为 ali + appid的md5值，确保唯一性 -->
          <string>tt-alipay-demo</string>
        </array>
      </dict>
    </array>
  </dict>
</plist>

重要说明：

• 将 tt-alipay-demo 替换为您的实际scheme
• 建议使用 ali + appid的md5值 作为scheme，确保唯一性
• scheme必须与代码中使用的完全一致
• 确保在支付宝开放平台配置中保持一致

快速开始

1. 导入插件

uni-app x 平台

import * as alipay from "@/uni_modules/tt-alipay-lite";

export default {
    data() {
        return {
            alipay: null as alipay.TTAliOpenSDK | null,
        }
    },
    onLoad() {
        // 初始化支付宝SDK实例
        this.alipay = alipay.getTTAliOpenSDK()
    }
}

uni-app 平台

// 在页面中引入插件
import * as alipay from "@/uni_modules/tt-alipay-lite";

export default {
    data() {
        return {
            alipay: null
        }
    },
    onLoad() {
        // 初始化支付宝SDK实例
        this.alipay = alipay.getTTAliOpenSDK()
    }
}

功能介绍

支付宝授权登录

💡 支付宝登录是一个两步过程：先获取authCode，再通过后端接口换取用户信息

第一步：获取授权码 (authCode)

参数说明

TTAliLoginOptions

URL 参数说明（极简版 SDK 接入 authcenter）

⚠️ 重要提示：使用极简版 SDK 时，必须在授权 URL 中将 auth_type 设置为 PURE_OAUTH_SDK，授权会根据该参数确定回调类型。

当 params 传入极简版授权链接 https://authweb.alipay.com/auth 时，应包含以下核心参数：

极简版 SDK 授权 URL 示例：

https://authweb.alipay.com/auth?auth_type=PURE_OAUTH_SDK&app_id=2016051801417322&scope=auth_user&state=XXXXXXX

说明：

• auth_type：指定为 PURE_OAUTH_SDK
• app_id：支付宝开放平台应用 ID
• scope：授权范围，取值为 auth_base 或 auth_user
• state：商家自定义参数，建议使用 base64 编码的随机字符串
• 其它参数：均不需要，由于不过 OpenAPI，所以也无需签名流程

详细字段含义及更多可选参数见：极简版授权请求参数和返回

唤起说明

使用极简版 SDK 时，服务端拼接好的跳转 URL 示例如下：

https://authweb.alipay.com/auth?auth_type=PURE_OAUTH_SDK&app_id=2016051801417322&scope=auth_user&state=XXXXXXX

在导入极简版 SDK 后，将此 URL 作为 params 参数传入 login 方法即可完成授权调用。

返回值 TTAliLoginSuccess

示例代码

uni-app x 平台

// 支付宝授权登录
handleAlipayLogin() {
    // 构建极简版授权URL（必须包含 auth_type=PURE_OAUTH_SDK）
    const appId = 'YOUR_APP_ID'; // 替换为您的应用ID
    const state = btoa(Date.now().toString()); // 生成base64编码的state参数

    const authUrl = `https://authweb.alipay.com/auth?auth_type=PURE_OAUTH_SDK&app_id=${appId}&scope=auth_user&state=${state}`;

    this.alipay?.login({
        scheme: 'tt-alipay-demo', // 应用回调scheme
        params: authUrl, // 授权URL（已编码）
        serviceType: 1, // 三方授权
        success: (result) => {
            console.log("✅ 获取授权码成功:", result.authCode);
            console.log("✅ 状态参数:", result.state);
            // 将authCode发送到后端服务器
            this.sendAuthCodeToServer(result.authCode, result.state)
        },
        fail: (error) => {
            console.error("❌ 支付宝授权失败:", error);
            this.handleAlipayError(error, '支付宝登录');
        },
        complete: (result) => {
            console.log("📱 授权流程完成:", result);
        }
    } as alipay.TTAliLoginOptions)
}

uni-app 平台

// 支付宝授权登录
handleAlipayLogin() {
    // 构建极简版授权URL（必须包含 auth_type=PURE_OAUTH_SDK）
    const appId = 'YOUR_APP_ID'; // 替换为您的应用ID
    // 生成base64编码的state参数（uni-app中可以使用uni.base64Encode或自行实现）
    const state = btoa ? btoa(Date.now().toString()) : Date.now().toString();

    const authUrl = `https://authweb.alipay.com/auth?auth_type=PURE_OAUTH_SDK&app_id=${appId}&scope=auth_user&state=${state}`;

    this.alipay.login({
        scheme: 'tt-alipay-demo', // 应用回调scheme
        params: authUrl, // 授权URL（已编码）
        serviceType: 1, // 三方授权
        success: (result) => {
            console.log("✅ 获取授权码成功:", result.authCode);
            console.log("✅ 状态参数:", result.state);
            // 将authCode发送到后端服务器
            this.sendAuthCodeToServer(result.authCode, result.state)
        },
        fail: (error) => {
            console.error("❌ 支付宝授权失败:", error);
            this.handleAlipayError(error, '支付宝登录');
        },
        complete: (result) => {
            console.log("📱 授权流程完成:", result);
        }
    })
}

// 发送authCode到后端服务器
// uni-app x 平台
sendAuthCodeToServer(authCode: string, state?: string) {
    uni.request({
        url: 'https://your-server.com/api/alipay/login',
        method: 'POST',
        data: { 
            authCode: authCode,
            state: state 
        },
        success: (res) => {
            // 处理登录成功逻辑
            console.log('登录成功:', res.data)
            uni.showToast({
                title: '登录成功',
                icon: 'success'
            })
        },
        fail: (err) => {
            console.error('登录请求失败:', err)
            uni.showToast({
                title: '登录失败',
                icon: 'error'
            })
        }
    })
}

// uni-app 平台
sendAuthCodeToServer(authCode, state) {
    uni.request({
        url: 'https://your-server.com/api/alipay/login',
        method: 'POST',
        data: { 
            authCode: authCode,
            state: state 
        },
        success: (res) => {
            // 处理登录成功逻辑
            console.log('登录成功:', res.data)
            uni.showToast({
                title: '登录成功',
                icon: 'success'
            })
        },
        fail: (err) => {
            console.error('登录请求失败:', err)
            uni.showToast({
                title: '登录失败',
                icon: 'error'
            })
        }
    })
}

第二步：后端换取用户信息

📖 详细流程请参考: 支付宝授权服务端接入

后端需要完成的步骤：

1. 使用authCode换取access_token
2. 使用access_token获取用户信息
3. 返回用户信息给前端

错误处理

错误码说明

// 统一错误处理函数 handleAlipayError(error: any, action: string) { console.error(❌ ${action}失败:, error)

// 获取错误码和错误信息
const errCode = error.errCode || error.code
const errMsg = error.errMsg || error.message

switch(errCode) {
    case 101:
        uni.showModal({
            title: '支付宝未安装',
            content: '请先安装支付宝客户端后再试'
        })
        break

    case 102:
        uni.showToast({
            title: '授权服务异常',
            icon: 'error'
        })
        break

    case 103:
        uni.showToast({
            title: '服务类型错误',
            icon: 'error'
        })
        break

    case 104:
    case 107:
        uni.showToast({
            title: '授权URL配置错误',
            icon: 'error'
        })
        break

    case 105:
        uni.showToast({
            title: '请勿频繁操作',
            icon: 'error'
        })
        break

    case 106:
        uni.showToast({
            title: '授权跳转失败',
            icon: 'error'
        })
        break

    case 108:
        uni.showToast({
            title: '应用配置错误',
            icon: 'error'
        })
        break

    case 1000:
        uni.showToast({
            title: '当前平台不支持',
            icon: 'error'
        })
        break

    case 999:
        // 其他错误，显示具体错误信息
        uni.showToast({
            title: errMsg || '操作失败',
            icon: 'error'
        })
        break

    default:
        // 支付宝SDK原始错误，可能是用户取消等
        if (errMsg && errMsg !== '用户取消') {
            uni.showToast({
                title: errMsg,
                icon: 'error'
            })
        }
        break
}

}

// 使用示例 const authUrl = 'https://authweb.alipay.com/auth?auth_type=PURE_OAUTH_SDK&app_id=YOUR_APP_ID&scope=auth_user&state=YOUR_STATE'; this.alipay?.login({ scheme: 'tt-alipay-demo', params: authUrl, success: (result) => { console.log('登录成功:', result) }, fail: (error) => { this.handleAlipayError(error, '支付宝登录') } } as alipay.TTAliLoginOptions)

## 常见问题

### 1. 找不到插件方法？
**解决方案**: 确保使用自定义基座运行，标准基座不包含原生插件。

### 2. iOS平台登录无响应？
**解决方案**: 
- 检查插件 Info.plist 中的 URL Scheme 配置
- 验证支付宝开放平台的应用配置
- 确保scheme与代码中使用的完全一致

### 3. Android平台授权无响应？
**解决方案**:
- 检查插件 AndroidManifest.xml 中的 scheme 配置
- 验证支付宝开放平台的应用配置
- 确保应用签名与开放平台配置一致

### 4. 平台scheme配置问题？
**解决方案**:
- **iOS**: 修改 `uni_modules/tt-alipay-lite/utssdk/app-ios/Info.plist` 文件
- **Android**: 修改 `uni_modules/tt-alipay-lite/utssdk/app-android/AndroidManifest.xml` 文件
- **HarmonyOS**: 修改 `uni_modules/tt-alipay-lite/utssdk/app-harmony/config.json` 文件
- 建议使用 `ali` + `appid的md5值` 作为scheme，确保唯一性
- 确保支付宝开放平台配置的scheme与代码中一致

### 5. HarmonyOS平台授权无响应？
**解决方案**:
- 检查 `harmony-configs/entry/src/main/module.json5` 中是否添加了 `"apmqpdispatch"`
- 确保 `querySchemes` 数组中包含支付宝回调scheme
- 验证网络权限配置是否正确
- 检查支付宝开放平台的应用配置

### 6. 授权URL配置错误？
**解决方案**:
- 确认授权URL格式正确，必须使用 `https://authweb.alipay.com/auth` 作为基础URL
- 必须包含 `auth_type=PURE_OAUTH_SDK` 参数（极简版SDK固定参数）
- 检查 `app_id` 参数是否正确
- 确认 `scope` 参数为 `auth_base` 或 `auth_user`
- 确保 `state` 参数为base64编码（100位以内）

### 7. 各平台支持哪些业务类型？
**解决方案**:
- **iOS平台**：支持所有业务类型
  - serviceType = 0: 电子发票业务
  - serviceType = 1: 三方授权业务（推荐）
  - serviceType = 2: 代扣业务
- **Android平台**：支持所有业务类型
  - serviceType = 0: 电子发票业务
  - serviceType = 1: 三方授权业务（推荐）
  - serviceType = 2: 代扣业务
  - 代扣业务需要使用 sign_params 参数而非 url 参数
- **HarmonyOS平台**：仅支持授权登录
  - serviceType = 1: 三方授权业务（固定）
  - 不支持电子发票和代扣业务

### 8. 需要支付功能怎么办？
**解决方案**: 
- 本插件为轻量版，专注于授权登录功能
- 如需支付功能，请使用 `tt-alipay-pro` 插件
- 避免同时使用两个插件，防止打包冲突
- 或集成支付宝官方支付插件

### 9. 与tt-alipay-pro插件冲突？
**解决方案**:
- 两个插件不能同时使用，会导致打包冲突
- 纯登录场景：使用 `tt-alipay-lite`
- 登录+支付场景：使用 `tt-alipay-pro`
- 选择其中一个插件即可满足需求

## 版本对比

| 特性 | tt-alipay-lite | tt-alipay-pro |
|------|----------------|---------------|
| **定位** | 轻量级授权登录 | 完整版授权登录+支付 |
| **授权登录** | ✅ | ✅ |
| **支付功能** | ❌ | 🚧 开发中 |
| **官方支付插件兼容** | ❌ 会冲突 | ✅ 完美兼容 |
| **电子发票** | ✅ | ✅ |
| **代扣业务** | ✅ | ✅ |
| **包大小** | 更小 | 更大 |
| **适用场景** | 纯登录场景 | 登录+支付场景 |

## 📞 技术支持

如果在使用过程中遇到问题，请：
1. 查阅上方常见问题
2. 参考支付宝官方开发文档
3. 检查配置是否正确
4. 确认支付宝客户端版本
5. 联系技术支持获取帮助

---

**祝您开发愉快！** 🎉