更新记录

1.0.0（2026-04-07）

支持 三端授权登录功能

平台兼容性

uni-app(4.86)

uni-app x(4.86)

tt-lark-open

🚀 飞书/Lark 授权登录插件，为 uni-app x 提供完整的飞书移动端 SSO 登录能力，支持标准模式与挑战码模式（PKCE）。

📖 目录

• SDK版本信息
• 平台支持说明
• 环境配置
• 快速开始
• 基础使用
• 功能介绍
  • 飞书授权登录
• 错误处理
• 常见问题

SDK版本信息

📚 推荐阅读: 飞书官方移动端 SSO 文档

平台支持说明

支持平台

• ✅ Android
• ✅ iOS
• ✅ HarmonyOS

能力范围

🚨 重要提示

⚠️ 必须使用自定义基座运行，否则无法找到插件方法
⚠️ Android 端请确认宿主 MainActivity 使用 singleTop
⚠️ 回跳 scheme 必须与飞书开放平台配置一致
⚠️ code 需要交由服务端换取 token，客户端不要直接持久化敏感凭证

环境配置

前置条件

1. 在 飞书开放平台 创建移动应用
2. 获取应用 app_id（例如 cli_xxx）
3. 在开放平台完成包名、签名、回调等配置

iOS 平台配置

插件已在 utssdk/app-ios/config.json 配置 LarkSSOSDK 依赖与 LSApplicationQueriesSchemes。
回跳 scheme 请直接在插件内 uni_modules/tt-lark-open/utssdk/app-ios/Info.plist 配置（app_id 去掉下划线后的值）。

示例：

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLName</key>
    <string>LarkSSO</string>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>clixxx</string>
    </array>
  </dict>
</array>

Android 平台配置

插件已提供：

• INTERNET 权限
• queries 查询飞书客户端（lark://ssoclient）

你还需要在宿主 MainActivity 配置：

• launchMode="singleTop"
• 回跳 intent-filter（scheme 为你的 app_id）

参考示例：

<activity
    android:name=".MainActivity"
    android:exported="true"
    android:launchMode="singleTop">
    <intent-filter>
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data android:scheme="cli_xxx" />
    </intent-filter>
</activity>

HarmonyOS 平台配置

插件 utssdk/app-harmony/config.json 使用 @lark/larksso。
宿主侧请确保：

1. module.json5 配置 querySchemes 包含 lark
2. 配置网络权限 ohos.permission.INTERNET

快速开始

1. 导入插件

import * as larkopen from "@/uni_modules/tt-lark-open";

2. 获取 SDK 实例

const lark = larkopen.getTTLarkOpenSDK();

3. 初始化 SDK

lark.register({
  appId: "cli_xxx",
  challengeMode: true,
  scopeList: ["contact:user.id:readonly"],
  success: () => {
    console.log("✅ 飞书SDK初始化成功");
  },
  fail: (err) => {
    console.log("❌ 飞书SDK初始化失败", err);
  },
  complete: () => {}
});

4. 发起授权登录

lark.login({
  challengeMode: true,
  scopeList: ["contact:user.id:readonly"],
  success: (res) => {
    console.log("✅ 登录成功 code:", res.code);
    console.log("codeVerifier:", res.codeVerifier);
  },
  fail: (err) => {
    console.log("❌ 登录失败", err);
  },
  complete: () => {}
});

基础使用

register 参数

TTLarkOpenRegisterOptions

• appId: string 必填，飞书应用 app_id
• challengeMode?: boolean 选填，是否开启挑战码模式（建议 true）
• scopeList?: string[] 选填，授权 scope 列表
• success/fail/complete 回调

login 参数

TTLarkOpenLoginOptions

• challengeMode?: boolean 选填，可覆盖 register 配置
• scopeList?: string[] 选填，可覆盖 register 配置
• success/fail/complete 回调

功能介绍

飞书授权登录

登录成功回调数据：

type TTLarkOpenLoginSuccess = {
  code: string,
  codeVerifier?: string | null
}

• code：服务端换 token 的授权码
• codeVerifier：挑战码模式下返回

错误处理

常见问题

1) Android 点击登录无回调

请优先检查：

• 宿主 MainActivity 是否 singleTop
• 回跳 scheme 是否与 app_id 一致
• 开放平台包名和签名是否正确

2) iOS 能拉起飞书但收不到结果

请检查：

• URL Types 的 scheme 是否使用 app_id 去下划线后的值
• 是否正确处理了 openURL（插件 Hook 已内置）

3) 为什么只有 code，没有 token

这是飞书标准 OAuth 流程。客户端拿到 code 后，需要由你自己的服务端去换取 token。
详见官方文档：移动端 SSO SDK

📞 技术支持

如果在使用过程中遇到问题，请：

1. 查阅上方常见问题
2. 参考飞书官方开发文档
3. 检查配置是否正确

祝您开发愉快！ 🎉