企业官网建设流程全解析

做鸿蒙开发到现在，我上手过不少“看起来炫酷”的功能，但要说最能体现鸿蒙生态特色的，还得是碰一碰加好友。手机碰一下对方的NFC标签，不用扫码、不用搜ID，直接拉起应用进入加好友确认页，这种体验放到产品里是真的加分。这篇就把我做碰一碰加好友功能时踩过的坑、理清的链路、沉淀下来的代码套路全部写出来，适合刚装好DevEco Studio、想给应用加NFC入口的开发者参考。不管你之前有没有写过NFC相关逻辑，只要按着这里的步骤走，基本都能跑通。

1. 整体设计：碰一碰加好友到底是怎么跑通的？

1.1 先搞明白碰一碰的本质：系统级的“暗号匹配”

碰一碰看起来像魔法，本质却很简单：NFC标签里存了一段URL，手机读取后把这段URL交给系统，系统根据URL里的scheme、host、path找到能处理它的应用或元服务，然后拉起对应页面。

拿身边的东西来类比就是：NFC标签是钥匙，手机NFC芯片是锁孔，系统是门禁系统，你的应用是被闸机放行的那扇房间门。钥匙插进去，门禁判断“这钥匙能开301房间”，于是打开对应房门。整个过程走的不是蓝牙配对，也不依赖两台手机之间的直连，而是“标签 -> 系统 -> 应用”的单向通道。

这带来的第一个设计启示是：加好友功能不需要在两端手机之间做实时通信，NFC标签里完全可以只放一个发起方标识，真正的好友关系通过后端服务建立。这也让功能实现难度从“实时通信”降到了“参数传递”，对新手友好得多。

1.2 为什么用元服务而不是普通App

做碰一碰入口，第一选择应该是元服务（Atomic Service），而不是传统安装式App。原因有三：

• 免安装，碰一下就能进，链路最短。加好友场景讲究“快”，如果用户碰了标签还要先下载一个几十MB的App，体验直接就废了。
• 体积小，拉起速度快。元服务更轻，系统处理意图时的开销低，冷启动时间也更短。
• 适合低频刚需。好友添加不是高频操作，为它让用户装一个完整App不划算，元服务用完即走，符合场景诉求。

当然，如果你已经有一个成熟的App，也可以在主工程里增加对应的Ability来响应碰一碰。但从我实际体验来看，单独做一个元服务入口，开发和调试都更干净，也不会污染主应用的页面栈逻辑。

1.3 把功能拆成三段链路来设计

我在动手写代码前，把碰一碰加好友拆成了三段链路，后面所有工作都是围着这三段展开的：

• 第一段：标签侧。NFC标签里写入一条带参数的URL，例如harmonyos://nfc/friend?uid=1001&invite=abc123。uid表示发起加好友的用户，invite是防误触的邀请码。
• 第二段：系统侧。手机读到URL后，系统解析并匹配应用在module.json5里声明的URI规则，拉起对应的Ability。这一步的关键是路由配置的scheme、host、path必须和标签里的URL完全对得上。
• 第三段：应用侧。拿到系统传递过来的Want参数，解析uid和invite，调后端接口发起好友请求，配合前端页面完成“确认添加”。

设计完这三段，你会发现整个功能的核心工作量其实集中在第二段和第三段，标签只是数据的载体。下面按这个链路逐步拆解。

2. 核心细节：NFC标签、路由配置与参数解析

2.1 NFC标签里到底应该存什么

很多第一次做碰一碰的开发者会犯一个错：想把好友的昵称、头像、手机号全塞进标签里。这是典型的“不会设计协议”。NFC标签存储空间极小，而且标签是一次性写入的静态数据，放太多东西既浪费空间，也没法应对数据变化。

我给的方案是：标签里只放一个短URL，业务参数全部放进URL的query里。这里有几个约束要记住：

• URL不要过长。普通便宜的NFC标签（比如NTAG213）只有144字节可用，一个带参数的短链完全够用，但如果你硬塞一长串json，可能直接写不进去。
• 不要在URL里放敏感信息。好友邀请本质上是个可公开的入口，如果有人顺手把标签内容读出来，他拿到的应该只是“邀请码+用户ID”，而不是手机号、社交账号这类隐私数据。
• 注意URL编码。如果参数里有中文、空格或者特殊符号，写入前必须做URL编码，否则系统解析时可能截断或乱码。

至于标签选型，不同容量的差异可以看这张表：

加好友场景下，NTAG213就绰绰有余了。实测下来，这类标签贴纸几毛钱一张，买一叠回来写废几张也不会心疼。

2.2 路由配置是“碰一碰”能不能拉起的命门

标签里写了URL，接下来要看系统凭什么把你的应用拉起来。答案在元服务的module.json5里。我们需要在abilities中声明一个skills，让系统知道“这个scheme、这个host、这个path应该交给我处理”。

这是一段可直接参考的配置：

