鸿蒙uni-app唤起：DeepLinking与AppLinking

鸿蒙专家

在鸿蒙开发中，应用间互相唤起是常见需求，比如跳转到微信支付、打开地图导航或启动自有应用。与Android/iOS类似，鸿蒙提供了两套方案：Deep Linking（自定义URI）和App Linking（基于HTTPS域名验证），分别对应URL Scheme和Universal Links。下面从配置到调用逐步说明，并附带参数获取与踩坑修复。

【方案对比】
Deep Linking使用自定义scheme（如hellouniapp://），配置简单，但华为浏览器唤起来时会弹出系统确认框，用户需要多点击一次，有一定流失率。App Linking需要HTTPS域名并在AGC后台开通，体验更好——不弹窗直接唤起，且应用未安装时会自动跳转应用商店。

【配置Deep Linking】
首先找到module.json5文件。在HBuilderX工程中，路径为harmony-configs/entry/src/main/module.json5；如果不存在，可从unpackage/dist/app-harmony目录复制产物中的module.json5。
在module.abilities[0].skills数组中追加新skill：

2. {
3.   "actions": ["ohos.want.action.viewData"],
4.   "uris": [
5.     {
6.       "scheme": "hellouniapp",
7.       "host": "router"
8.     }
9.   ]
10. }

复制代码

注意：actions固定不变，scheme自定义，host必填且不能为*。原有的skills[0]（应用启动配置）不要改动，仅追加新元素。
验证方法：在网页上放链接<a href="hellouniapp://router">唤起应用</a>，用华为浏览器打开点击，底部弹出系统确认提示。弹窗文案由系统控制，无法自定义。

【配置App Linking】
步骤更多但体验更好。首先在AGC后台（https://developer.huawei.com/consumer/cn/service/josp/agc/index.html）找到应用 → 增长 → App Linking，开启功能。
在落地页域名根目录部署.well-known/applinking.json文件，内容：

2. {
3.   "applinking": {
4.     "apps": [
5.       {
6.         "appIdentifier": "你的AppID"
7.       }
8.     ]
9.   }
10. }

复制代码

该文件必须可公网访问（注意nginx等服务器不要屏蔽.well-known路径）。然后在AGC后台创建应用链接并发布。最后在module.json5中追加新skill：

2. {
3.   "entities": ["entity.system.browsable"],
4.   "actions": ["ohos.want.action.viewData"],
5.   "uris": [
6.     {
7.       "scheme": "https",
8.       "host": "你的域名",
9.       "pathStartWith": "你的路径"
10.     }
11.   ],
12.   "domainVerify": true
13. }

复制代码

entities、actions、domainVerify固定；scheme必须是https；host与验证文件所在域名一致；pathStartWith指定路径前缀。

【在应用中唤起其他应用】
安装uts-openSchema插件（https://ext.dcloud.net.cn/plugin?id=17828），它封装了openSchema和canOpenURL。在module.json5的module节点下声明querySchemes数组，最多50个：

2. {
3.   "module": {
4.     "querySchemes": ["wechat", "hellouniapp"]
5.   }
6. }

复制代码

Deep Linking唤起示例：

2. import { openSchema, canOpenURL } from "@/uni_modules/uts-openSchema";
3. const canOpen = () => {
4.   if (canOpenURL("hellouniapp://router")) {
5.     openSchema("hellouniapp://router/path/1?v=2");
6.   }
7. };

复制代码

App Linking唤起更简单：

2. import { openSchema } from "@/uni_modules/uts-openSchema";
3. const openApp = () => {
4.   openSchema("https://你的域名/你的路径");
5. };

复制代码

注意，canOpenURL不支持App Linking的https scheme，直接返回false；App Linking场景下无需判断，直接调用openSchema即可，未安装时会自动跳转商店。

【唤起元服务】
如需从鸿蒙应用唤起元服务，使用openAtomicService：

2. import { common, AtomicServiceOptions } from '@kit.AbilityKit';
3. export const openAtomicService = () => {
4.   const appId = '你的鸿蒙元服务APPID';
5.   const options: AtomicServiceOptions = { displayId: 0 };
6.   return new Promise((resolve, reject) => {
7.     UTSHarmony.getUIAbilityContext()
8.       .openAtomicService(appId, options)
9.       .then((result: common.AbilityResult) => resolve(''))
10.       .catch((err: BusinessError) => reject(err.message));
11.   });
12. };

复制代码

【接收唤起参数】
无论是Deep Linking还是App Linking，传参后应用需要接收。冷启动（应用首次被唤起）时监听onAppAbilityCreate：

2. import { Want } from "@kit.AbilityKit";
3. UTSHarmony.onAppAbilityCreate((want: Want) => {
4.   let uri = want?.uri;
5.   // 此时通信通道尚未建立，延迟仅为演示，实际无需延迟
6.   setTimeout(() => { console.log("onCreate", uri); }, 1000);
7. });

复制代码

热启动（应用已在后台再次唤起）时监听onAppAbilityNewWant：

2. UTSHarmony.onAppAbilityNewWant((want: Want) => {
3.   console.log("onNewWant", want?.uri);
4. });

复制代码

在Vue页面中，可直接使用uni.getLaunchOptionsSync()获取参数，无需手动封装UTS插件。若想手动暴露，将接收到的参数通过插件暴露给Vue层即可。

【踩坑记录】
1. canOpenURL报错17700056：该错误表示要查询的scheme未在module.json5的module.querySchemes中声明。检查并添加对应scheme即可。
2. querySchemes不超过50个：鸿蒙对此有限制，需注意控制数量，若需唤起众多第三方应用建议合理规划。
3. module.json5合并时保留原内容：追加skills时不可覆盖skills[0]（应用启动配置），只能追加新索引；querySchemes也是追加而非覆盖。
4. .well-known/applinking.json必须可公网访问：部分服务器会屏蔽.well-known路径，需在nginx或相应Web服务器中开放。
5. Deep Linking弹窗文案不可控：华为浏览器的弹窗文案由系统决定，用户需确认一次，有一定流失率；对体验要求高的场景建议优先采用App Linking。

【验证环境】
uni-app 4.36+、HBuilderX 4.36+、DevEco Studio 5.0.3.400、HarmonyOS NEXT 5.0.0.29。

热心网友1

楼主讲解得很清晰，正好最近在接入鸿蒙的跳转功能，对Deep Linking和App Linking的区别有了更深入的了解。特别是App Linking的域名验证和AGC后台配置那部分，之前一直没搞清楚，现在终于知道怎么操作了。感谢分享！

热心网友1

感谢楼主的详细分享！这个对比和配置步骤讲得很清楚，尤其是Deep Linking的弹窗确认和App Linking的直接唤起体验差异，对实际选型很有帮助。想问一下，App Linking的域名验证文件如果部署在CDN上会不会有缓存或路径问题？另外，对于非HBuilderX工程手动配置module.json5时，还有哪些容易漏掉的细节？

热心网友1

感谢楼主的详细分享，非常实用！特别是App Linking部署.well-known文件和domainVerify配置的部分，之前踩过坑，看了这个彻底明白了。请问在uni-app中，如果同时支持Deep Linking和App Linking，skills数组里追加多个元素时有没有顺序要求？另外，canOpenURL不支持App Linking的https，那有没有办法在唤起前判断是否安装了目标应用呢？期待楼主进一步指点。