企业官网建设流程全解析

简介：一份面向Unity开发者的华为HMS SDK接入Demo资源包，适合需在华为设备上集成游戏服务、账号登录、推送等能力的开发者。包内包含完整Unity工程与示例代码，涵盖SDK导入、项目配置、初始化、登录及功能调用等关键环节，并附有可运行APK及调试日志，便于对照学习排错。资源共2000个文件，压缩包约28.82MB，文件构成以bin、class、jar、java、xml等为主，bin与class对应编译库与字节码，jar、java为SDK依赖及接口源码，info、meta等为Unity与Android工程元数据，整体结构贴近真实接入场景。该资源在CSDN已有1842人学习下载，开发者可由此理解HMS SDK在Unity环境下的接入流程，快速定位版本兼容、权限配置等问题，并可直接基于示例工程改造，缩短华为生态集成周期。

1. Unity接入华为SDK demo：别一上来就写业务代码，先跑通官方包再谈集成

做国内安卓发行的Unity开发者，几乎都会撞上“华为渠道接入”这个需求。账号登录、推送、支付、角标适配，每一项背后都是华为自家的HMS Core SDK。很多人拿到“Unity接入华为SDK demo”之后，第一反应是往自己的项目里塞SDK包，然后被一堆构建报错卡住好几天。实际上，正确的顺序应该是先把官方demo完整跑通，理解它的目录结构、AGC后台配置和构建链路，再迁移到自己的工程。这篇文章就把从环境准备、demo导入、真机调试到踩坑排错的完整路径讲清楚，适合刚开始接触HMS Core的Unity客户端同学，也适合正在赶华为应用市场上架排期的团队。

2. 挑对SDK和准备环境：HMS Core、AGC后台与Unity工程的三方对齐

很多人被“华为SDK”这个名字误导，以为是一个能一把梭的集成包。实际在Unity里，华为SDK是按服务拆开的，每个服务对应独立的Unity包、独立的初始化代码和独立的AGC后台配置。这一章先把选型和环境准备好，后面demo才能少走弯路。

2.1 华为SDK不是只有一个包：HMS Core各服务的Unity接入差异

HMS Core是华为移动服务的能力集合，Unity接入时常见的有账号登录、推送、应用内支付、游戏服务、地图、统一扫码等。在华为开发者联盟下载页面里，每个服务都是一个单独的unitypackage，命名一般是 HMSAccount / HMSPush / IAP 这样的关键词。下载之前先想清楚你的应用到底需要哪几个服务，不要一上来把全家桶都导进去，包体爆炸不说，AGC后台的服务开通状态还会影响初始化。

选型时注意一点：同一服务在不同版本SDK里的初始化方式可能不一样。老版本SDK用的是“manifest里配置meta-data + 全局初始化”，新版本则要求在代码里显式调用初始化接口。看官方demo时，先确认它对应的是哪个SDK版本，再对照自己手里的包，避免照着老demo写新版代码，最后回调各种不触发。

2.2 开发者账号与AppGallery Connect：上架前必须完成的3项配置

在Unity工程里写任何代码之前，先把华为开发者联盟的账号搞定。流程不复杂，但每一步都关系到后面能不能跑通：第一步注册开发者账号，第二步在AppGallery Connect后台创建应用，第三步下载应用的 agconnect-services.json 配置文件。

创建应用时有两个极易埋雷的地方：应用包名必须和Unity工程的包名完全一致，别今天起一个 com.test.demo，明天Unity里改成 com.xxx.game，后面所有日志报错都来自这里；签名证书的SHA-256指纹必须填进后台，很多demo真机闪退都是因为指纹没填或者填成了debug签名的指纹。

配置完成后，后台会生成一个 JSON 配置文件，把它下载下来，之后放进Unity工程的Assets根目录。我一般会打开文件检查一下关键字段，它长这样，字段结构节选如下：

{ "agcgw": { "host_url": "https://connect-api.cloud.huawei.com" }, "client": { "app_id": "123456789", "api_key": "xxx", "package_name": "com.yourcompany.yourapp" }, "project_info": { "project_id": "project-xxx" } }

