iOS NFC使用指南：如何使用React Native读取、写入NFC标签以及锁定这些标签

我同时提供了这两种格式，让用户自己进行选择，因为通过具体的数据对比，这些差异会比单纯的文字描述更加直观明了。

同样的联系信息，URL格式仅占17字节，而vCard格式则占184字节。这种差异实际上代表了两种完全不同的处理方式，因此用户需要自己来做出选择，而不是由系统替他们做出决定。

如何编码vCard

vCard其实只是文本而已。应用程序实际写入标签的内容就是这样的：

BEGIN:VCARD
VERSION:3.0
N:Doe;Jane;;;
FN:Jane Doe
ORG:Example Ltd
TITLE:Full-stack engineer
TEL;TYPE=CELL:+15550100
EMAIL;TYPE=INTERNET:jane@example.com
URL:https://example.com
END:VCARD

每行只包含一个字段：名称、冒号、值，最后再加上回车符和换行符。将这些内容组合起来，就能得到一个有效的vCard标签。

这种格式起源于20世纪90年代，不过其中有三条规则很容易被忽略或误解。因此，你的编码程序必须能够正确处理这三条规则。

1. 长行应按字节进行分割，而不是按字符。

任何长度超过75字节的行都必须被拆分，并在下一行继续显示，开头需要加上空格。虽然可以使用line.slice(0, 75)这种方法来截取前75个字节，但这种方法其实是按照字符数来计算的，因此如果某个字符串中包含多个字节长的字符，这种方法就会导致标签中的数据无效。正确的做法应该是按照代码点来遍历字符串，同时记录每个字节的长度。

2. 发送 `N`，并明确说明你只是在进行猜测。

看看那行 `N:`。vCard 3.0要求将名字拆分为 `家庭名;名字;附加信息;前缀;后缀` 这几部分，因此仅仅发送 `FN` 是不够的。对于中文和匈牙利语的名字、那些有两个姓氏的西班牙语名字，以及那些只使用一个名字的人来说，将显示名称拆分成这些部分实际上是一种猜测行为，而这种猜测往往是错误的。我会记录下这一猜测结果，并让进口工具实际显示的 `FN` 保持用户输入时的原样。

3. 将值中的每个分号都进行转义处理。

在那一行 `N:` 中，那些分号是用于表示结构信息的。如果某人的职位是“Engineer; Lagos”，如果直接将这一字符串写入数据中，就会导致一个字段被分割成两个部分，而进口工具会误将其余内容视为名字的一部分。因此，这些分号必须以 `Engineer\; Lagos` 的形式存在。

只要把这三点处理正确，整个编码程序就只需要大约170行代码来处理字符串相关操作，而且完全可以在不使用任何标签的情况下进行测试。

那个通过了所有测试的转义错误

第三条规则正是我遇到的最严重的错误所在。我的转义函数中有这样一行代码：

.replace(/;/g, '\;')   // ← 这行代码并没有对任何分号进行转义处理

vCard要求在值中的每个分号前面都必须加上一个反斜杠。`'\;'"` 看起来似乎是可以达到这个目的的，但实际上并非如此。JavaScript中并不存在 `\;` 这样的转义序列，因此它只会忽略掉反斜杠，直接返回普通的 `';'`。这样一来，这一行代码实际上就是将所有的分号都替换成了它们本身。

正确的解决方法应该是使用 `'\\\;'"`，这样第一个反斜杠就可以用来转义第二个反斜杠了。

后来情况变得更糟了。我为这个转义函数编写了一个测试用例，并期望它能够输出未经过转义的原始数据，因为我认为那一行代码是有效的。然而这个测试用例反而暴露了这个错误，也就是说，如果使用正确的代码，这个测试用例反而会失败。

后来我又写了第三个测试用例，试图通过 `not.toContain('N:')` 来判断某个字段是否不存在。但这个测试永远都不会通过，因为所有的vCard文件都是以 `BEGIN:VCARD` 开头的，而 `BEGIN:` 这一行也必定以 `N:` 结尾。

十分钟内就犯了三个错误，原因都在于对规则的理解有误。

如果先进行测试的话，我是不会犯这些错误的。因为我和测试代码都基于同一个假设：在处理字符串时确实需要对其进行转义处理。

在向标签写入数据之前，先确认一下它的属性

任何写入操作都会替换芯片中原有的数据，因此顺序非常重要：

1. 首先查询标签的属性：它是否可以被写入，其实际容量是多少？
2. 如果发现标签是只读的，或者容量太小，就应该立即停止写入操作。
3. 然后进行写入。
4> 写入完成后，再读取数据，确认它是否与之前发送的数据一致。

第二步才是确保数据安全的关键。如果在写入操作之前就发现标签无法被修改，就可以避免对标签造成任何破坏；而如果在写入操作进行中出现错误，至少也可以防止数据被部分地写进去。

步骤4的存在，正是因为那种报告了“操作成功”但实际上并未真正发生写入操作的情况，才是最糟糕的结果。需要在同一会话中重新进行读取操作，并且比较记录的内容，而不是原始的字节数据。实际上，某个标签在发送完全相同的数据时，其返回的信息格式可能与你发送时的格式不同。

这四个步骤都需要在同一个会话中完成，而不能分开进行。在iOS系统中，每个`requestTechnology`请求都会在用户面前弹出系统提示窗；因此如果将这四个步骤分开处理，就意味着需要弹出四个提示窗，并且用户需要进行四次点击才能完成同一个操作。而在Android系统中，系统并不会注意到这种差异——正是这种差异，使得在iOS平台上设计出来的界面看起来显得有些随意，直到你在其他平台上看到同样的设计时才会明白其中的原因。

在这一个界面中，你可以看到全部四个步骤：首先向标签发送请求，然后接收返回的数据并进行测量（而不是基于假设进行计算），接着执行写入操作，最后通过读取操作来确认数据是否确实被正确地存储了下来，而且每一字节的数据都得到了验证。

检查点： 使用`git checkout step-3-write`命令进入相关代码目录。使用配置文件编辑器进行设置，采用vCard格式进行编码，并在写入数据之前先检查所需的存储空间是否足够。

容量够吗？137字节，而不是144字节

在这个过程中，这个项目让我学到了很多东西。

NTAG213标签具有144字节的用户可用存储空间。这个数值在所有的技术规格说明中都有明确记载：总共36页，每页占4字节，也就是第4页到第39页。我正是根据这个数值来设计容量检查机制的。

一个普通的名片所包含的信息（姓名、头衔、公司信息、电话号码、电子邮件地址以及一个链接）大约需要184字节的文本空间；而当这些信息被封装成NDEF格式的消息后，总大小会变为202字节，这就是前面提到的那个数值。

因此，普通的名片是无法存储在普通的NTAG213标签上的。这是一个真实存在的产品限制，并非软件故障；应用程序必须明确说明这一点，而不是让用户遇到莫名其妙的问题。

不过我的计算结果是错误的。当我最终去测量一个真正的NTAG213标签的容量时，发现它实际上只有137字节的存储空间。

144字节这个数值指的是芯片的用户可用存储空间；而对于开发者来说，真正重要的数值是NDEF消息的最大长度。由于标签本身会进行一些额外的数据存储处理，所以实际可用的存储空间要比144字节小。我之前的计算结果多算了7字节，这就导致我认为名片可以存储在标签上，但实际上是不行的。

