本文介绍 Flutter 项目使用 tencent_kit 插件在 HarmonyOS 平台接入 QQ 登录的完整流程。由于底层限制，仅支持服务端模式登录。主要步骤包括添加依赖、配置腾讯开放平台 AppID 及鸿蒙 BundleName、设置 module.json5 中的 Scheme 回调权限、初始化 SDK 并调用 registerApp 和 setIsPermissionGranted。核心功能为 loginServerSide，返回授权码需经后端换取 access_token。注意事项包括权限调用顺序、授权码有效期及 Scheme 配置细节，避免常见报错如注册失败或无回调。
在 Flutter 跨平台开发中，tencent_kit 插件为 Android、iOS 及 HarmonyOS 提供了统一的腾讯（QQ）SDK 接入能力。针对 HarmonyOS 平台，该插件受底层 SDK 限制，仅支持服务端模式登录及部分基础功能，本文将严格遵循 pub.dev 官方文档规范，详细拆解接入流程、核心功能实现及注意事项，帮助开发者规避常见报错。
根据 tencent_kit 6.2.0 版本官方定义，HarmonyOS 平台仅支持以下 4 个核心方法，其他功能（如客户端直接登录、分享拓展类型等）暂不支持：
setIsPermissionGranted：设置权限授权状态（必须在注册应用前调用）registerApp：初始化并注册应用（关联腾讯开放平台 AppID）isQQInstalled：判断设备是否安装 QQ 客户端loginServerSide：服务端模式登录（唯一支持的登录方式，返回授权码用于后端换取 Token）关键提醒：服务端模式下，插件返回的'授权码'存储在 TencentLoginResp.accessToken 字段中，不可直接当作客户端 Token 使用，需通过后端接口换取正式的 access_token 和 openid。
AppID（纯数字字符串）BundleName、签名指纹（参考应用签名配置方法），审核通过后生效HarmonyOS 应用配置（module.json5）：必须按以下格式配置 Scheme 和权限，否则 QQ 回调会失败（字段不可遗漏或修改）：
{
"module": {
"name": "entry",
"type": "entry",
"package": "com.example.flutterharmony",
"versionCode": 1000000,
"versionName": "1.0.0",
"querySchemes": [
"https",
"qqopenapi"
],
"abilities": [
{
"name": ".MainAbility",
"srcEntry": "./ets/MainAbility/MainAbility.ets",
"launchType": "standard",
"skills": [
{
"entities": [
"entity.system.browsable"
],
"actions": [
"ohos.want.action.viewData"
],
"uris": [
{
"scheme": "qqopenapi",
"host": "102061317",
"path": "auth",
"linkFeature": "Login"
}
]
}
]
}
]
}
}
在 Flutter 项目的 pubspec.yaml 文件中添加插件依赖，配置 AppID（核心参数不可错）：
dependencies:
flutter: sdk: flutter
tencent_kit: ^6.2.0
tencent_kit:
app_id: "102061317"
universal_link: ""
执行以下命令安装插件及相关依赖：
flutter pub get
若使用 Flutter 2.5 版本，需在 ios/Podfile 中添加兼容配置（避免编译报错）：
post_install do |installer|
installer.pods_project.targets.each do |target|
flutter_additional_ios_build_settings(target)
target.build_configurations.each do |config|
config.build_settings['EXCLUDED_ARCHS[sdk=iphonesimulator*]'] = 'i386 arm64'
end
end
end
在应用启动时（如 main.dart 或首页初始化），先调用 setIsPermissionGranted 授予权限，再注册应用，顺序不可颠倒：
import 'package:flutter/material.dart';
import 'package:tencent_kit/tencent_kit.dart';
void main() {
runApp(const MyApp());
}
class MyApp extends StatefulWidget {
const MyApp({super.key});
@override
State<MyApp> createState() => _MyAppState();
}
class _MyAppState extends State<MyApp> {
late final TencentKit _tencentKit;
@override
void initState() {
super.initState();
_initTencentKit();
}
Future<void> _initTencentKit() async {
_tencentKit = TencentKit();
await _tencentKit.setIsPermissionGranted(true);
final bool isRegistered = await _tencentKit.registerApp();
if (isRegistered) {
debugPrint("腾讯 SDK 注册成功");
} else {
debugPrint("腾讯 SDK 注册失败，请检查 AppID 配置");
}
}
@override
Widget build(BuildContext context) {
return MaterialApp(
home: Scaffold(
appBar: AppBar(title: const Text("tencent_kit HarmonyOS 示例")),
body: const Center(child: LoginButton()),
),
);
}
}
class LoginButton extends StatefulWidget {
const LoginButton({super.key});
@override
State<LoginButton> createState() => _LoginButtonState();
}
class _LoginButtonState extends State<LoginButton> {
late final TencentKit _tencentKit;
bool _isQQInstalled = false;
@override
void initState() {
super.initState();
_tencentKit = TencentKit();
_checkQQInstalled();
}
Future<void> _checkQQInstalled() async {
final bool result = await _tencentKit.isQQInstalled();
setState(() => _isQQInstalled = result);
}
@override
Widget build(BuildContext context) {
return Text(_isQQInstalled ? "已安装 QQ" : "未安装 QQ");
}
}
支持两种授权方式：拉起 QQ 客户端授权（已安装 QQ 时）、H5 扫码授权（未安装 QQ 时，通过 qrcode: true 开启），返回的授权码需传给后端换取 access_token。
Future<void> _loginServerSide() async {
if (!_isQQInstalled) {
_doLogin(qrcode: true);
} else {
_doLogin(qrcode: false);
}
}
Future<void> _doLogin({required bool qrcode}) async {
try {
final TencentLoginResp resp = await _tencentKit.loginServerSide(
qrcode: qrcode,
);
if (resp.isSuccess) {
final String authCode = resp.accessToken ?? "";
debugPrint("授权码获取成功：$authCode");
await _getAccessTokenFromBackend(authCode);
} else {
debugPrint("登录失败：${resp.errorMessage}，错误码：${resp.errorCode}");
}
} catch (e) {
debugPrint("登录异常：$e");
}
}
Future<void> _getAccessTokenFromBackend(String authCode) async {
const String backendUrl = "https://你的后端域名/api/qq/token";
try {
// 向后端传递 authCode、AppID、redirect_uri（固定为 auth://tauth.qq.com/）
// 示例请求（实际项目使用 dio 等网络库）
// final response = await Dio().get(backendUrl, queryParameters: {"appid": "102061317", "code": authCode, "redirect_uri": "auth://tauth.qq.com/"});
// 解析后端返回的 access_token 和 openid，用于后续获取用户信息
} catch (e) {
debugPrint("换取 Token 失败：$e");
}
}
@override
Widget build(BuildContext context) {
return ElevatedButton(
onPressed: _loginServerSide,
child: Text(_isQQInstalled ? "QQ 客户端登录" : "QQ 扫码登录"),
);
}
后端需调用腾讯开放平台的'通过授权码获取 Access Token'接口，流程如下：
https://graph.qq.com/oauth2.0/tokengrant_type：固定为 authorization_codeclient_id：你的腾讯 AppIDclient_secret：你的腾讯 AppKey（仅后端存储，不可泄露）code：客户端传递的授权码（authCode）redirect_uri：固定为 auth://tauth.qq.com/（与客户端一致）access_token、expires_in（有效期）、refresh_token 等，后端需存储并返回给客户端用于后续操作。setIsPermissionGranted(true) 必须在 registerApp() 之前调用，否则会报'权限未授予'错误（官方强制要求）。TencentLoginResp.accessToken 是临时授权码（有效期 5 分钟，仅一次有效），不可直接用于获取用户信息，必须通过后端换取正式 access_token。module.json5 中的 host 必须是纯数字 AppID，path 固定为 auth，否则 QQ 授权后无法回调应用。pubspec.yaml 中 app_id 是否与腾讯开放平台一致（含引号，纯数字）；module.json5 中 package 字段与腾讯开放平台的 BundleName 一致。module.json5 的 skills 配置（scheme、host、actions 字段是否与官方一致）；redirect_uri 是否为 auth://tauth.qq.com/；client_secret（AppKey）是否正确，且未泄露给客户端。flutter clean 清理缓存后重新 flutter pub get；tencent_kit 插件为 Flutter 开发者提供了 HarmonyOS 平台的 QQ 登录快捷接入方案，但受限于底层 SDK，仅支持服务端模式登录。核心接入要点可概括为：配置对齐官方要求、权限调用顺序不可错、授权码通过后端换 Token。遵循本文步骤，可快速实现稳定的 QQ 登录功能，若需扩展分享等功能，需结合腾讯官方 HarmonyOS SDK 单独集成。
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online
将 Markdown（GFM）转为 HTML 片段，浏览器内 marked 解析；与 HTML 转 Markdown 互为补充。 在线工具，Markdown 转 HTML在线工具，online
将 HTML 片段转为 GitHub Flavored Markdown，支持标题、列表、链接、代码块与表格等；浏览器内处理，可链接预填。 在线工具，HTML 转 Markdown在线工具，online
通过删除不必要的空白来缩小和压缩JSON。 在线工具，JSON 压缩在线工具，online
将JSON字符串修饰为友好的可读格式。 在线工具，JSON美化和格式化在线工具，online