1. 先画三张业务地图
所有 NFC 业务,本质只有三种形态:
① 读卡(Reader / Polling)
手机 = 读头,外部 = 标签/卡片
典型:巡检打卡、资产盘点、防伪溯源、耗材识别、标签量产写号
② 卡模拟(Card Emulation / Listening)
手机 = 卡片,外部 = 读头/闸机/POS
典型:门禁、会员卡、园区一卡通、票务、车钥匙
③ 双向(P2P / 读写器互通)
手机 ↔ 手机 / 手机 ↔ 设备
典型:配网传参、产线写号(⚠️ Beam 已在 Android 14 移除)
再叠加一个维度:频段。
| 业务诉求 | 频段 | Android 原生能否覆盖 | 方案 |
|---|---|---|---|
| 工牌/门禁/公交 | 13.56MHz | ✅ | 原生 NFC |
| 仓储托盘/服装吊牌 | UHF 900MHz | ❌ | 外接 UHF 模块(串口/BLE) |
| 老小区门禁、动物耳标 | LF 125kHz | ❌ | 外接 LF 读头 / 引导换卡 |
| 远距离资产盘点(>10cm) | HF 15693 | ⚠️ 部分机型 | 优先 NfcV,做好降级 |
这一格表是需求评审阶段就该拍死的东西。等到开发完发现"客户要读 UHF 标签",返工成本极高。
2. 逐模块业务构想 × 坑
2.1 API 层:把"能力探测"做成基础设施
业务构想:做一个 NfcCapability,在任何业务开始前先探明"这台机器到底能干什么",输出一张能力矩阵,驱动后续 UI 与降级策略。
data class NfcCapability(
val hasNfc: Boolean, // 硬件是否存在
val enabled: Boolean, // 用户是否打开
val hceSupported: Boolean, // 是否支持卡模拟
val secureNfc: Boolean, // 是否支持 Secure NFC(防中继)
val techs: Set<String> // 探测到的可用技术
)
探测的坑:android.nfc 没有 getSupportedTechList() 这种 API。唯一可靠的办法是用一张已知的测试卡实际读一次,记录 tag.techList。所以工程上要区分"静态能力"(HCE 是否声明、Secure NFC 是否支持)和"动态能力"(实测技术位)。
另一个坑:API 层现在会随 APEX 更新(Android 16 起 framework-nfc.jar 独立下发)。不要用 SDK_INT 推断 NFC 行为,用 PackageManager.hasSystemFeature(PackageManager.FEATURE_NFC_HOST_CARD_EMULATION) 这类特性开关。
2.2 服务层:把状态机当成业务状态来用
业务构想:NFC 开关是异步的,把"开卡引导"做成一个可恢复的流程。
// 推荐:监听状态广播,而不是假设 enable() 成功
val filter = IntentFilter(NfcAdapter.ACTION_ADAPTER_STATE_CHANGED)
val receiver = object : BroadcastReceiver() {
override fun onReceive(ctx: Context, intent: Intent) {
when (intent.getIntExtra(NfcAdapter.EXTRA_ADAPTER_STATE, -1)) {
NfcAdapter.STATE_ON -> startReading()
NfcAdapter.STATE_TURNING_ON -> showLoading()
NfcAdapter.STATE_OFF -> showGuide()
}
}
}
坑:ACTION_ADAPTER_STATE_CHANGED 在部分 ROM 上会被节流或延迟;STATE_TURNING_ON 可能停留很久(固件初始化慢)。工程上要给超时兜底(比如 5 秒后仍然 TURNING_ON 就提示"设备 NFC 异常,请重启")。
业务上可以做的一件聪明事:把 applyRouting 的语义映射成业务语言——"屏幕亮且应用在前台"时打开轮询+"屏幕灭"时只保留卡模拟路由。这是省电与体验的最佳平衡点,也解释了为什么"灭屏刷不了门禁"通常是配置问题而不是硬件问题。
2.3 派发层:治理"应用劫持"与"选择器弹窗"
业务构想:多应用抢同一张卡,是政企项目最常见的问题(比如钉钉、企业微信、自家 App 都想处理工牌)。
治理手段按优先级:
- 优先用
enableReaderMode/enableForegroundDispatch:前台应用直接拿走,不参与系统级竞争; - AAR(Android Application Record):在标签里写入自己的包名,保证只有自己能拉起;
ACTION_TECH_DISCOVERED+ 精确tech-list:缩小匹配面,减少选择器;- 避免
ACTION_TAG_DISCOVERED:它是兜底 Action,谁都能注册,已在 Android 17(API 37)废弃,新项目一律不要用。
<!-- tech-list 要精确到你真正需要的最小集合 -->
<resources xmlns:xliff="urn:oasis:names:tc:xliff:document:1.2">
<tech-list>
<tech>android.nfc.tech.NfcA</tech>
<tech>android.nfc.tech.IsoDep</tech>
</tech-list>
</resources>
坑:tech-list 的语义是"同时具备",不是"任一具备"。写多了匹配不上,写少了被别人抢。
2.4 技术对象层:标签量产写号与资产盘点
业务构想 A:产线批量写号 一张标签写"型号 + 批次 + 序列号 + HMAC 签名",产线工人连续贴卡,要求 300ms 内出结果。
业务构想 B:资产盘点
用 NfcV(15693)做远距离盘点,一次性走完整货架。
关键代码:带重试的安全写入
fun writeNdef(tag: Tag, message: NdefMessage, retries: Int = 3): Boolean {
repeat(retries) { attempt ->
var ndef: Ndef? = null
try {
ndef = Ndef.get(tag) ?: return false
ndef.connect() // 注意:必须先 connect
if (!ndef.isWritable) return false
if (message.toByteArray().size > ndef.maxSize) return false
ndef.writeNdefMessage(message)
return true
} catch (e: TagLostException) {
// RF 场被重配或卡移开,退避后重试
Thread.sleep(50L * (attempt + 1))
} catch (e: IOException) {
return false
} finally {
runCatching { ndef?.close() }
}
}
return false
}
坑清单:
| 坑 | 现象 | 处理 |
|---|---|---|
maxSize 是"当前可用",不是"总容量" | 写入超限抛 IOException | 写前校验,留 8 字节余量 |
| 写一半移开卡 | 标签变成"半损坏",既非 NDEF 也非可格式化 | 用 NdefFormatable 兜底格式化 |
MifareClassic 扇区密钥 | 认证返回 false | 该机型可能只支持透传,不支持认证,需厂商确认 |
缓存了 Tag 对象 | 第二次操作必失败 | 每次回调都重新 getTag() |
一个省钱的设计:把"写号"和"验签"拆开。写号只写明文 + 签名,验签在服务端做。这样即使标签被复制,没有后端签名校验也无法伪造业务。
2.5 HCE 模块:门禁/会员/票务的正确姿势
业务构想:把"手机当工牌",AID 与后端约定,APDU 只做三件事——SELECT、读卡号、读签名。
class MyApduService : HostApduService() {
override fun processCommandApdu(apdu: ByteArray, extras: Bundle?): ByteArray {
// 1) SELECT AID: 00 A4 04 00 Lc AID
if (apdu.size >= 4 && apdu[1] == 0xA4.toByte() && apdu[2] == 0x04.toByte()) {
return SELECT_OK_SW // 90 00
}
// 2) 读卡号: 约定私有指令 80 CA 00 00
if (apdu.size >= 4 && apdu[1] == 0xCA.toByte()) {
return buildCardNo() + SELECT_OK_SW
}
return UNKNOWN_CMD_SW // 6D 00
}
override fun onDeactivated(reason: Int) {
// reason: LINK_LOST / DESELECTED —— 用来清理会话状态
}
companion object {
private val SELECT_OK_SW = byteArrayOf(0x90.toByte(), 0x00)
private val UNKNOWN_CMD_SW = byteArrayOf(0x6D, 0x00)
}
}
必须知道的四条约束:
- 响应有超时(通常几百毫秒)。
processCommandApdu里绝对不能做网络/数据库请求,只能读内存。需要联机就把数据提前缓存好。 - APDU 有长度上限。超长响应要做分片,靠
00 C0 00 00 Le(GET RESPONSE)续传,状态字用61 XX告诉读卡器还有多少字节。 onDeactivated一定会来,但不保证顺序;不要在这里做重活。- AID 冲突静默失败。两个 App 注册同一 AID,落选者完全收不到回调,日志里也没有明显报错。排查时先
adb shell dumpsys nfc看路由表。
调试命令(非常有用,建议收藏):
# 查看当前 NFC 状态、AID 路由、HCE 服务
adb shell dumpsys nfc
# 看 NFC 相关日志
adb logcat -s NfcService:N NfcDispatcher:N HostEmulationManager:N NativeNfcManager:N nfc_ncif:N
2.6 底层/外设模块:把 LF/UHF 抽象成统一接口
业务构想:客户既要刷手机(13.56MHz),又要盘 UHF 托盘。最干净的做法不是"两个 App",而是统一标签抽象:
interface TagSource {
val name: String
fun start(onTag: (RawTag) -> Unit)
fun stop()
}
data class RawTag(
val id: String, // 统一后的标识
val band: Band, // HF_13M56 / UHF_900M / LF_125K
val payload: ByteArray?,
val rssi: Int? = null
)
class NfcTagSource(...) : TagSource { /* NfcAdapter + ReaderMode */ }
class UhfTagSource(...) : TagSource { /* 串口/BLE UHF 模块 */ }
上层业务只依赖 TagSource,band 决定后续解析策略(NDEF / EPC Gen2 / EM4100)。这样换硬件不动业务代码,也天然满足了"高中低频统一"的产品诉求。
坑:外接模块的时钟与手机 NFC 会互相干扰。UHF 模块发射时优先暂停 NFC 轮询,否则两边都读不到。这是车载/手持机项目的高频问题。
2.7 安全模块:Secure NFC 与中继攻击
业务构想:门禁/支付类业务要防"中继攻击"(一个人拿着读卡器,另一个人拿着手机在远处)。
手段:NfcAdapter.isSecureNfcSupported() / enableSecureNfc(true)(Android 9+,依赖 NXP 芯片能力)。开启后卡模拟被限制在极近距离,中继基本失效。这是硬件级能力,不支持就是没有,不要试图用软件绕。
3. 版本兼容:一张表 + 一段代码
3.1 行为变更矩阵
| 版本 | API | NFC 相关变更 | 影响与对策 |
|---|---|---|---|
| 4.4 | 19 | 引入 HCE(HostApduService + AID 路由) | HCE 基线,之前的机器只能用 eSE |
| 9 | 28 | isSecureNfcSupported() / enableSecureNfc() | 先判断支持再加开关 |
| 10 | 29 | 后台 Activity 启动限制;普通应用无法 enable()/disable() | Intent 派发必须前台;开关只能跳设置页 |
| 12 | 31 | PendingIntent 可变性必须显式声明 | 前台派发的 PendingIntent 记得 FLAG_IMMUTABLE |
| 13 | 33 | NfcFrameworkInitializer 注册服务 | API 层开始模块化,不要靠版本号猜行为 |
| 14 | 34 | Android Beam 正式移除 | P2P 方案全部下线,改 BLE/QR |
| 16 | 36 | NFC 迁入 Mainline APEX com.android.nfcservices;http/https 的 NDEF URI 改为触发 ACTION_VIEW | 网址标签的 Intent Filter 要兼容 ACTION_VIEW |
| 17 | 37 | ACTION_TAG_DISCOVERED 废弃;targetSdk > 36 的 Activity 接收 NFC Intent 需声明 android.permission.DISPATCH_NFC_MESSAGE;网址标签改为"打开链接"通知,需用户点击 | 迁移到 NDEF/TECH;清单补权限;不要假设贴卡即跳转 |
上表中 16/17 的变更来自 AOSP 与 Android 官方文档的现行行为说明。厂商 ROM 落地节奏不一,必须实测。
3.2 兼容写法:一份清单 + 一段代码
<!-- AndroidManifest.xml -->
<uses-permission android:name="android.permission.NFC" />
<uses-feature android:name="android.hardware.nfc" android:required="false" />
<activity
android:name=".TagActivity"
android:exported="true"
android:permission="android.permission.DISPATCH_NFC_MESSAGE">
<!-- 注意:该权限从 Android 17 起成为必需;老版本声明无副作用 -->
<intent-filter>
<action android:name="android.nfc.action.NDEF_DISCOVERED" />
<category android:name="android.intent.category.DEFAULT" />
<data android:scheme="https" android:host="your.domain" />
</intent-filter>
</activity>
object NfcCompat {
/** 是否具备基础 NFC 能力(硬件 + 可用) */
fun isAvailable(ctx: Context): Boolean {
val am = ctx.getSystemService(Context.NFC_SERVICE) as? NfcManager
return am?.defaultAdapter != null
}
/** 是否支持 HCE(特性开关,比版本号可靠) */
fun supportsHce(ctx: Context): Boolean =
ctx.packageManager.hasSystemFeature(
PackageManager.FEATURE_NFC_HOST_CARD_EMULATION)
/** 是否支持 Secure NFC(硬件相关) */
fun supportsSecureNfc(adapter: NfcAdapter): Boolean =
runCatching { adapter.isSecureNfcSupported }.getOrDefault(false)
/** 统一的读卡入口:ReaderMode 优先级最高,不参与系统级 Intent 竞争 */
fun startReading(activity: Activity, onTag: (Tag) -> Unit) {
val adapter = NfcAdapter.getDefaultAdapter(activity) ?: return
adapter.enableReaderMode(
activity,
{ tag -> onTag(tag) },
NfcAdapter.FLAG_READER_NFC_A or
NfcAdapter.FLAG_READER_NFC_B or
NfcAdapter.FLAG_READER_NFC_V or
NfcAdapter.FLAG_READER_SKIP_NDEF_CHECK,
null
)
}
/** 必须成对调用,否则会一直占用 NFC 前台 */
fun stopReading(activity: Activity) {
NfcAdapter.getDefaultAdapter(activity)?.disableReaderMode(activity)
}
}
三条硬经验:
FLAG_READER_SKIP_NDEF_CHECK要按需加。加了快,但拿不到EXTRA_NDEF_MESSAGES,需要自己读;不加则框架会先做一次 NDEF 探测,慢但省事。ReaderMode用onResume开、onPause关。忘了关会导致退出应用后 NFC 仍被占用,甚至耗电异常投诉。- 不要同时用 ReaderMode 和 ForegroundDispatch。两者都会争抢前台优先级,行为不确定。
4. 厂商兼容:差异到底从哪来
4.1 芯片与能力
| 芯片平台 | 常见机型档位 | 关键差异 |
|---|---|---|
| NXP PN5xx / SN100 系列 | 主流旗舰、大量国产机 | MIFARE Classic、Secure NFC 支持最好 |
| 高通 NQ 系列 | 部分旗舰 | eSE/UICC 路由能力强,MIFARE 视授权 |
| 三星 / ST 等 | 韩版、部分中端 | FeliCa(日版)、特定路由策略 |
| 国产中低端方案 | 千元机 | 常裁剪 MifareClassic、NfcV,甚至只保留 NDEF |
4.2 五个高频差异点
- MIFARE Classic:需要 NXP 芯片 + 授权。非 NXP 平台基本没有,
techList里干脆不出现。 - NfcV / ISO 15693:部分机型默认关闭轮询位,需要在设置或配置文件里打开。
- FeliCa(NfcF):仅日版机型提供,国行普遍缺失。
- eSE / UICC 路由:金融、运营商业务依赖,需要系统签名或厂商白名单,普通 App 无法直接访问。
- 灭屏卡模拟:由
RF_SET_LISTEN_MODE_ROUTING_CMD的电源状态位决定,各家策略不同(省电优先 or 体验优先)。
4.3 兼容策略:探测 + 降级 + 声明
① 探测:静态特性(PackageManager.hasSystemFeature)+ 动态实测(贴卡看 techList)
② 降级:技术缺失时切换到备用链路(NfcA 透传 / 二维码 / 手输编号)
③ 声明:把"支持的机型清单"写进合同与隐私政策,而不是写进代码注释
一个实用的降级表:
| 能力缺失 | 降级方案 |
|---|---|
无 MifareClassic | 用 NfcA 读 UID + 服务端映射 |
无 NfcV | 改用 14443A 标签重新发卡 |
| 无 HCE | 引导使用实体卡 / 动态二维码 |
| 无 Secure NFC | 缩短读卡距离要求 + 后端风控 |
4.4 配置文件在哪
排障时如果怀疑是 RF 参数问题,先确认这几类文件:
/vendor/etc/libnfc-nci.conf # 通用 NCI 配置
/vendor/etc/libnfc-nxp.conf # NXP 专有 RF 参数
/vendor/etc/libnfc-brcm.conf # 部分平台
/vendor/etc/nfc_nci_<vendor>.conf # 厂商自定义
这些文件属于 vendor 分区,应用层读不到(SELinux 限制)。所以"读不到某类卡"的最终结论通常是:带上日志找厂商,要求打开对应轮询位。这也是为什么 NFC 项目立项时就要把"厂商支持承诺"写进合同。
5. 排障手册:症状 → 层 → 手段
| 症状 | 定位层 | 首选手段 |
|---|---|---|
| 开关打不开,一直 TURNING_ON | HAL / 固件 / 供电 | logcat -s nfc_ncif,看 CORE_RESET 是否超时 |
| 能开但一张卡都读不到 | RF_DISCOVER_CMD / 天线 | 换已知好卡交叉验证,对比 dumpsys nfc |
| 只能读某类卡 | 技术位 / 固件 | 看 techList,对照芯片能力表 |
| 能读但 App 收不到 Intent | 派发 / 后台限制 / 权限 | 改前台派发,检查 exported 与 DISPATCH_NFC_MESSAGE |
偶发 TagLostException | RF 重配 / 场强 | 加退避重试,避免读卡中途切前后台 |
| HCE 无回调 | AID 路由 / 电源状态 | dumpsys nfc 看路由表,检查 AID 大写与 category |
| 灭屏刷不了 | 路由电源位 | 要求厂商放开灭屏 host 路由 |
| 读卡距离特别近 | 天线 / 手机壳 / 金属 | 换位置、去壳、避开摄像头模组 |
日志关键词(记下来能省很多时间):
RF_DISCOVER / RF_INTF_ACTIVATED / RF_DEACTIVATE # 发现链路
CORE_RESET / CORE_INIT # 初始化
SET_LISTEN_MODE_ROUTING # AID 路由
HostEmulationManager # HCE 会话
TagLostException / transceive failed # 数据交换
6. 上线检查清单
能力与权限
-
uses-feature android.hardware.nfc设为required="false",无 NFC 设备可安装 - 启动时做能力探测,缺失时给出明确文案而非崩溃
- HCE 用
FEATURE_NFC_HOST_CARD_EMULATION判断,不用版本号 - Android 17+ 的 Activity 已声明
android.permission.DISPATCH_NFC_MESSAGE
读卡链路
-
ReaderMode在onResume/onPause成对开关 - 不缓存
Tag,每次回调重新获取 -
transceive有退避重试(≥3 次) -
tech-list精确到最小集合,不使用ACTION_TAG_DISCOVERED - 网址类标签同时兼容
ACTION_NDEF_DISCOVERED与ACTION_VIEW
HCE 链路
- AID 全大写、偶数长度、已在后端备案
-
processCommandApdu内无阻塞操作,超时可控 - 长响应实现
61 XX+GET RESPONSE分片 -
onDeactivated正确清理会话状态 - 与其他应用 AID 冲突时有人工引导
兼容与体验
- 建立机型验证矩阵(至少覆盖 NXP / 高通 / 三星三类芯片)
- MIFARE / NfcV 缺失时走降级链路
- 失败提示可操作("请贴近感应区中央"而非"读取失败")
- 连续读卡做防抖(同一 UID 500ms 内不重复回调)
7. 结语
NFC 是个"上层简单、下层极深"的领域。Ndef.get(tag).connect() 这一行代码背后,是 NCI 报文、RF 路由、AID 表、电源状态、芯片授权五件事同时成立。
所以做 NFC 业务,真正要建立的能力不是"会调 API",而是三件事:
- 分层定位——出问题先判断在哪一层,别在应用层瞎改;
- 能力探测——不假设任何机型有什么,先测再说;
- 降级设计——任何单点能力都要有 B 方案。
把这三件事做进架构,NFC 就不再是"玄学",而是一个普通的、可测试的传感器。
标签建议:Android、NFC、架构、兼容性、源码分析