这个错误还隐藏了另一个问题：标签并不会直接存储你发送的消息，而是会用一些额外的字节来对消息进行格式化处理，这种格式化信息被称为TLV格式，用于说明数据的类型、长度和实际内容。我在计算存储容量的时候，把这些格式化字节也算进去了，因此导致了重复计算。实际上，所有被用来计算存储容量的数值（比如Android系统的`getMaxSize()`方法返回的值、iOS系统的状态查询结果，以及一些合理的假设值）都已经包含了这些格式化字节，也就是说，这些数值其实已经代表了“排除格式化信息后的消息大小”了。

更大的错误

比这个数字本身更糟糕的是，我对这个平台的判断是错误的。

因为iOS的getTag()函数只返回{ id, tech }这两个字段，所以我得出了“iOS无法检测标签的实际容量”这个结论。我在代码中、在平台对比分析中，以及应用程序的用户界面中都写了这一点，并且还计划开发一个专门的模块来弥补这一缺陷。最终，这个模块也被成功集成到了应用程序中：

那条用斜体字写的说明实际上是一个错误的结论，但却被当作事实呈现给了用户。上面那张提示卡片中的所有数据其实都是基于这个错误假设得出的。

这种判断是错误的。ndefHandler.getNdefStatus()函数——也就是CoreNFC的queryNDEFStatus方法——在当前会话进行过程中，就能同时返回标签的读写状态以及其实际容量。其实，这个功能早在几周前我就已经掌握了。

让我们来看看这个错误的形成过程：

• 我的错误认知：认为只有一个函数getTag()能够获取标签信息，而这个函数并不提供标签的容量信息。这是事实吗？

• 我的错误结论：因此我认为iOS无法告诉用户标签能存储多少字节的数据。但这种推理是错误的。

一个函数没有回答某个问题，并不意味着整个平台都无法提供这个信息。就好比我尝试打开一扇门，发现它锁着，就认为根本无法进入这栋建筑一样。

对于这个项目，我的原则是：在任何情况下，只有当我在实际设备上验证过某个结论后，才会将其记录下来作为事实。但在测量数据时，我遵循了这个原则；而在根据测量结果得出结论时，我却忘记了这一原则。

一个未经验证的结论，与一个未经核实的数字一样危险，而且更难以被发现，因为这样的结论会借助那些经过验证的数据来增加自身的可信度。

所以现在，应用程序会在询问标签信息后，只有在没有收到任何回应的情况下，才会假设标签的容量为默认值。每当出现这种假设时，应用程序都会明确说明这一点：

该标签容量过大。应为137字节，但实际上有202字节，超出65字节的限制。请缩短数据格式或使用链接。

目前还没有标签返回其实际容量信息，因此这里默认使用NTAG213类型标签。当您向标签写入数据时，标签会自动显示其真实容量。

每当数值是经过假设得出的时候，都会出现“应为……”这样的字样。这种表述方式其实是故意设计出来的：一旦应用程序不再强调这一点，读者就会误以为这些数值确实是经过实际测量得出的。

下面是当标签已经返回了其容量信息后，同样的提示卡片会显示什么内容：

“wrong-tag”这条规则是整个系统正常运行的基础。如果接受任何标签都可以使用这个功能，那么这个过程就变成了“拥有一个贴纸”，而不是“去找到那个贴纸所在的地方”。

对标签信息进行规范化处理的重要性远超人们的想象。同一个物理芯片，通过不同的读取方式可能会被识别为04C4FC91DF2A81或04:c4:fc:91:df:2a:81。如果将这些不同的识别结果视为不同的标签，就会导致严重的错误：你手中拿着的正确芯片，也可能因为读取方式的不同而被系统拒绝识别。

那个绿色按钮并不会终止任何操作，它只是启动扫描流程，而真正结束会话的是这个扫描过程本身。在它的下方，以较为低调的方式显示着通往机场的出口信息。

2. 计时器是向上计时的，永远不会倒计时。

如果选择倒计时，那么你就可以坐在沙发上等待会话结束；无论你是否采取了任何行动，会话都会自动终止。而向上计时的方式则能真实反映实际发生的情况。

3>会话中断时，系统会进行记录，而无法阻止这种情况的发生。

这就是这个设计的有趣之处所在。

它实际上能够强制执行什么

它无法屏蔽TikTok。在iOS系统中，要真正禁止某个应用程序的运行，就需要使用com.apple.developer.family-controls这个权限设置。这是一个由苹果公司单独审核并仅授予那些以保障用户数字健康或提供家长控制功能为目的的应用程序的特权；即便是用于测试环境的TestFlight也需要这个权限。Focoos应用程序拥有这个权限，但如果你按照本手册的操作来进行设置，那么你的应用程序很可能没有这个权限。因此，如果有人承诺可以屏蔽某些应用，那肯定是一个无法兑现的承诺。

所以，它实际上能够强制执行的只有一件事：对会话记录的保存。

虽然提供了一个“逃生通道”，但如果你在机场真的遇到了麻烦，第一次使用这个功能时，就会留下永久性的痕迹——系统会记录这次会话是提前结束的。这个痕迹是永久存在的，每次你打开这个应用程序时都会看到它。

而“会话记录本身”才是真正需要被保护的对象，因为这是这个应用程序中唯一值得用户自己加以保护的资料。这种保护机制是不对称的：

如果你在晚上11点坐在沙发上选择清除记录，那么实际上什么记录都不会被删除。而清除这些记录所付出的代价，恰恰就是当初创建这些记录时所花费的时间和精力。

无论你是否有过专注会话的经历，“提前结束”这一栏都会被显示出来，这就是这个设计的意义所在。这一栏会永久地出现在界面中，因此在使用“逃生通道”之前，你就会清楚地知道使用它所带来的后果。而“清除记录”这个选项则位于界面的最下方，是这个应用程序中唯一需要特定标签才能执行的操作。

还有两个看似微不足道的设置，实际上却非常重要。正在进行的会话在重新启动后仍然会继续存在，因为这些会话数据会被保留下来；因此，强制退出应用程序并不能真正逃避这些规则。能够结束会话的唯一方法就是使用特定的标签或“逃生通道”，而其中任何一种方法都会留下痕迹。

即使会话中断，这些时间仍然会被计入总专注时长中，因为在你真正失去专注状态之前，你确实处于专注状态。将这类时间重置为零既不公平，也不准确。

相比之下，“连续专注时长”机制的设计更为严格：一旦会有会话中断，该时长就会被重置为零。一个不可能丢失的数值其实没有必要被记录下来。

编译器发现的两个React漏洞

这两个漏洞都属于React通用层面的问题，并非与NFC功能相关，而且它们都不是我发现的。React编译器通过eslint-plugin-react-hooks提供了相应的代码检查规则，这些规则能够标记出那些无法被安全优化的代码片段，而这两个漏洞就是通过这些规则被检测出来的。你并不一定需要使用React编译器才能遇到这些问题。

const [now, setNow] = useState(Date.now()); // ✗ 在渲染过程中使用这个函数会导致代码不纯

