Ionic Capacitor集成NFC报plugin_not_installed错误问题求助

问题核心本质 #

出现该报错的根因是Capacitor原生工程层没有真正集成phonegap-nfc插件，仅安装npm层面的JS依赖包，不会自动把插件注入到iOS原生编译流程中。结合当前配置和操作流程，具体诱因包含以下几点：

• 未将phonegap-nfc以Cordova插件的形式注册到Capacitor项目配置，仅安装了JS侧的包装依赖
• 依赖版本存在兼容断层：当前使用的@ionic-native/nfc@^4.20.0属于早期Ionic 3/4时代的适配包，和新版Capacitor、高版本phonegap-nfc的适配逻辑不匹配
• iOS端未提前声明NFC系统权限，导致同步流程中插件被系统校验规则拦截，无法正常注入
• 旧的iOS构建缓存残留，干扰了插件的注入编译流程

分步解决操作 #

1. 正确注册Cordova原生插件 #

仅安装npm依赖不会触发Capacitor的原生插件注入流程，需要显式把phonegap-nfc注册到Capacitor配置中，执行命令：

npx cap cordova add phonegap-nfc

注意：不要使用旧版ionic cordova plugin add命令，该命令在纯Capacitor项目中不会修改Capacitor的核心配置文件。
注册完成后，打开项目根目录的Capacitor配置文件（capacitor.config.ts/capacitor.config.json），确认plugins配置块下已经存在NFC插件的注册项，缺失的话手动补充：

const config: CapacitorConfig = {
  appId: '你的应用包名',
  appName: '你的应用名称',
  webDir: 'build',
  plugins: {
    NFC: {}
  }
};

2. 替换版本不匹配的依赖包 #

当前使用的@ionic-native/nfc@4.20.0版本过老，和Capacitor 3及以上版本适配性极差，需要替换为匹配当前Capacitor版本的适配包：

# 卸载旧的不兼容依赖
npm uninstall @ionic-native/nfc phonegap-nfc
# 安装匹配新版Capacitor的适配层与核心插件
npm install @awesome-cordova-plugins/nfc phonegap-nfc@latest

同步修改app.module.ts中的provider导入路径，将原来的@ionic-native/nfc导入替换为新包的对应路径，避免引用失效。

3. 补全iOS端NFC权限配置 #

phonegap-nfc插件在iOS端需要系统级权限声明，否则就算插件注入成功，也会被iOS安全规则拦截，触发插件未安装的误报：

• 打开iOS工程目录下的Info.plist，新增NFC使用权限字段：

<key>NFCReaderUsageDescription</key>
<string>应用需要使用NFC功能读取标签信息</string>

• 打开Xcode工程的Target设置，在Signing & Capabilities栏目下添加NFC Tag Reading能力，确保权限配置被正确写入entitlements文件。

4. 清理缓存后重新同步编译 #

旧的构建缓存会导致插件注入流程失效，按顺序执行清理与同步命令：

# 清理node依赖与锁文件，避免残留缓存干扰
rm -rf node_modules package-lock.json
npm install
# 重新构建web资源
ionic build
# 清理iOS平台的旧编译缓存
rm -rf ios/App/Pods ios/App/App.xcodeproj/project.xcworkspace
# 重新同步插件到原生工程
npx cap sync ios
# 打开Xcode工程重新编译运行
npx cap open ios

验证方式 #

完成配置后，先在Xcode的「Build Phases -> Compile Sources」列表中搜索phonegap-nfc相关源码文件，如果能检索到对应条目，说明插件已经被正确注入到原生编译流程，运行时就不会再触发plugin_not_installed的报错。

内容的提问来源于stack exchange，提问作者Dominik Hartl