这个JSON里最核心的是client段。app_id对应华为开发者联盟给应用分配的唯一ID，api_key是SDK访问服务端接口的凭证，package_name必须和你Unity里设置的应用包名完全一致。如果这三个值任何一个有问题，SDK初始化阶段就会在Logcat里报类似“app_id not match”的错误。还要确认一下文件确实放在了Assets根目录下，而不是嵌套在某个子文件夹里，否则Unity打包时不会把它带进APK。

2.3 Unity工程侧：版本、JDK、Android SDK与包名的硬性要求

Unity环境的版本匹配是很多人翻车的地方。华为HMS Core Unity SDK在2019.4、2020.3、2021.3这几个LTS版本上表现最稳，如果你工程还在用2018或2017，建议先升级再接入，硬上老版本会碰到Gradle插件的兼容性问题。还没装Unity的话，用Unity Hub安装时勾选Android Build Support模块，这一步很多人会忘记，导致后面导出APK时报SDK工具缺失。

JDK和Android SDK方面，HMS Core的Android原生层要求Java 8字节码，所以JDK版本建议用1.8；Android SDK的compileSdkVersion在28到30之间比较稳妥。打开终端检查一下当前环境：

# 检查JDK版本，Unity 2019-2021通常要求JDK 1.8 java -version # 检查Android SDK路径和已安装的平台版本 echo "$ANDROID_HOME" ls "$ANDROID_HOME/platforms"

Unity导出APK时会优先使用Unity内置的JDK和SDK路径，如果输出里版本信息异常，去Unity的 External Tools 设置面板里重新指定路径即可。我习惯把ANDROID_HOME显式配置成Unity Hub安装的SDK目录，这样命令行工具和Unity编辑器用的是同一套环境，排查问题时少很多疑惑。

还有两个设置项在建工程时就设好：Player Settings里的Scripting Backend设为IL2CPP，Target Architectures勾选ARM64。华为应用市场对64位包的要求越来越严，Mono模式可能在部分新机型上出现异常，所以提前切换到IL2CPP能省掉后面上架时的返工。包名设置同样在Player Settings里，记住一个原则：Unity里的包名、AGC后台创建的包名、签名文件里的包名，三者必须完全一致，少一个分号都不行。

3. 把官方demo导入Unity：从unitypackage到APK的完整链路

环境准备好之后，真正的“Unity接入华为SDK demo”操作就开始了。这一章的目标只有一个：让官方demo在你的华为真机上跑起来。不要着急改业务逻辑，先把整条链路走通。

3.1 获取demo的两种方式和目录结构

获取华为SDK demo最常见的渠道有两个：一个是去华为开发者联盟的HMS Core Unity SDK下载页找对应服务板块，页面里会提供包含示例工程的zip包；另一个是去官方GitHub仓库找Unity插件工程。第一次做接入时建议用前者下载的完整demo包，因为它是已经组装好的示例工程，省去自己拼装的时间。下载慢的问题，常见做法是换一个网络时段重试，或者直接从Google搜索包名找其他分发地址，不要在一个坏链接上死磕。

解压下载的zip后，工程目录通常能看到这样的结构：

HMS-Core-Unity-Plugin/ ├── Assets/ │ ├── HMSCore/ # 各服务封装层，C#脚本和Android原生aar │ ├── Plugins/Android/ # 依赖配置和AndroidManifest片段 │ └── Samples/ # 官方示例场景和测试脚本 ├── Packages/ ├── ProjectSettings/ └── build.gradle

这个结构里最有价值的是HMSCore目录，它包含了SDK所有的C#封装和原生库，是后续业务开发要依赖的核心；Samples目录里是可运行的示例场景，演示了每个API的调用方式。先花十分钟把Samples里的场景和相关脚本看一遍，比直接开接要高效得多，你会看到它们是怎么处理登录回调、token获取这些典型逻辑的。

3.2 把unitypackage导入demo工程的正确顺序

拿到的是工程源码压缩包就直接解压用Unity打开，拿到的是unitypackage则需要导入已有工程。导入顺序有讲究，我一般是这么做的：先创建一个空的Unity工程，包名设好，再用Build Target切到Android，然后双击unitypackage导入。导入完成后马上看Console面板有没有报错，如果看到一堆编译错误，多半是SDK版本和Unity版本不匹配，这时候先停下来换版本，不要硬往下走。

导入完成后，把上一章下载的agconnect-services.json复制到Assets根目录。这个文件放到Assets下面是因为Unity打包时会把整个Assets目录的内容打进去，JSON文件会被放进APK的assets目录，SDK启动时从这个位置读取配置。放错位置导致的典型报错是初始化时找不到配置文件，日志里会提示“Failed to parse agconnect-services.json”。