这就是purity规则所针对的情况：Date.now()与Math.random()、crypto.randomUUID()一样，都被归类为“对于相同的输入会返回不同结果的API”。在渲染过程中不断获取当前时间会导致组件每次渲染时都产生不同的输出结果。

一个显而易见的解决方法是在效应函数的开头设置这个时间值，但这样做又会违反另一个规则。set-state-in-effect明确指出：“在效应函数内部立即设置状态会迫使React重新开始整个渲染流程”，从而导致“不必要的额外渲染”。

purity规则推荐的解决方案是使用延迟初始化的方式，即useState(() => Date.now())。对于一个在组件挂载后才开始运行的计时器来说，这种实现方式确实是正确的。因为计时器并不是在组件挂载时就开始运行的，而是在某个会话开始时才开始计时，所以如果在挂载时就获取当前时间，得到的结果就会失效；而使用延迟初始化的方式就可以避免这个问题。

将初始值设置为0既符合“代码纯度”的要求，也能作为一个有效的提示信号：当值为假时，说明“还没有开始计时”，因此界面上就不会显示无意义的数值。

那种既正确又简洁的实现方式是将计时操作延迟到某个特定的时机执行：useEffect(() => { if (!session) return; // 延迟执行而不是立即调用：在效应函数内部直接使用setState会导致额外的渲染操作； // 而通过设置0毫秒的超时时间，可以让这个操作被推迟到下一个任务执行， // 这样就可以避免不必要的额外渲染。 const first = setTimeout(() => setNow(Date.now()), 0); const id = setInterval(() => setNow(Date.now()), 1000); return () => { clearTimeout(first); clearInterval(id); }; }, [session]);

为什么你的NFC锁并不安全

“专注时长”功能会使用标签的标识符作为键值对来进行存储。大多数NFC“锁屏”应用也是采用这种方式。有必要明确说明这种做法的优缺点是什么。

四个让我每晚都要花几个小时去解决的麻烦问题

问题1：系统界面会无缘无故地消失

问题2：你的扫描结果会被会话结束操作覆盖

为了解决这个问题，需要确保某个操作只执行一次。即：一个锁，一个地方：

private func settle(resolving value: [String: Any]) {
  lock.lock()
  defer { lock.unlock() }

  guard let promise else { return }   // 如果已经完成解析，则什么都不做
  selfpromise = nil
  promise.resolve(value)
}

由于这里存在四个嵌套的异步操作步骤以及五条可能导致失败的路径，因此必须严格执行这一规则，而不能仅凭假设来处理问题。

问题3：你已经拥有的某个权限实际上“缺少所需的权限”

你的权限配置中包含了NDEF和TAG，但会话仍然无法启动。

造成这种问题的原因是轮询选项——也就是你在打开会话时告诉CoreNFC应该监听哪些无线电标准。每一个标准都需要对应的权限才能被使用。我请求使用了[.iso14443, .iso15693, .iso18092]，其中最后一个标准是FeliCa，这种标准主要在日本使用，而使用它还需要com.apple.developer.nfc.readersession.felica.systemcodes权限。如果没有这个权限，整个会话都会失败，而错误信息中并不会明确指出“是FeliCa导致了问题”。

为了解决这个问题，只需要请求那些你确实有权限去处理的选项即可：

pollingOption: [.iso14443, .iso15693]

.iso14443涵盖了NTAG和MIFARE，这些正是任何标签项目所需要的标准。我当初添加了第三个选项，结果却导致会话无法启动——因为有些不常见的标签会导致错误信息出现。

这与之前遇到的“通配符配置文件导致的错误”是同一个道理，只不过问题的表现形式不同而已：在那种情况下，是“缺少某个权限”导致了签名失败；而在这里，则是本来不需要的权限在运行时被要求使用了。

问题4：对于一个确实存在的文件，编译器却提示“找不到‘YourClass’这个类”

你将一个Swift文件添加到本地的Expo模块中，然后进行构建，但编译器却提示该类不存在。

造成这种问题的原因是iOS依赖关系的管理方式。CocoaPods是负责管理这些依赖关系的包管理工具，每个依赖项都会附带一个podspec文件，这个文件列出了该依赖项所包含的所有源代码文件。你的项目中，podspec文件中可能写着“这个文件夹中的所有.swift文件”，也就是**/*.swift这样的写法。

问题在于：CocoaPods在执行pod install命令时，只会将这个通配符模式解析一次。由于这是一个静态的规则列表，之后你添加的任何文件都不会被包含在这个规则中，因此编译器认为你的类确实不存在。

为了解决这个问题，请记住这个规则，以后不要再为此浪费时间了：

如果是在现有的文件中添加一个函数，就需要重新构建项目；如果是添加一个新的文件，则应该先执行pod install命令，之后再重新构建项目。

错误信息中并没有提到这两点。

为什么无法实现“触屏支付”功能

正是在这里，这两个平台之间的差异已经不再仅仅是程度上的区别了。在向产品经理做出任何承诺之前，你必须了解这一点。

“触屏支付”实际上代表着两种不同的含义。

首先，有一种是用手机进行支付：比如Apple Pay，或者Google Wallet中的银行卡功能。在iOS系统中，相关的安全组件是被关闭的，也没有任何第三方API可供使用——既没有相应的权限，也不具备这样的功能。

其次，还有一种是通过手机接收付款请求：例如iPhone上的“触屏支付”功能，或者ProximityReader框架。虽然这些技术确实存在，但要想真正将其集成到应用中，仍然需要满足许多条件：

• 需要拥有机构级开发者账户，并且要以账户持有者的身份进行申请。

• 需要分别申请测试版权限和正式上线权限。

• 苹果会根据预先设定的标准进行审核，而获得正式上线许可可能需要数周时间。

• 必须通过经过苹果认可的支付服务提供商来进行集成，比如Stripe、Adyen或Square。

现在来看Android系统。HostApduService允许任何应用程序模拟银行卡的功能。无需任何审批流程，也不需要特定的权限或支付服务提供商的支持——只需实现processCommandApdu()方法并注册你的AID即可。AID其实就是应用程序标识符，支付终端会根据这个编号来决定应该让手机上的哪个应用程序进行处理。

不过这里确实存在一个关键限制：只有在你的应用程序被设置为默认钱包应用（在Android 15及更高版本中），或者处于前台状态并调用了setPreferredService方法时，那些注册在CATEGORY_payment类别下的AID才能正常使用。而那些用于封闭式支付卡、会员积分系统、访问控制功能或存储值服务的AID，则始终是可以被使用的，且无需任何特殊审批。

与本手册中提到的其他所有差异不同，这种差异并不是程度上的或形式上的区别。简单来说，其中一个平台根本就不具备实现这一功能的能力。如果你的产品计划中包含了让手机模拟银行卡的功能，那么这个方案只适用于Android系统；最好现在就了解这一点，而不是等到开发周期快结束的时候才发现这个问题。

为什么你需要自己编写原生模块

到目前为止，本项目中的所有功能都是通过react-native-nfc-manager来实现的。但在项目的最后阶段，我们更换了这一依赖库，而且原因也在开发过程中发生了变化。

因此，我们不应该默默地让这些带有缺陷的代码继续存在下去。事实上，有些团队确实无法使用第三方依赖项。某些内部政策、审计要求，或者某些包，根本无法在合理的时间内得到修复并合并到项目中来。对于“我该如何自己实现这个功能？”这个问题，确实值得认真思考。

至于这个特定的依赖项，相关的证据早已被收集到了——通过阅读相关代码就可以发现这些问题：

最后那个问题在测试阶段导致了严重的故障：扫描失败后，屏幕上根本不会显示任何内容，因为error(err.message)这一代码会返回空字符串，而React会将空字符串视为错误。这个问题的存在其实只是因为在代码中定义了错误的处理方式而已。

这些问题都无法通过JavaScript来解决。

搭建框架已不再是难点

npx create-expo-module@latest --local --name NfcNative \
  --package com.you.nfcnative -p apple android --features Function

通过pod install命令，系统会自动将这四个文件集成到构建过程中。无需进行任何Xcode项目配置，也无需使用RCT_EXPORT_METHOD宏或手写JSI代码——这种C++层使得JavaScript可以直接调用原生代码。如果你是在“桥接时代”编写过React Native原生模块的，那么这种方法对你来说应该非常熟悉。

不过也存在两个小问题，而且这些问题的文档中并没有明确说明：--name参数用于设置原生模块的名称，而存储目录则是通过路径参数来指定的（如果没有指定路径，模块会被保存在modules/my-module文件夹中）。另外，生成的podspec文件可能会无形中提高应用程序的最低系统要求。

那些真正能传达信息的类型错误

internal final class NoNfcSettingsException: Exception {
  override var reason: String {
    "iOS系统中没有可使用的NFC设置。只有当硬件支持NFC功能时，才能使用它。”
  }
}

Expo框架中的Exception类为每种错误都提供了一个代码以及一条说明信息，这些信息都可以通过JavaScript直接读取。这就是解决上述问题的根本方法。

而这里有一个让我感到惊讶的地方：即使掌握了原生代码的实现，也并不能免除你排查错误的工作。Expo会自动处理这些异常信息：

FunctionCallException: 调用‘openNfcSettings’函数失败
  → 原因是：NoNfcSettingsException：iOS系统中没有可使用的NFC设置……

err.message实际上只是描述异常发生原因的代码段而已。在错误链中，这一部分位于最后；这与库中出现的问题恰恰相反——在库中，这些错误信息是空字符串；而在这里，它们被隐藏了起来，但两者都导致了同样的问题。

下面是在应用程序中显示的这条错误链，它与JavaScript接收到的信息完全一致：

在用户能够看到的信息之前，有整整三行与框架相关的代码。解决问题的关键并不在于Swift语言本身，而在于用户界面的设计：应该先展示最核心的错误信息，其余的详细内容则可以放在需要时才显示出来的地方。

同样的错误，同样的信息，没有任何内容被遗漏。那些用Swift语言编写的代码才是引导用户理解问题原因的关键部分，而“原始错误链”则可以在需要时通过一次点击就能查看。

掌握原生代码的实现确实会改变哪些信息会让你感到惊讶吧。

那个在测试中未能被发现的漏洞

在将应用程序的实现方式切换后，当取消扫描操作时，系统会显示一条红色的提示信息“无法读取标签”，而之前则什么信息都不会显示。

在我们的Swift代码中，会抛出UserCancelledException异常；相应的映射表也是根据UserCancelledException来设计的。然而这两者并不匹配，因为Expo在处理这些异常时会对代码进行修改：它会去掉字符串末尾的Exception后缀，将驼峰式命名法转换成小写字母形式，然后在前面加上ERR_前缀：

UserCancelledException  →  ERR_USER_CANCELLED

这就是为什么所有的测试都能通过的原因：

const wrapped = (code, message) =>
  new Error(`调用‘readTag’函数失败 → 原因是：${code}: ${message}`);

实际上，并不存在code这个属性，因为我认为Expo并没有设置它。代码本身及其对应的测试都基于一个错误的假设而设计，因此它们才会得出完全一致的结果。

< p>你发明的那些测试工具，其实只能证明你的代码本身是自洽的罢了。真正起到关键作用的是用户点击“取消”按钮这一行为。

< p>这个修复方案使得表格中的键值对仍然与Swift类名保持一致，并且能够自动生成ERR_系列的相关代码格式，这样一来，就只有一个权威的数据来源了，而不会再有两份逐渐出现差异的列表。现在，通过使用设备错误信息、code属性等来进行测试，就可以确保代码不会出现回归问题。

< p>检查点： git checkout step-4-own-module。这个模块与相应的库是分开管理的。

< h2 id="heading-how-to-prove-parity-before-you-switch">如何在切换实现方案之前验证其正确性 < p>千万不要仅仅凭直觉就决定更换实现方案。应该先在两种实现方式中都读取相同的物理标签数据，然后对比分析结果。

< p>使这种验证方法变得有效的设计原则是：“不同”并不意味着结果一定是错误的。我们的检测机制会同时报告数据的容量和可写性等信息，而库的检测机制并不包含这些内容；如果将这种差异视为错误，反而会造成误导。

< table> 状态 含义 相同 两种实现方式都报告了相同的结果，因此它们是一致的 不同 两种实现方式报告的结果不同，因此存在差异。 仅本端支持 我们的实现方式了解的信息更多，这就是需要切换的原因 仅库端支持 我们丢失了一些信息，因此也无法进行切换 两者均不支持 无法得出任何结论 < p>当仅库端支持这种情况出现时，禁止进行切换是非常重要的：虽然这种差异并不表示代码存在矛盾，但丢失信息确实是一个严重的问题。

< p>以真实的NTAG213标签为例：四个字段的内容是完全相同的，其中有两个字段只被我们的实现方式报告出来，因此没有任何冲突。这就是我们决定进行切换的依据，而不是因为觉得新代码看起来更合理而已。

< h2 id="heading-what-a-config-plugin-was-doing-for-you">配置插件究竟为你做了什么 < p>删除某个依赖项时，最危险的部分其实并不是代码本身。

< p>react-native-nfc-manager提供了一个配置插件，这个插件负责生成iOS系统的NFC权限相关文件以及NFCReaderUsageDescription描述信息。如果删除了这个插件，那么这些文件就会消失，应用程序会因此失去NFC功能，而且不会出现任何错误提示。在构建过程中，也不会有任何问题发生；只是相关的配置选项不会再出现在界面中了。

< p>因此，正确的操作顺序应该是：首先在app.json文件中自行配置这些选项，然后进行预构建测试，确认生成的结果与插件产生的结果完全一致，之后再删除插件，再次进行验证，最后才删除相应的依赖包。

< p>删除一个依赖项意味着会继承它的构建配置；而插件实际输出的代码，才是最终可见的部分。

< h3 id="heading-keep-the-evidence-after-deleting-the-dependency">在删除依赖项后，务必保留相关证据 < p>之所以要替换那个库，是因为它存在一些缺陷，但这些缺陷对应的测试文件已经不存在了。如果删除了这个库，那些用于检测这些缺陷的测试就无法再运行了，而那些用于验证两种实现方式是否一致的测试也会失效，这样一来，那个手工编制的、包含36个条目的对照表也就无法得到验证了。

因此，该仓库在 `vendor/` 目录下保存了一个被冻结的副本，这个副本遵循 MIT 许可协议，仅被一个测试文件所使用；同时，它也被排除在了 ESLint 和 Prettier 的检查范围之外，因为其相关属性的值在文档中记载有误，而对其进行重新格式化将会破坏它原本所要展示的功能。

✓ 每个错误类别在创建时都会被赋予空消息
✓ 将 U+1F600 这一字符转换为 U+F600，即一个仅用于私用领域的字符
✓ 会忽略它刚刚检测到的语言代码
✓ 对状态字节中的 UTF-16 标志也会视而不见

如果未来的某个版本修复了这些缺陷，那么这些测试用例就会失败，这时我们就需要重新考虑相关的设计方案，而不是将这些失败视为麻烦事。

检查点： git checkout step-5-no-dependency

如何永久锁定标签

在这个整个流程中，有一项操作是无法撤销的。正是这项操作，如果其设计出现错误，就会导致物理设备遭到损坏，因此它被放在了最后一步进行。

在 iOS 上使用 `NFCNDEFTag.writeLock`，在 Android 上使用 `Ndef.makeReadOnly()`——这两种方法都会将芯片中的锁定位设置为“已锁定”状态。这样一来，这个标签就可以被永久读取，但再也无法被写入任何内容了：无论是你的应用程序、其他任何应用程序，还是任何手机都无法对其进行修改。这种操作没有撤销机制，也无法通过恢复出厂设置来改变它的状态。

在实际应用中，人们经常会这样做。比如活动徽章、产品认证标识，或是博物馆的标签等等——凡是会被公众所接触到的物品，都会被设置为“不可修改”状态，因为如果一个标签可以被重新写入，那么任何人都可以随意修改它。

“门”本身就是这个功能的关键所在

原生调用代码只有四行，而所有真正重要的操作其实都发生在这四行代码之前。

在这个应用程序中，两次点击操作才能完成对标签的写入操作——毕竟写入操作是可以被撤销的，你只需要重新输入其他内容即可。但在这种情况下，这样的设计显然是不够的。因此，开发者借鉴了 GitHub 在删除仓库时使用的机制：你需要输入该标签的名称，以证明你知道自己正在删除的是哪个标签。

它所接收到的 `status` 值其实就是标签本身的 NDEF 状态，这个值与写入操作所需的参数是完全相同的——要么是“NDEF”状态，要么是“可读写”状态，要么已经是“只读”状态了。

export function lockGate(tagId, status, typed): LockGate {
  if (!tagId) return { state: 'no-tag' };
  if (status === NDEF_STATUS.READ_ONLY) return { state: 'already-locked' };
  if (status === NDEF_STATUS NOT_SUPPORTED) return { state: 'not-lockable' };

  return normaliseTagId(typed) === normaliseTagId(tagId)
    ? { state: 'armed', tagId }
    : { state: 'needs-confirmation', expected: tagId };
}

确认对话框用于验证用户是否真的愿意执行锁定操作；而输入标签标识符这一行为则体现了用户的关注程度。我们需要重点防范的情况并不是那些想要锁定标签的人，而是那些想要锁定错误的标签的人。

正因如此，在你先读取标签的内容之前，系统是不会启动锁定机制的，并且会显示标签上当前存储的信息。这样，就可以避免在标签被错误地使用之前，导致不必要的麻烦。

标签的标识符会显示在屏幕上，用户也需要手动输入它。这看起来似乎有些多余，但当你想到它的存在目的时，就会明白其重要性了：确保正确的设备能够识别到正确的数据。

注意这个操作流程的顺序：already-locked会在用户确认输入之前被检查，因此没有人能够通过输入来“锁定”一个已经锁定的标签，并且系统也不会提示操作成功。实际上，这种操作根本无法成功，也没有其他办法可以补救。

“无事可做”并不意味着“出了问题”

AlreadyLockedException与LockFailedException被明确区分开来，用户界面会用绿色颜色来显示这种错误状态，并且不会提供任何锁定按钮。标签的状态正好符合用户的期望，但如果将这种情况视为失败，就会让人们误以为某个正常的芯片出了问题。

“无需采取任何操作，也没有任何内容会被更改”这句话确实传达了重要的信息：它说明应用程序并没有尝试进行任何操作，而对于那些无法重复执行的操作来说，了解这一点是非常重要的。

这个原则与在自己的代码中避免抛出依赖关系的错误类型是一样的：两种不同的情况绝对不能被当作同一个信号来处理，而当你需要区分它们时，往往就意味着出现了问题。

需要验证，因为无法通过重试来确定结果

这两种实现方式都会在操作完成后重新检查标签的状态。这种检查在写入操作中也会存在，但在这里它的意义有所不同：如果写入操作失败，还可以重新尝试；但如果锁定操作看似成功，但实际上并没有发生任何变化，那么这个标签就会被认为处于受保护的状态，而用户也无法通过重试来验证这一点的正确性，因为重试本身就会导致问题进一步恶化。

因此，未经过验证的锁定状态不会像未经过验证的写入操作那样被当作一个警告信息来显示。系统会提示标签的状态未知，在依赖该标签之前需要先读取其内容。

最确切的确认信号会来自标签本身，而不是应用程序。当用户再次尝试写入该标签时，CoreNFC系统会直接拒绝这一操作，而不会让用户的代码有机会执行这个操作。

那句话是iOS编写的，而不是这个应用程序编写的。这是唯一真正重要的证据，也是你永远无法再次获取的证据。

一个独立的类，而非某种标志

NfcLockSession在很大程度上重复了写入会话的相关内容：设置、代理以及一次性的确认流程。这种设计是故意的。

另一种选择是在写入会话中使用lock: Bool这个参数。然而，这样一个布尔型参数有时会导致标签损坏，而三年后，在有人对代码进行重构时，恰恰因为这个人从未读过原始代码文件，所以不小心使用了这个参数。两个调用位置、两种不同的意图，但却没有从错误的地方能够访问到相同的代码路径。

有时候，对于“这些代码几乎是一样的”这种情况，最好的处理方式就是让它们确实保持几乎相同的状态。

以及那个在代码有误时却仍然正确的测试

it('会拒绝完全不符合NDEF标准的标签', () => {
  expect(lockGate(TAG, NDEF_STATUS NOT_SUPPORTED, TAG).state).toBe('armed');
});

从名称上看，这个测试应该是用来“拒绝”不符合NDEF标准的标签的；但从实际的测试结果来看，它显示的是“armed”。这个测试通过了，因为代码确实执行了相应的操作，而writeLock方法是NFCNDEFTag对象上的方法，因此，对于不符合NDEF标准的标签来说，本来就不应该调用这个方法。

名称是正确的，但代码却是错误的。这个错误之所以能够被发现，是因为在查看测试结果时，看到了与测试名称相对应的正确结果；只有通过这种方式，才能发现这种错误：那些与错误代码相匹配的测试，在实际的测试运行过程中是无法被检测出来的。

你究竟会如何将这个产品正式发布呢？

上面提到的所有步骤都是使用expo run:ios、Xcode、CocoaPods在本地完成的，而且过程中还两次对整个硬盘进行了清理操作。另一种选择是使用EAS Build工具来进行开发，因此，对于这两种方法来说，确实需要进行一次认真的比较，而不仅仅是简单地进行推荐。

下面提到的所有步骤都是通过EAS Build工具进行测试的：首先进行了一次正式的生产环境构建测试，然后还设计了一个专门的实验来验证上述说法的正确性，而不是直接假设这些说法就是正确的。唯一没有做的事情就是安装最终生成的.ipa文件。由于这是App Store版本的应用程序，因此无法通过其他方式安装；此外，本手册中提到的所有与NFC功能相关的测试，都是在使用在真实设备上本地编译生成的二进制文件进行的。

如果使用EAS Build工具，本来可以节省很多时间和精力

在这个项目中，最令人头疼的问题就是这个错误：

“iOS团队配置文件”不支持NFC标签读取功能。

解决这个问题的方法需要手动操作，而且从错误信息中根本无法看出解决办法：需要在苹果的官方平台上注册一个明确的App ID，然后勾选NFC标签读取选项，最后重新生成配置文件。从这个错误信息来看，根本没有任何提示说明需要打开浏览器来解决问题。

EAS会自动完成这一步骤。如果你的权限文件中包含了受支持的权限项，eas build命令会在Apple开发者控制台中启用相应的功能；如果该功能已经启用，系统就会跳过这一步骤。而com.apple.developer.nfc.readersession.formats这个键值对，正是这款应用所声明的权限项，它确实被列在受支持的权限列表中。

因此，在整个使用指南中，唯一需要人工操作且过程较为繁琐的步骤，实际上却被我根本没有使用的EAS工具给自动化处理掉了。

如何通过实际验证来确认事实

使用eas build命令针对TapCard的实际应用包标识符进行测试，并无法证明这一点的正确性。在相信别人提供的截图之前，了解其中的原因是非常重要的：

✔ 注册的应用包标识符：com.nfccard.tap
✔ 同步后的权限项：无更新

“无更新”，是因为这个App ID原本就已经具备了NFC标签读取功能。我是通过浏览器手动为它配置了这个功能的。所有这些测试结果只证明了EAS工具认可我之前已经完成的工作而已。很多声称“EAS会自动处理这些步骤”的说法，其实都是基于这样的测试结果来宣传的。

要真正验证这一点的正确性，就需要使用一个从未存在过的应用包标识符。因此，我们可以创建一个临时项目，比如com.nfccard.tap.eastest，这个项目中除了包含所需的权限项外，不包含任何其他内容。这样的临时项目应该与真正的应用程序分开管理，而不能通过暂时更改其应用包标识符来完成测试，因为这样做可能会导致存储的凭证信息混乱。

✔ 注册的应用包标识符：com.nfccard.tap.eastest
✔ 同步后的权限项：已启用：NFC标签读取功能

事实确实如此。我们使用了一个根本不存在的App ID，仅通过权限文件就为它配置了NFC标签读取功能，整个过程没有使用浏览器，也没有访问任何官方门户网站。由于同步操作是在配置凭证信息的步骤中进行的，所以使用的命令是eas credentials:configure-build，而且这个命令并没有消耗任何构建资源。

如果你要重复进行这个测试，有一个实际需要注意的地方：请先运行真正的应用程序构建过程。分发证书是针对整个账户而言的，而Apple对每个账户可以持有的分发证书数量是有限制的，因此如果先创建临时项目，就会浪费一个证书，而这个证书最终可能会被用于一个你打算删除的应用程序上。按照正确的顺序操作的话，临时项目会尝试重用真正的分发证书，而只会为自己生成一个新的配置文件，这种配置文件是针对每个应用包标识符单独生成的。

CLI工具的实际功能

这种权限项与功能之间的对应关系并不是什么神奇的机制，也不是隐藏在某个难以发现的地方。实际上，它就是一个查找表，而NFC标签读取功能在这个查找表中也有相应的条目（文件路径为eas-cli/build/credentials/ios/appstore/capabilityList.js）：

{
  name: 'NFC Tag Reading',
  entitlement: 'com.apple.developer.nfc.readersession.formats',
  capability: CapabilityType.NFC_TAG_READING,
  // 从技术上讲，似乎只有`TAG`这个选项是被允许的，但很多应用程序都会建议用户同时添加`NDEF`选项。
  validateOptions: createValidateStringArrayOptions(['NDEF', 'TAG')),
  getSyncOperation: getDefinedValueSyncOperation,
}

请再读一遍那条评论，因为它实际上是在谈论你：NDEF 可能并不是一个有效的值。所有的教程都建议你使用["NDEF", "TAG"]这个格式，这本手册中的app.json文件也是这样写的，而负责维护映射表的人也明确表示只有TAG才有实际意义，但他还是接受了这两种格式，因为如果拒绝其中任何一种，就会导致整个系统出现问题。当没有人去检查相关规范时，这就是所谓的“惯例”了。

getDefinedValueSyncOperation则是另一个关键环节。这个操作会判断某个功能是否已被定义，因此同步过程是双向进行的，而不仅仅只是添加新的内容。

还有一个文档中没有提到的实际细节：同步操作实际上是由credentials步骤触发的，而不是由构建步骤引发的。

SetUpTargetBuildCredentials.runAsync()
  └─ ensureBundleIdExistsAsync({ entitlements, … })
       └─ syncCapabilitiesAsync()
            → "Synced capabilities: Enabled: NFC Tag Reading"    (或 "No updates")

因此，通过eas credentials:configure-build --platform ios命令，你可以注册App ID并同步相关功能，而无需进行任何构建操作。如果你只需要确保苹果端的相关设置正确无误，那么你根本不需要花费额外的成本来进行构建。

随之而来的问题

同步过程是双向的：如果某个功能在远程被设置为启用状态，但本地的相关配置文件中并没有这个选项，那么当你运行eas build命令时，这个功能就会自动被禁用。

那些既通过门户网站手动管理各种功能，又使用EAS进行构建的团队，会发现EAS会自动关闭一些功能。无论你是否愿意，配置文件最终都会成为决定各项功能是否启用的权威依据。

EXPO_NO_CAPABILITY_SYNC=1这个选项可以让你选择不参与同步过程，但需要注意的是，这样做会导致远程所做的更改无法被同步到本地，从而后续可能会引发配置文件不一致的问题。因此，请为各种功能指定一个明确的负责人，让其来负责这些功能的配置和管理。

EAS也无济于事的事情

对于这个项目遇到的大多数问题来说，“使用EAS”并不能解决它们，如果有人声称EAS能帮助解决问题，那其实就是在误导人们：

问题	EAS能帮忙吗？
在App ID中启用NFC标签读取功能	✅ EAS可以自动完成这个操作
需要将整个磁盘空间重复使用两次	✅ 构建过程可以在其他地方进行
构建完成后Gradle后台进程会占用大量内存	✅ 可以在本地不运行任何构建相关程序
添加Swift文件后需要执行pod install命令	✅ 每次构建都会进行清理操作
CoreNFC会话释放后内存未得到正确处理	❌ 这是一个代码错误
需要多次执行相同的操作来完成某项任务	❌ 这也是一个代码错误
FeliCa相关的功能请求	❌ 这并不是EAS能够管理的功能
String.fromCharCode方法在处理emoji时会出现截断现象	❌ 这是一个依赖库相关的问题
Expo在处理某些情况时会返回ERR_USER_CANCELLED错误代码	❌ 这只是一个错误的假设而已
读取标签数据本身	❌ 对于这种功能来说，云端服务根本无法替代物理芯片的作用

EAS能够解决机器本身存在的问题，但无法解决与NFC技术相关的问题。 如果这本手册中任何关于NFC的内容，其结果都会是完全相同的。

交易方式

本地构建需要耗费磁盘空间、内存资源以及进行相应的设置工作。在这个项目中，我们曾两次使用460GB的磁盘进行构建；在内存压力较大的情况下，有三个后台进程被强制终止；此外，还因为Gradle守护进程出现故障而导致重建工作失败。

使用EAS需要等待排队时间，并且还需要使用云服务来进行构建；同时，你的签名凭据也会存储在Expo的服务器上。但它无法缩短真正关键的那个环节：你仍然需要亲自将芯片靠近手机进行读取操作。 即使云构建结果显示成功，也无法确定标签数据是否已经被正确读取。

对于那些拥有可用本地开发工具链的个人项目来说，本地构建在迭代速度上确实具有优势；但对于团队项目、持续集成管道，或者那些发现自己的磁盘空间在构建过程中被完全占用的用户来说，仅从代码同步的角度来看，使用EAS也是一个非常不错的选择。

Android端的简要介绍

Android确实值得拥有属于自己的专门手册，而这样的手册也正在编写中。对于那些不想等待的人来说，这一部分内容可以作为一个预览：其中介绍了Kotlin语言在Android平台上的使用方式，以及两种平台在架构上的差异——这些差异使得NFC技术在Android和iOS上的实现方式实际上是完全不同的。

请将这部分内容视为设计层面的预览，而不是已经经过验证的实现方案。Kotlin代码是针对官方文档中规定的API进行编译的，其功能与在硬件上经过验证的Swift代码是相似的；因此，整体框架是正确的。至于关于设备测试的详细信息，请参阅后续发布的正式手册。

那些真正重要的差异是从API层面就能看出来的，而不是通过设备测试才能发现的；而这些差异恰恰决定了你应该如何组织代码结构。

Android没有会话机制

iOS会为你提供一个会话对象，这个会话对象本身就是整个交互流程的核心：你启动应用程序后，操作系统会生成相应的界面元素，并将标签数据提供给你；之后该会话对象就会失效。而Android则提供了读取模式：这种模式会在标签靠近设备时触发，对应的回调函数会被绑定到你的前台活动中。

adapter.enableReaderMode(activity, ::onTagDiscovered, flags, Bundle())

iOS会话对象所承担的所有功能，在Android系统中都会由你自行负责实现：

	iOS	Android
扫描界面显示	操作系统生成界面元素	应用程序自己绘制所有界面元素
会话结束时机	读取一个标签后自动结束	在每次退出程序时调用disableReaderMode
所需资源	屏幕上不会显示任何内容	仅需要前台活动对象，而非上下文对象
回调线程	主线程	绑定器线程
取消操作	系统会提供相应的接口来处理	需要你自己手动实现取消操作

最后那一行代码实际上与JavaScript相关。这个跨平台的`cancelScan()`函数在Android系统中确实能够正常工作，但在iOS系统中则被明确记录为“无实际效果的功能”：在iOS系统中，系统本身负责处理取消操作，而Swift模块也故意没有实现这一功能。

export async function cancelScanNative(): Promise {
  if (Platform.OS !== 'android') return;
  await NfcNative.cancelScan();
}

另外：需要传递 FLAG_READER_NO_platform_SOUNDS，否则操作系统会在应用程序已经向用户说明操作步骤的情况下，仍然播放自己的发现提示音。

Kotlin与One Design Note

private fun onTagDiscovered(tag: Tag) {
  val ndef = Ndef.get(tag) ?: run {
    stopReaderMode(); rejectOnce(NotNdefException()); return
  }

  try {
    ndef.connect()

    val status = NfcTagInfo.status(ndef)
    val capacity = ndef.maxSize

    messageToWrite?.let { message -> 
      // 在执行任何操作之前先进行确认，操作顺序与Swift中的相同：如果拒绝操作，标签的状态将保持不变；如果在写入过程中出现错误，标签的状态可能会发生变化。
      if (!ndef.isWritable) { … }
      if (message.toByteArray().size > capacity) { … }
      ndef.writeNdefMessage(message)
    }

    // 可以通过相同的连接来读取数据。对于写入操作来说，这一过程属于验证环节；而对于读取操作来说，它就是获取到的数据本身。
    val onTag = ndef.ndefMessage
    …
  } finally {
    runCatching { ndef.close() }
  }
}

Android系统中并没有与iOS的NFCNDEFStatus相对应的机制，因此标签的状态是通过其他方式推导出来的，而不是直接被读取到的。

fun status(ndef: Ndef?): Int =
  when {
    ndef == null -> 1     // 不是NDEF格式：因为Ndef.get()返回null
    ndef.isWritable -> 2  // 可读写
    else -> 3             // 只能读取
  }

iOS可以直接给出这个问题的答案；而Android则是通过Ndef.get()返回null来表示“不是NDEF格式”，同时会通过isWritable属性来判断标签是否可以写入数据。将这两种方式映射到同一组数字中，就可以确保TypeScript代码无需知道当前是在哪个平台上运行，而这正是原生模块的主要作用所在。

如果你移植这段代码，就会遇到一些重要的差异

	iOS	Android
权限模型	应用ID + 功能权限 + 是否为付费账户	只需在manifest文件中添加一行代码，即可免费使用
配置错误时的后果	会出现签名错误，但错误信息中不会明确指出“NFC”相关问题	会因为权限缺失而导致功能无法使用
权限的细分程度	针对每个具体的操作请求进行判断	一个权限就可以覆盖所有相关的操作
扫描用户界面	使用系统自带的界面，无法进行自定义设计	没有专门的用户界面，所有元素都需要手动绘制
通过读取操作可以获取标签的容量信息	❌ 需要通过特殊查询才能获取	✅ 可以使用getMaxSize()方法获取
通过读取操作可以判断标签是否可写入数据	❌ 需要通过特殊查询才能获取	✅ 可以通过isWritable属性来判断
天线的位置	位于设备的上边缘	位于设备的后中部
卡片模拟功能	无法实现	可以通过HostApduService实现卡片模拟功能
是否支持永久性锁定	使用writeLock方法可进行永久性锁定，且这种锁定是不可逆的	使用makeReadOnly()方法可进行永久性锁定，且这种锁定也是不可逆的

从那张表格中可以归纳出两种模式。

iOS会将处理这些操作的负担提前承担，而Android则会在后期进行处理。在iOS系统中，需要在读取任何数据之前先完成权限验证、签名等操作；而在Android系统中，则是在阅读模式下通过Activity的生命周期机制来处理这些功能，同时也可以自行实现取消操作的功能。 此外，两者之间的功能差异并没有看起来那么大。并不是说iOS提供的信息更少，而是说在Android系统中，这些功能会在普通的读取操作中被自动执行；而在iOS系统中，则需要用户在进行特定操作时主动请求这些功能。同样的数据，但获取方式却不同。正如你们所见，我在分析三份文档时都犯了这个错误。

演示仓库

以上所有内容都属于同一个项目，即TapCard，它是一个完整的应用程序，而不是零散代码的集合。

层级	位置	包含的内容
应用程序代码	app/(tabs)/	包括读取、写入、聚焦等相关界面，以及标签信息显示功能
纯逻辑代码	lib/	包含NDEF解码器与编码器、vCard格式处理代码、容量检测逻辑、错误处理机制等，约2,240行代码，未使用React Native库
原生模块代码	modules/nfc-native/	包含约1,010行的Swift代码和约475行的Kotlin代码，主要用于会话管理、类型化异常处理及标签格式转换等功能
状态存储代码	store/	用于存储应用程序的状态信息，如用户配置、最后读取的标签信息等，同时使用AsyncStorage进行数据持久化存储
辅助代码	vendor/	包含被移除的依赖项及相关测试代码，用于验证这些依赖项移除的合理性
备注文件	DEVLOG.md, GOTCHAS.md, PLATFORM-NOTES.md	记录了所有的命令执行过程及出现的错误信息，还包括75个陷阱测试结果以及各项功能之间的运行对比数据

总共进行了293次测试，分属于15个测试套件，整个测试过程耗时约一秒钟，而且完全不需要任何硬件设备。这就是保持解码逻辑纯粹所带来的好处。

git checkout step-0-scaffold        # 启动应用程序，但不支持NFC功能
git checkout step-1-first-read      # 进行权限验证及原始数据读取操作
git checkout step-2-decode          # 使用自定义解码器进行标签信息解析
git checkout step-3-write           # 处理vCard格式数据并检测标签容量
git checkout step-4-own-module      # 使用原生模块与库文件一起运行应用程序
git checkout step-5-no-dependency   # 移除所有依赖项，仅使用库文件
git checkout step-6-android         # 在Android平台上使用Kotlin语言的读取模式

你可以克隆这个项目，购买一些贴纸，然后切换到step-1-first-read分支，将自己的芯片放在手机上测试这些功能。通过这种实际操作，你能最快地了解上述所有内容的具体运作方式。

开始之前需要了解的内容

首先购买标签芯片。目前没有模拟器可供使用。当初我的芯片在邮寄过程中丢失了，导致项目停摆了两周时间，没有任何复杂的架构设计能够替代真正的芯片来完成这些功能。在信任任何依赖项之前，先仔细阅读相关文档。** 使用ndef-lib进行了20分钟的测试后，我们发现了三个真正的缺陷，这些缺陷甚至改变了应用程序的架构。而这些缺陷中，没有一个出现在我会去搜索的问题跟踪系统中。 要假设程序出现故障时可能不会产生任何提示信息。** 在我记录的75个问题中，有大约12个根本不会引发任何错误：未释放的会话对象、被移除的配置插件、未被正确处理的分号、被截断的emoji符号、空白的错误信息，以及被Git忽略的原生模块。在NFC相关的技术场景中，“什么异常都没有发生”其实是最常见的现象，因此必须相应地设置监测机制，并在实际运行环境中进行验证，而不能仅仅依赖返回值来判断问题是否存在。 应该将平台差异明确体现在代码类型中，而不是通过注释来说明。** 应将该差异定义为一种“一级状态”，例如这样定义： ```typescript type Fact = { label: string; value: string | null; // null表示该平台没有提供相关数据 unavailable?: string; // 用通俗的语言解释为什么无法获取该数据 }; ``` 如果一个用户界面在值缺失或为0的情况下都只显示一条空白的提示信息，那么这种设计根本起不到任何教育意义。 另外，不要让某个结论继承其背后观察结果的可信度。** 有个例子就耗费了我们最多的时间，而实际上它与NFC技术毫无关系。

结论

现在你们已经对iOS平台有了全面的了解：复杂的权限设置机制、因为常用解码器会丢失数据而不得不手动编写的解码程序、在执行操作之前需要先询问标签的写入路径、受地理位置影响的聚焦计时功能、用Swift语言实现的原生模块、被删除但其相关证据仍被保留的依赖项，以及那些需要用户输入名称才能使用的标签。

接下来有三件事值得进一步探索：

1. 背景标签读取功能：** 在应用程序关闭的状态下点击标签。iOS系统会弹出一条通知，用户必须点击这条通知才行，而且这种功能仅适用于某些类型的标签。正是这一特性让NFC技术显得如此神奇，而关于哪些标签符合这个条件，其具体规则也值得深入了解。

2. 加密标签：** NTAG424类型的标签会在每次被点击时更新计数器。如果你想让某个标签具有凭证功能而不是仅仅作为标识符使用，那么这就是你需要开始研究的方向。

3. 还有Android平台，** 它将是我们的下一个学习对象。上面的概述只是整个内容的框架，而关于如何在真实设备上操作Android平台的详细步骤，将在后续的内容中介绍。

实际上，真正有趣的部分从来都不是requestTechnology这个方法。真正值得关注的是那些两个平台在你使用方法错误时拒绝告诉你的信息。

参考资料与延伸阅读

关于Apple、CoreNFC以及权限设置的相关资料：

• Core NFC, NFCTagReaderSession, 和 NFCNDEFTag

• queryNDEFStatus: 这个方法其实并不存在，我们的项目之前错误地认为它存在。

• Near Field Communication Tag Reader Session Formats entitlement

• 在iPhone上设置Tap to Pay功能所需的权限

• 配置家庭控制功能

• iPad上是否支持CoreNFC功能: 一位Apple工程师确认，该框架仅适用于iPhone。

Android：

• NFC基础知识与高级NFC功能

• NfcAdapter.enableReaderMode

• Ndef：getMaxSize()、isWritable()

• 基于主机的卡片仿真技术

相关格式：

• NFC论坛的NDEF与RTD规范：包括URI前缀表及文本记录的状态字节

• RFC 2426：vCard 3.0规范，涉及N字段以及行折叠功能

Expo与React Native：

• eslint-plugin-react-hooks，以及其中两个备受关注的规则：purity和set-state-in-effect

• Expo Modules API与配置插件

• 持续原生应用生成技术

• EAS Build中的iOS功能支持：哪些权限会被同步，以及EXPO_NO_CAPABILITY_SYNC的作用

• expo-modules-core与ios/Core/Exceptions/CodedError.swift：ERR_USER_CANCELLED这个错误码的来源

已发布的NFC相关功能，可参考以下链接：“你可能已经见过这些内容”：

• 在“快捷方式”中设置触发条件，苹果官方文档。NFC功能需要iPhone XS或更高版本及iOS 13.1系统

• 在“查找”应用中将AirTag等物品标记为丢失，苹果官方文档

• amiibo常见问题解答，任天堂官网，关于只读与可读写数据类型的区别

• 使用“英国移民身份验证”应用程序，GOV.UK官方网站

• iPhone上的“轻触支付”功能及支持地区列表，苹果官网

与“焦点功能”相关的前沿技术：

• Foqos（开源项目，可在App Store》中下载）以及TapBlok

本项目所替代的库：

• react-native-nfc-manager：这个库属于MIT许可协议。在3.17.2版本中，通过阅读其源代码发现了其中存在的缺陷；这些缺陷对应的测试用例已被保存在演示项目的vendor/目录中。