更新记录

1.0.1（2026-04-09）

支持 Harmony平台

1.0.0（2025-08-31）

支持 新浪微博授权登录与分享 支持 iOS平台与安卓平台

平台兼容性

uni-app(4.86)

uni-app x(4.86)

tt-weibo-sdk

🚀 新浪微博SDK插件，为 uni-app x && uni-app 提供完整的新浪微博集成解决方案，包含登录、分享功能

📖 目录

• SDK版本信息
• 环境配置
  • iOS平台配置
  • Android平台配置
  • HarmonyOS（鸿蒙）平台配置
• 快速开始
• 基础使用
• 功能介绍
  • 微博授权登录
  • 微博分享功能
• 错误处理
• 常见问题

SDK版本信息

功能支持矩阵

📚 推荐阅读: 微博开放平台官方文档

🚨 重要提示

⚠️ 必须使用自定义基座运行，否则无法找到插件方法（鸿蒙端同样需要包含本插件与 core.har 的自定义基座 / 云打包配置）

⚠️ 必须配置正确的重定向地址，否则登录功能无法正常工作

⚠️ iOS / Android 原生侧配置已内置在插件内（utssdk/app-ios/Info.plist、utssdk/app-android/AndroidManifest.xml），请在其中替换 AppKey（wb 前缀） 等占位内容并重新打自定义基座，无需再到工程根目录重复配置同名片段

环境配置

前置条件

1. 在微博开放平台申请移动应用
2. 获取 AppKey
3. 配置应用包名、签名和重定向地址

iOS平台配置

1. 插件内 Info.plist（已内置，无需改工程根目录）

微博所需的 CFBundleURLTypes、LSApplicationQueriesSchemes 已配置在插件内：

uni_modules/tt-weibo-sdk/utssdk/app-ios/Info.plist

使用自定义基座或云打包时，uni-app 会将该文件合并进主应用，一般不必再在项目根目录单独维护一份 Info.plist。

你必须修改：打开上述插件内 Info.plist，将 wb您的微博AppKey 替换为 wb + 你在微博开放平台申请的 AppKey（与开放平台配置一致）。

说明：若需增删 LSApplicationQueriesSchemes 或调整 URL Types，直接编辑该插件文件即可；完整键值结构以仓库内文件为准。

iOS 端隐私清单见同目录 PrivacyInfo.xcprivacy（随插件一并参与打包）。

2. 配置通用链接（Universal Link）

使用 register 时的 universalLink 时，仍需在应用侧按 uni-app 要求配置 Associated Domains 等，与是否使用插件内 Info.plist 无关。

📖 详细步骤请参考：uni 官方文档 - 通用链接

Android平台配置

1. 插件内 AndroidManifest.xml（已内置，无需改工程根目录）

权限、queries、微博 AuthActivity / ShareActivity / WeiboSdkWebActivity 等已写在插件内：

uni_modules/tt-weibo-sdk/utssdk/app-android/AndroidManifest.xml

打包时会与主工程清单合并，一般不必再在项目根目录重复粘贴整段微博配置。

你必须修改：

• 将 AuthActivity 上 intent-filter 里 data 的 android:scheme（当前为占位 wb您的微博AppKey）改为 wb + 你的 AppKey。
• 若文件顶部 package="您的包名" 仍为占位，请改为与本应用实际包名一致（或与当前 HBuilder / uni-app 对 UTS 插件 Manifest 的合并规则保持一致；以打包后生效结果为准）。

混淆规则见同目录 proguard.cfg。

2. 注意事项

• 微博开放平台中的 包名、签名 须与当前应用一致；重定向地址须与代码里 register 的 redirectUrl 一致。
• 测试时使用与平台登记相同的签名，避免 SSO 校验失败。

HarmonyOS（鸿蒙）平台配置

1. SDK 依赖（core.har）

插件鸿蒙端依赖微博官方提供的 core.har，默认路径为：

uni_modules/tt-weibo-sdk/utssdk/app-harmony/libs/core.har

请从微博开放平台提供的 鸿蒙 SDK / Demo 压缩包中获取同名文件并放入上述目录（或按包内说明替换升级）。utssdk/app-harmony/config.json 中已声明依赖名为 core，与官方示例 oh-package.json5 一致。

2. module.json5（querySchemes 与网络权限）

在鸿蒙工程模块的 module.json5（例如自定义基座或 harmony-configs 下的 entry/src/main/module.json5）中：

• 配置 ohos.permission.INTERNET（插件示例中已包含）。
• 在 querySchemes 中声明微博相关 Scheme，以便系统允许检测 / 调起微博客户端，例如：

"querySchemes": [
  "sinaweibo",
  "weibo",
  "weibosdk",
  "weibosdk2.5",
  "weibosdk3.3",
  "sinaweibohd"
]

若工程同时集成微信等能力，可将上述项与 weixin、wxopensdk 等并列配置。

3. 开放平台：包名与签名

鸿蒙应用需在开放平台完成移动应用信息配置，其中：