检查文件是否就位，可以直接在工程根目录下执行命令确认：

# 确认关键文件是否就位，缺哪个补哪个 ls -la Assets/agconnect-services.json ls -la Assets/HMSCore/ ls -la Assets/Plugins/Android/

确认这三个文件都在后，打开Build Settings，把Samples里的示例场景加入Build列表，点击Build按钮生成APK。如果你用的是Unity 2019.4，第一次构建会自动下载对应的Gradle版本，这个过程受网络环境影响可能很慢，甚至失败。常见做法是把下载链接复制到浏览器手动下载，然后放进用户目录下的.gradle/wrapper/dists对应文件夹中，重新构建就好。

3.3 第一次构建APK和真机启动：预期什么、看什么日志

构建成功只是第一步，离“跑通”还差真机验证。连接一台华为手机（或者已升级HMS Core的荣耀手机），开启USB调试，把APK装上去。注意华为手机默认会拦截“未知来源应用”的安装，安装时会弹窗确认，这是正常现象。

启动应用后先在Logcat里过滤HMS相关日志，命令是：

adb logcat -s HMS* Unity* AndroidRuntime:E

这条命令的-s参数用来指定日志tag过滤器，HMS*匹配华为SDK的日志输出，Unity*匹配Unity引擎日志，AndroidRuntime:E只显示Java层崩溃错误。启动应用后如果看到“HMS Core is not available”或者“service is unavailable”这类的日志，大概率是设备上的华为移动服务版本过旧，去应用市场更新HMS Core即可。

还有一种情况是日志里出现“Debug mode not opened”或“not allow to call api”。这是因为应用还没有上架，AGC后台默认不允许未上架的应用调用线上接口。解决办法是去AppGallery Connect后台，在应用信息页打开“调试模式”，并把当前华为账号添加到测试用户列表里，之后重新构建并安装就能正常走接口了。这一步做完，demo的程序流程才算真正完整走通。

4. 在demo里接第一个服务：账号登录和推送的最小可运行代码

demo跑通之后，下一步是在示例代码的基础上接自己的业务。账号登录和推送是绝大多数App会用到的两个基础服务，而且它们的接入模式可以复用到你后面接IAP、GameService等更多服务上。

4.1 账号服务：初始化、静默登录与拉起华为登录页

华为账号登录的SDK放出来之后，第一步是构造授权参数。授权参数决定你向用户申请哪些权限，比如只登录拿昵称头像，就只需要ID Token和Profile权限，不要申请手机号，否则审核时会多很多麻烦。这里用官方封装好的AccountAuthParamsHelper来串参数，最小可运行的初始化加静默登录代码如下：