{ "module": { "name": "entry", "type": "atomic-service", "abilities": [ { "name": "EntryAbility", "srcEntry": "./ets/entryability/EntryAbility.ets", "skills": [ { "actions": ["ohos.want.action.viewData"], "uris": [ { "scheme": "harmonyos", "host": "nfc", "path": "friend", "linkFeature": "NfcFriend" } ] } ] } ] } }

这里最容易被忽略的是匹配规则。系统做URI匹配时，是scheme、host、path三者同时生效的，有一个对不上就拉不起来。另外，actions里的ohos.want.action.viewData不能省，它表示这个Ability具备“查看数据”的能力，碰一碰拉起正是走的这条动作。

还有一个更高阶的配置项是linkFeature，它用来标记这个链接对应的业务场景。如果你打算让应用上架到华为应用市场里的碰一碰专区，需要把这个feature同步到AppGallery Connect后台；如果只是内测或者自用，可以先不管它，不影响本地拉起。

2.3 在Ability里拿到参数，并决定去哪一页

路由配置好之后，系统会把URL里的参数塞进Want对象传给你的Ability。解析逻辑写在EntryAbility里就行。我个人建议把参数解析抽成一个公共函数，因为碰一碰拉起时有两种路径：

• 新起Ability时，参数通过onCreate传入。
• 复用已存在的Ability时，参数通过onNewWant传入。

如果只写了其中一条，就会出现“第一次碰能拉起，第二次碰进去了却没反应”这种诡异问题。正确的做法是两个入口都做解析：

