前言

说实话，我第一次听说 Deep Link 的时候还一脸懵——这不就是个 URL 跳转吗？直到做电商项目，产品经理来了一句"用户从微信点链接要直接跳到商品详情页"，我才发现这玩意儿真不是随便配个 scheme 就完事的。

Deep Link 配不好，用户点链接跳不到指定页面，白白的流量就浪费了。

今天把 Deep Link 和 App Linking 的配置到落地，一次性讲清楚。

Deep Link 到底是什么

说白了，Deep Link 就是通过 URI 把用户直接送到应用的某个页面。

传统的方式，用户点个链接，先打开浏览器，再引导下载 App，装完打开还得到首页自己找内容。Deep Link 直接一步到位：点链接 → 拉起 App → 跳到目标页面。

HarmonyOS 里有两套方案：

• Deep Linking：用自定义 scheme（比如myapp://），简单但安全性差
• App Linking：用 HTTPS 域名，有域名校验，更安全也更智能

划重点：App Linking 是 Deep Linking 的升级版，官方推荐用 App Linking。

scheme 配置：module.json5 里的关键代码

不管是 Deep Linking 还是 App Linking，一切从 module.json5 的配置开始。

Deep Linking 的配置长这样：

{ "module": { "abilities": [ { "name": "EntryAbility", "exported": true, "skills": [ { "entities": ["entity.system.browsable"], "actions": ["ohos.want.action.viewData"], "uris": [ { "scheme": "myshop", "host": "www.myshop.com", "path": "goods" } ] } ] } ] } }

关键代码讲解：

• entities必须包含entity.system.browsable，表示这个 Ability 可以被浏览器类 Intent 拉起
• actions必须包含ohos.want.action.viewData，声明要处理"查看数据"的动作
• uris里scheme是你自定义的协议名，host是域名，path是路径限定

注意：scheme用自定义的就行，但不能跟系统保留的冲突（比如http、https、file这些别碰）。

如果用 App Linking，scheme 必须改成https，还要加domainVerify：

{ "uris": [ { "scheme": "https", "host": "www.myshop.com", "path": "goods", "domainVerify": true } ] }

• domainVerify: true是 App Linking 的灵魂——系统会校验你的域名所有权，只有域名主人才能声明这个链接归谁
• App Linking 的 scheme 强制https，不能自定义

App Linking 创建：从服务器到 AGC

App Linking 不像 Deep Linking 改改配置文件就行，它需要三步配置：服务器 → AGC → 客户端。

第一步：服务器放校验文件

在你的域名服务器根目录创建.well-known/applinking.json：

{"applinking":{"apps":[{"appIdentifier":"1234567","index":1}]}}

• appIdentifier是 AGC 上的 APP ID，在"项目设置 > 应用信息"里拿
• index是优先级，同一域名绑多个 App 时，index 大的优先被拉起
• 文件路径必须是https://你的域名/.well-known/applinking.json，不能换

第二步：AGC 配置

登录 AppGallery Connect → 增长 → App Linking → 应用链接 → 创建，填入你的域名。

注意：域名不带/，https://www.example.com/是错的，要写https://www.example.com。

AGC 会去你服务器拉那个 JSON 做校验，匹配就发布成功。发布后系统每 24 小时会重新拉取校验。

第三步就是上面写的 module.json5 配置，三步缺一不可。

跨应用跳转：代码实现

配置好之后，代码里怎么跳？用openLink就行：

import{common,OpenLinkOptions}from'@kit.AbilityKit';import{BusinessError}from'@kit.BasicServicesKit';functionjumpToGoods(context:common.UIAbilityContext,goodsId:string):void{letlink=`https://www.myshop.com/goods?action=showGoods&goodsId=${goodsId}`;letoptions:OpenLinkOptions={appLinkingOnly:true};try{context.openLink(link,options).then(()=>{console.info('App Linking 拉起成功');}).catch((err:BusinessError)=>{console.error(`拉起失败:${err.code},${err.message}`);});}catch(paramError){console.error(`参数错误:${paramError.code}`);}}

• appLinkingOnly: true表示只走 App Linking 通道，不走 Deep Linking
• 如果拉起失败，看错误码定位：1234567这种一般是配置问题，2234567一般是域名校验没过

处理入参：Intent 解析

跳过来了，目标页面得接住参数。在UIAbility的onCreate和onNewWant里解析：

import{AbilityConstant,UIAbility,Want}from'@kit.AbilityKit';import{url}from'@kit.ArkTS';exportdefaultclassEntryAbilityextendsUIAbility{onCreate(want:Want,launchParam:AbilityConstant.LaunchParam):void{this.handleLink(want);}onNewWant(want:Want,launchParam:AbilityConstant.LaunchParam):void{this.handleLink(want);}privatehandleLink(want:Want):void{leturi=want?.uri;if(!uri){return;}try{leturlObj=url.URL.parseURL(uri);letaction=urlObj.params.get('action');letgoodsId=urlObj.params.get('goodsId');if(action==='showGoods'&&goodsId){AppStorage.setOrCreate('goodsId',goodsId);}}catch(error){console.error(`链接解析失败:${error}`);}}}

关键代码讲解：

• onCreate处理冷启动（App 没在后台），onNewWant处理热启动（App 还活着），两个都要写
• url.URL.parseURL(uri)把 URI 解析成结构化对象，query 参数通过params.get()取
• 解析完用AppStorage.setOrCreate传给页面，页面侧用@StorageProp或@StorageLink接收

URI 格式规范

把 URI 的组成拆开看看：

module.json5 里path的匹配方式还有三种变体：

不配path的话，这个域名的所有链接都会被你的 App 拦截，慎用。

写在最后

Deep Link 这东西，配置繁琐但价值巨大。尤其做社交分享、短信营销、扫码直达这些场景，没 Deep Link 基本没法玩。

我的建议是：新项目直接上 App Linking，别用 Deep Linking 的自定义 scheme 了。scheme 冲突、安全性差、没装 App 就歇菜——这些坑 App Linking 全帮你避了。

唯一要耐住性子的是那个三步配置流程，服务器 → AGC → 客户端，一步都不能跳。配完之后记得用hdc shell hidumper -s AppDomainVerifyManager查一下校验状态，success了才算真正生效。