• 包名：与工程 AppScope/app.json5 中的 bundleName 一致。
• 签名：按微博鸿蒙接入文档注册 MD5 签名；可使用官方 Demo 中 Utility.getSign 等方式获取（详见开放平台提供的注册说明 / FAQ）。

未正确配置包名或签名时，会出现授权失败、SSO 校验错误等问题。

4. 初始化与授权回调

• 业务侧须先调用 register，传入 appKey、redirectUrl，可选 scope（空字符串表示走快捷授权等，以微博文档为准）。鸿蒙端不需要 universalLink。
• 插件在 register 成功后会注册微博 SDK，并通过 UTSHarmony.onAppAbilityCreate / onAppAbilityNewWant 调用 WBAPI.doWBAsResult，将授权与分享结果回传，一般无需在宿主 EntryAbility 里再手写微博回调。
• 若你自行修改了应用 Ability 生命周期，请确保从微博返回时仍能执行微博 SDK 要求的结果处理，避免收不到登录 / 分享回调。

官方 Demo 还会在 AbilityStage 中提前 registerApp；本插件在首次 register 时完成等价初始化，通常可满足业务。若需与官方 Demo 完全一致的应用级初始化时机，可在宿主侧增加 AbilityStage 自行接入（与插件并行时注意避免重复注册逻辑冲突）。

5. 与 Android / iOS 的行为差异（使用前必读）

快速开始

1. 导入插件

import { getTTWeiBoSDK } from '@/uni_modules/tt-weibo-sdk';

export default {
    data() {
        return {
            weiboSDK: null as any,
        }
    },
    onLoad() {
        // 获取微博SDK实例
        this.weiboSDK = getTTWeiBoSDK()
        // 注册微博SDK
        this.initWeiboSDK()
    },
    methods: {
        // 初始化微博SDK
        initWeiboSDK() {
            // SDK初始化代码见下方
        }
    }
}

2. 初始化 SDK

initWeiboSDK() {
    if (!this.weiboSDK) {
        console.error('微博SDK初始化失败')
        return
    }

    this.weiboSDK?.register({
        appKey: "您的微博AppKey",                    // 必填：微博开放平台申请的AppKey
        redirectUrl: "您的重定向地址",                // 必填：重定向地址
        scope: "all",                               // 可选：权限范围，默认all
        universalLink: "您的通用链接",               // iOS 可选；鸿蒙端忽略即可
        success: (res) => {
            console.log("✅ 微博SDK初始化成功");
        },
        fail: (err) => {
            console.error("❌ 微博SDK初始化失败:", err);
            uni.showToast({
                title: '微博SDK初始化失败',
                icon: 'error'
            })
        }
    });
}

功能介绍

微博授权登录

💡 微博登录需要用户授权，登录成功后会返回accessToken和用户信息

参数说明

TTWeiBoLoginOptions

返回值 TTWeiBoLoginSuccess

示例代码

// 微博登录
handleWeiboLogin() {
    this.weiboSDK?.login({
        success: (res) => {
            console.log("✅ 微博登录成功:", res);
            console.log("AccessToken:", res.accessToken);
            console.log("用户ID:", res.userId);
            console.log("过期时间:", res.expiresIn);
            console.log("刷新Token:", res.refreshToken);

            // 保存登录信息
            uni.setStorageSync('weiboLoginInfo', {
                "accessToken": res.accessToken,
                "userId": res.userId,
                "expiresIn": res.expiresIn,
                "refreshToken": res.refreshToken
            } as UTSJSONObject);

            // 登录成功后获取用户信息
            this.getUserInfo()
        },
        fail: (err) => {
            console.error("❌ 微博登录失败:", err);
            this.handleLoginError(err)
        },
        complete: (res) => {
            console.log("微博登录完成:", res);
        }
    });
}

// 处理登录错误
handleLoginError(error: any) {
    const errCode = error.errCode;
    const errMsg = error.errMsg;

    switch(errCode) {
        case 201:
            console.log('用户取消登录');
            break;
        case 202:
            uni.showToast({
                title: '登录失败',
                icon: 'error'
            });
            break;
        case 203:
            uni.showModal({
                title: '微博未安装',
                content: '请先安装微博客户端',
                showCancel: false
            });
            break;
        case 204:
            uni.showToast({
                title: '网络错误',
                icon: 'error'
            });
            break;
        case 205:
            uni.showToast({
                title: '授权被拒绝',
                icon: 'error'
            });
            break;
        default:
            uni.showToast({
                title: errMsg || '登录失败',
                icon: 'error'
            });
            break;
    }
}

微博分享功能

💡 支持分享文本、图片、网页链接和视频到微博

分享类型

分享类型 (type)

• 0 - 文本分享
• 1 - 图片分享
• 2 - 网页链接分享
• 3 - 视频分享

参数说明

TTWeiBoShareOptions

使用示例

1. 分享文本

shareText() {
    this.weiboSDK?.share({
        type: 0,
        text: '这是一条微博文本分享，支持最长2000个字符的内容。',
        success: (res) => {
            console.log('✅ 文本分享成功');
            uni.showToast({ title: '分享成功' });
        },
        fail: (err) => {
            console.error('❌ 分享失败:', err);
            uni.showToast({ title: '分享失败', icon: 'error' });
        }
    });
}