import { common, Want } from '@kit.AbilityKit'; async function parseAndGo(want: Want) { const params = want.parameters; const uid = params?.['uid'] as string ?? ''; const invite = params?.['invite'] as string ?? ''; // 跳转到好友确认页，把解析出来的参数传过去 this.context.getRouter().pushUrl({ url: 'pages/FriendApplyPage', params: { uid, invite } }); }

注意，want.parameters里的值通常是字符串，但也有可能被解析成数组，比如URL里出现?uid=1&uid=2这类重复参数。遇到这种情况时最好做一层防御性判断，取第一个值或直接抛错拒绝，别让脏数据进入业务流程。

2.4 UI层布局：用RelativeContainer和Tabs快速搭确认页

参数拿到了，接下来要给用户一个“确认添加好友”的界面。我用的布局组合是RelativeContainer加Tabs，这也是我在鸿蒙UI开发里用得比较顺手的组合。

RelativeContainer负责整体定位，好友头像放在左上，昵称和签名放在头像旁边，底部按钮区域固定对齐。Tabs则用来做“确认添加”和“暂不添加”两个动作面板，简单直接：

@Entry @Component struct FriendApplyPage { @State uid: string = ''; @State inviteCode: string = ''; build() { RelativeContainer() { // 好友信息区 Text(`用户ID: ${this.uid}`) .fontSize(20) .align(Alignment.TopStart) .margin({ left: 16, top: 24 }) // 操作区 Tabs() { TabContent() { Button('确认添加') .onClick(() => this.applyFriend()) }.tabBar('确认添加') TabContent() { Button('暂不添加') .onClick(() => this.cancel()) }.tabBar('暂不添加') } .align(Alignment.Bottom) .height(120) } .width('100%') .height('100%') } }

界面上别放太多花哨的东西。碰一碰场景下用户的目标非常明确：要么加好友，要么不加。一切UI都该围绕这两个动作设计，加好友成功后直接弹个Toast提示并返回即可。

3. 实操过程：从新建工程到真机碰一碰

3.1 环境准备：不只是装个DevEco Studio

开始写代码前，先把环境理清楚，省得后面一边写一边补课。

• DevEco Studio版本建议用5.0以上，HarmonyOS SDK选择API 12或更高。新版本对元服务模板和NFC相关能力支持更完善。
• 工程类型务必选择“Atomic Service（元服务）”，如果你建成了普通应用，后面在模块配置上会多绕不少路。
• 真机必须是支持NFC的华为设备。模拟器不支持NFC功能，这点没什么可妥协的，老老实实准备一台实体机。

另外建议把手机的“开发人员选项”和“USB调试”提前打开，后面装HAP包、抓日志都要靠它。

3.2 一步一步创建元服务工程

在DevEco Studio里新建工程时，直接选“Empty Ability”模板，语言用ArkTS。建好后按下面几步操作：

1. 先改module.json5，按照上一节的路由配置，把skills和uris声明填进去。
2. 新建一个FriendApplyPage页面，专门承担好友确认场景。
3. 在EntryAbility的onCreate和onNewWant里调用统一的参数解析方法。
4. 把应用默认的首页改成FriendApplyPage，或者让路由直接指向它。

这里有个很容易踩的坑：新手喜欢把页面跳转逻辑写在自定义组件里，然后发现无论怎么碰，页面都是空白。原因在于碰一碰拉起的目标是Ability，不是某个ArkUI页面，你必须在Ability层面拿到Want并完成跳转，而不是等页面自己去猜。

3.3 真机联调：把标签写进去，碰它

工程跑起来之后，进入到最让人兴奋的一步：写标签，碰手机。

写NFC标签我用的工具是手机上的“NFC Tools”类应用，选“添加NDEF记录 -> URL”，然后把测试URL填进去，比如https://your-domain.com/friend?uid=1001&invite=abc123。这里有个细节：标签里写https链接还是自定义scheme链接，取决于你的路由配置。系统碰一碰拉起时对标准URL支持更友好，但自定义scheme在纯内测场景下调试更方便。两种我都试过，最终线上用的是标准https链接加路径映射，稳定性和兼容性都更好。

测试时注意三点：

• 手机NFC感应区一般在摄像头附近，把标签贴上去要停留一秒左右，不要一碰就移开。
• 亮屏状态下读取成功率远高于息屏状态，调试时保持解锁。
• 每次改了代码，重装HAP包之后要先杀掉应用进程再碰标签，避免旧进程把Want吃掉。

装包命令也很简单，DevEco Studio直接点Run就会自动推送，或者手动用hdc安装：

hdc install entry-default-signed.hap

装好后打开系统的日志工具，能看到类似“Ability jumped by url”的日志，基本就说明系统侧已经识别成功。

4. 踩坑实录：常见问题与排查技巧

4.1 碰一碰完全没有反应，问题出在哪

这是最让人焦虑的情况，但排查路径其实很固定。第一步先确认手机NFC开关是否打开，很多华为手机默认NFC是关闭的。第二步看标签里是不是NDEF格式的URL记录，有些廉价标签出厂是空白的，你需要先用工具写入才能用。第三步检查你有没有把手机识别区对准标签，多试几次。

如果手机有反应，但弹出来的是“无法识别”或“打开浏览器”，那就说明系统没有匹配到你的应用。此时优先检查module.json5里的uris配置和标签URL是否严格一致，尤其是path。我遇到过一次host对、path多了一个斜杠，结果直接拉起失败，检查了半小时才发现。

4.2 能拉起应用，但页面参数是空的

能拉起说明路由通了，参数为空则是解析的问题。常见原因是URL里的参数值被URL编码过，比如uid=1001%20test，在Java层直接取值会拿到编码后的字符串，需要做一次解码。另一个原因是你注册了多个Ability，系统拉起的是其中一个没有解析逻辑的Ability，这种情况就要梳理页面的意图分发。

还有一个容易被忽视的坑：当Ability复用旧实例时，onNewWant并不会自动携带最新Want到达页面。如果你只在aboutToAppear里读了currentWant，就会拿到第一次启动时的旧参数。我的习惯是维护一个全局的“待处理Want”缓存，在Ability层解析后主动用路由参数传给目标页面，不让页面自己去读Want。

4.3 用户连续碰两次，系统发了两个重复请求

这是业务侧需要防范的典型问题。NFC碰一碰太快的话，用户可能还没看清界面，系统就又拉了一次，导致同一个好友请求被提交两次。解决方式有两个层面：

• 前端做防抖：在FriendApplyPage里增加一个@State submitting: boolean，按钮点击后立刻置为true，请求结束前不允许再次点击。
• 后端做幂等：好友请求带上inviteCode，服务端判断同一个邀请码只处理一次。

实测下来，前后端都加防护是最稳的，别只依赖某一侧。

4.4 碰一碰拉起后页面卡在加载页

这种情况多半是后端接口被异步回调卡住了。很多新手在onClick里await一个网络请求，但UI线程还没有更新状态，按钮也不显示loading。建议在发起请求前先切换loading状态，请求结束后再还原，同时用超时保护，避免后端长时间无响应把用户晾在页面上。

下面的表格是我整理的一份排查速查表，直接照着查可以省不少时间：

4.5 别忘了权限与合规自查

碰一碰涉及读取NFC标签能力，在HarmonyOS里需要在module.json5里声明ohos.permission.NFC_TAG之类的权限。但这个权限在运行时通常不会弹窗，安装包阶段就会生效，所以配置好后基本就能直接用。

更需要注意的是用户隐私合规。你的页面如果展示了好友昵称、头像等个人数据，接入正式环境前必须要有相应的隐私政策说明。碰一碰本身不采集用户敏感信息，但如果你的后端通过标签里的uid反查了手机号，那这层关系就要在用户协议里写清楚，避免合规风险。

最后再分享一点我的个人体会

我在实际项目里碰过几次“看起来没问题但就是不触发”的鬼情况，最后发现都是“旧进程持有旧Want”在作怪。所以我现在做碰一碰类的功能，一定会把参数解析逻辑写成纯函数，在Ability的onCreate和onNewWant里都调用，同时对每个参数做默认值兜底。这个小习惯帮我省掉了大量线上反馈，你如果从零开始做，建议直接把这个模式固化到代码模板里。另外，如果你想把这套能力做成通用入口，还可以考虑把碰一碰的标签参数扩展成携带不同的业务类型，比如加好友、加群、快捷登录，靠一个统一的路由分发来承接，扩展起来会顺手很多。