using Huawei.Hms.Account; using Huawei.Hms.Common; using UnityEngine; public class HuaweiAccountDemo : MonoBehaviour { private void Start() { // 构造授权参数：申请ID Token和Profile权限，用于获取用户标识和公开资料 var helper = new AccountAuthParamsHelper(AccountAuthParams.DEFAULT_AUTH_REQUEST_PARAM) .SetIdToken() .SetProfile(); AccountAuthParams authParams = helper.CreateParams(); // 用授权参数创建账号认证服务 var service = new AccountAuthService(authParams); // 优先静默登录：如果用户之前授权过，华为会返回缓存的账号信息 service.SilentSignIn() .AddOnSuccessListener(account => { Debug.Log("静默登录成功：" + account.DisplayName); }) .AddOnFailureListener(e => { Debug.Log("静默登录失败，准备拉起登录页：" + e.Message); StartAuthCodeFlow(service); }); } private void StartAuthCodeFlow(AccountAuthService service) { // 拉起华为账号授权页，用户完成操作后结果回调到Activity service.StartSignIn(/* 当前Activity上下文 */); } }

这段代码里有几个点值得说明。DEFAULT_AUTH_REQUEST_PARAM是SDK预置的默认授权范围合集，能覆盖大部分游戏和应用的登录需求；SetIdToken()会在登录成功后返回一个JWT格式的ID Token，用来在后端服务器验证用户身份；SetProfile()允许读取用户昵称和头像。拿到AuthAccount对象后，除了DisplayName，还能取AvatarUriString、OpenId等字段，这些在界面上展示用户信息时直接可用。

静默登录失败时会进入StartAuthCodeFlow，这里调StartSignIn拉起华为账号登录页。注意这个方法需要传入一个Android Activity上下文，在纯Unity环境下通常是通过AndroidJavaObject获取当前的Activity，或者借助demo工程里封装好的HMSAgent类来简化这步。用户名密码的输入、授权确认都在华为账号页完成，你的App无需再写一套账号密码界面。

4.2 推送服务：token获取与收到消息的两种调试方式

推送服务相比账号登录要简单得多，核心就是一件事：拿到设备推送token。token上送给你的服务器，之后服务端通过华为推送接口向这个token下发消息。最小代码就一段：

using Huawei.Hms.Push; using UnityEngine; public class PushTokenDemo : MonoBehaviour { private void Start() { // 获取当前设备的推送token，通常在上送成功前需要缓存到本地 HmsMessaging.GetInstance() .GetToken() .AddOnSuccessListener(token => { Debug.Log("推送token：" + token); }) .AddOnFailureListener(e => { Debug.Log("获取token失败：" + e.Message); }); } }

HmsMessaging.GetInstance()是HMS推送服务的入口单例，GetToken()发起异步请求，成功后会返回一串长字符串。这个token每个设备、每个应用都是唯一的，卸载重装可能会变化，所以客户端每次启动都重新获取并上送是比较稳的实践。

token拿到之后怎么验证推送链路通不通？我一般用两种方式。第一种是直接上AGConnect后台的消息通知页面，创建一个测试通知，目标选“按设备token”，填入刚打印出来的token，发送之后看手机通知栏有没有消息，这种方式能验证整条服务端到客户端链路。第二种方式是在本地调试阶段用命令行模拟一个本地通知，快速验证消息处理回调，不用走后台。两种方式配合，能快速区分问题出在服务端还是客户端。

4.3 主线程调度：回调不触发的第一个嫌疑点

很多人在接HMS的时候遇到一个玄学问题：代码照着demo抄的，接口调用成功，但回调里的Debug.Log始终不打印。第一反应是SDK没用对，实际上问题出在线程。HMS的回调可能不在Unity主线程上执行，而Unity的API（比如Debug.Log、GameObject.SetActive）只能在主线程调用，跨线程调用轻则日志丢失，重则直接崩溃。

遇到这种情况，标准姿势是把回调内容通过线程调度器切回主线程，代码如下：

using Huawei.Hms.Common; using UnityEngine; void OnSuccess(AuthAccount account) { // HMS回调线程可能不是Unity主线程，统一切到主线程再操作Unity API Huawei.Hms.Common.ThreadManager.RunOnMainThread(() => { Debug.Log("主线程执行，安全更新UI：" + account.DisplayName); }); }

ThreadManager.RunOnMainThread是HMS Unity SDK提供的线程调度工具，接受一个Action，把里面的逻辑投递到Unity主线程执行。所有涉及Unity对象操作的代码都放进这个Lambda里，就不会再出现“日志偶尔打不出来”或“随机闪退”这类的诡异现象。这条经验能帮你解决掉接入过程中至少三分之一的问题。

5. Unity接入华为SDK的5个高频坑：从构建失败到回调丢失

这一章是整篇文章里最值钱的部分。下面这5个坑，前前后后坑过我很多时间，也经常在社区里看到别人反复踩。每一条我都按“现象 → 原因 → 解决”的顺序写，方便你直接对号入座。

5.1 坑一：Gradle构建失败，报错指向SDK版本冲突

现象：Unity导出APK时，Gradle构建跑到一半报错，提示duplicate class或Conflict with dependency。原因：华为SDK的Android原生层依赖于特定版本的AndroidX库或HMS Core基础包，你项目里其他插件（比如友盟、极光）也依赖了不同版本的同名库，Gradle解析依赖时无法统一。解决：在Unity的Assets/Plugins/Android/mainTemplate.gradle里显式声明依赖版本，强制所有模块使用同一个版本号。常见做法是把冲突的依赖force掉，或者用exclude把重复传递的依赖剔除。

5.2 坑二：真机启动闪退，Logcat里提示证书指纹或app_id错误

现象：APK装到手机上，一启动就崩溃，Logcat日志里有app_id not match、fingerprint关键字。原因：AGC后台的App ID或SHA-256指纹与本地签名不匹配。绝大多数情况是你用debug签名打的包，而后台填的是release签名的指纹，或者干脆没填。解决：核对Unity导出设置里的Keystore指纹，用keytool -list -v -keystore xxx.keystore查SHA-256，然后去AGC后台把对应的指纹填上。debug和release各填一个，避免之后切换构建模式时再次闪退，这算是提前给自己留后悔药。

5.3 坑三：C#调用成功但回调不回来，子线程操作Unity API被忽略

现象：接口调用进去了，日志里也能看到HMS侧的调用记录，但自己的AddOnSuccessListener里没有输出。原因：回调执行在线程池线程，Debug.Log跨线程调用有时被Unity静默吞掉，看起来就像回调没触发。解决：把回调逻辑包进ThreadManager.RunOnMainThread，统一主线程分发，这个问题在第四章节已经演示过。遇到回调不回来，先检查线程，再检查回调参数类型，别急着怀疑SDK坏掉了。

5.4 坑四：打包到手机画面拉伸、UI变形，机型适配问题

现象：demo跑得好好的，换一台华为全面屏手机，UI被拉伸，按钮跑到屏幕外面，画面变形。原因：Unity的默认画面适配没有针对全面屏和挖孔屏做处理，华为设备在刘海屏、挖孔屏下的显示区域比普通屏幕特殊。解决：在启动场景里显式设置屏幕方向，并针对SafeArea做自适应。用ScreenAdaptation脚本获取Screen.safeArea，把根布局的内边距设置成安全区范围，同时检查分辨率的match设置。接入华为SDK做上架测试时，一定要准备一台全面屏和一台带挖孔的机器，不然发上去之后线上反馈会很难看。

5.5 坑五：demo能跑，自己工程接入却报错：AndroidManifest合并冲突

现象：demo构建没问题，同样的SDK导入自己工程后，构建报Manifest merger failed，提示某些属性重复定义或权限缺失。原因：demo工程里已经帮你配置好了AndroidManifest.xml里的华为相关Activity、权限和meta-data，而你的工程里也有自己的manifest，两边的同名标签合并时冲突。解决：打开Assets/Plugins/Android/AndroidManifest.xml检查，把华为SDK要求的HuaweiIdAuthActivity、PushActivity等组件手动合入主manifest，同时确认Fingerprint等meta-data已声明。每次构建失败时，Unity都会生成一份合并后的manifest文件，通常位于Temp/StagingArea/AndroidManifest.xml，用diff工具对比一下就能找到冲突点，这个文件是个好东西，能省很多时间。

6. 离开demo前：把配置固化进自己的发布流程

demo跑通了，SDK也接上了，最后一步是把自己从“照着demo敲代码”的状态拔出来，让这套配置成为可复用的发布基建。我这里的做法是给Unity工程增加一个华为渠道的构建标记，用条件编译把HMS初始化代码和普通逻辑隔离，这样同一份代码既可以出华为渠道包，也可以出普通安卓包。核心代码如下：

#if HUAWEI_CHANNEL // 只在华为渠道包中初始化HMS相关服务 InitHuaweiSdk(); #endif

这个宏定义通过Unity的Scripting Define Symbols设置，在Build Settings的Player Settings里给Android平台加一个HUAWEI_CHANNEL即可。建议写一个编辑器的构建脚本，构建前自动判断平台并设置对应的符号，顺手把包名后缀和签名文件也统一处理好。这样每次发版不是靠手改配置，而是执行一条构建命令，配置漂移的问题就从根本上消除了。

上架前再把几项关键内容过一遍，我每次发包前都会照着这个表核对：

这套流程走下来，最大的收获其实是心态上的转变：刚接华为SDK时总想着代码怎么抄，后来发现真正容易出问题的都不是C#部分，而是包名、签名、后台配置和线程调度这些“环境性”的东西。建议你在自己的工程里也建立一份渠道接入清单，把每次踩坑的日志片段和解决方式都记进去。我自己的清单已经存了几十条，后来再接小米、OPPO的SDK，很多坑都是同一类型的，照着老经验能避开大部分雷区，这大概就是所谓的“血泪经验”。希望这篇笔记能帮你在接华为SDK时少走一段弯路，把时间省下来放在自己的业务上。

本文还有配套的精品资源，点击获取