2. 分享图片

shareImage() {
    this.weiboSDK?.share({
        type: 1,
        text: '分享一张图片',
        imagePath: '/static/share-image.jpg', // 本地图片路径
        success: (res) => {
            console.log('✅ 图片分享成功');
        },
        fail: (err) => {
            console.error('❌ 图片分享失败:', err);
        }
    });
}

3. 分享网页链接

shareWebPage() {
    this.weiboSDK?.share({
        type: 2,
        text: '分享一个网页链接',
        url: 'https://www.example.com',
        success: (res) => {
            console.log('✅ 网页分享成功');
        },
        fail: (err) => {
            console.error('❌ 网页分享失败:', err);
        }
    });
}

4. 分享视频

shareVideo() {
    this.weiboSDK?.share({
        type: 3,
        text: '分享一个视频',
        videoPath: '/static/share-video.mp4', // 本地视频路径
        // 鸿蒙端必填：封面图本地路径（Android / iOS 可不传，由各自 SDK 处理）
        imagePath: '/static/video-cover.png',
        success: (res) => {
            console.log('✅ 视频分享成功');
        },
        fail: (err) => {
            console.error('❌ 视频分享失败:', err);
        }
    });
}

鸿蒙说明：type=3 时必须同时提供 videoPath 与 imagePath（封面）。仅 Android / iOS 时若你的业务不需要封面，可去掉 imagePath，以各端实际编译与 SDK 要求为准。

错误处理

错误码说明

常见问题

1. 找不到插件方法？

解决方案: 确保使用自定义基座运行，标准基座不包含原生插件。

2. iOS平台登录/分享无响应？

解决方案:

• 检查插件内 uni_modules/tt-weibo-sdk/utssdk/app-ios/Info.plist 中 URL Scheme 是否为 wb + AppKey，并已重新打自定义基座
• 确认通用链接（若使用 universalLink）与 Associated Domains 配置正确
• 验证微博开放平台的 iOS 应用配置
• Scheme 格式须为 wb 前缀 + 数字 AppKey，与开放平台一致

3. Android平台功能异常？

解决方案:

• 确认应用签名与微博开放平台配置一致
• 检查包名是否正确（含插件内 AndroidManifest.xml 的 package 占位是否已改为实际包名）
• 确认插件内 wb + AppKey 的 scheme 与开放平台一致并已重新打自定义基座
• 确保微博客户端版本支持相关功能
• 验证重定向地址配置

4. 登录失败或授权被拒绝？

常见原因:

• 重定向地址配置错误
• 微博开放平台应用配置不完整
• 用户拒绝授权
• 网络连接问题

解决方案:

• 检查重定向地址是否与微博开放平台配置一致
• 确认应用权限配置正确
• 提示用户重新授权
• 检查网络连接状态

5. 分享图片/视频失败？

解决方案:

• 确保图片/视频路径为本地路径，不支持网络文件
• 检查文件是否存在且格式正确
• 图片/视频大小不要超过限制

6. 重定向地址配置问题？

重要说明:

• 重定向地址是微博登录的关键配置
• 必须与微博开放平台配置完全一致
• 支持自定义协议，如：myapp://weibo/callback
• 建议使用HTTPS协议的URL

7. 微博客户端版本兼容性？

解决方案:

• 建议使用最新版本的微博客户端
• 某些功能可能需要特定版本的微博支持
• 在功能使用前先检查微博是否安装
• 提供降级方案（如网页版登录）

8. 通用链接配置问题？

解决方案:

• 确保域名支持HTTPS
• 验证apple-app-site-association文件配置正确
• 检查苹果开发者账号中的Associated Domains配置
• 测试通用链接是否能正常跳转

9. 分享内容长度限制？

重要提示:

• 文本分享最长2000个字符
• 图片文件建议小于10MB
• 视频文件建议小于100MB
• 网页链接必须是有效的URL格式

10. 鸿蒙端登录成功但没有 refreshToken？

说明：鸿蒙微博官方 Oauth2AccessToken 未提供与 Android 完全一致的 refresh 接口，插件侧成功回调中 refreshToken 为 null 属预期行为。需要长期会话时请在服务端结合开放平台文档使用 accessToken 有效期 或其它授权方式。

11. 鸿蒙分享网页（type=2）效果与 Android 不一致？

说明：鸿蒙 SDK 能力以文本 / 图片 / 视频为主，本插件对 type=2 采用 文案 + 链接合并为文本 的策略，与 Android / iOS 的网页对象分享可能不同。若需统一体验，可对鸿蒙端单独使用 type=0 自行拼接文案与链接。

12. 鸿蒙视频分享报错 / 提示路径无效？

请检查：

• 是否同时传了 videoPath 与 imagePath（封面本地路径）。
• 路径是否为应用可访问的本地文件（可先使用 UTSHarmony.convert2AbsFullPath 能正确解析的路径）。

📞 技术支持

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

1. 查阅上方常见问题
2. 参考新浪微博官方开发文档
3. 检查配置是否正确
4. 确认新浪微博客户端版本

祝您开发愉快！ 🎉