Back to Details

capacitor-plugin-spm-support

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Add Swift Package Manager Support to a Capacitor Plugin

为Capacitor插件添加Swift Package Manager支持

Add SPM support to an existing Capacitor plugin so it can be consumed without CocoaPods.
为现有Capacitor插件添加SPM支持，这样无需CocoaPods即可使用该插件。

When to Use This Skill

何时使用本技能

  • User wants a plugin to work through Xcode's package manager
  • User is converting an existing iOS plugin from Obj-C bridge files to bridged Swift registration
  • User needs the plugin package manifest and file exports updated for SPM
  • 用户希望插件能通过Xcode的包管理器工作
  • 用户正在将现有iOS插件从Obj-C桥接文件转换为桥接Swift注册方式
  • 用户需要更新插件包清单和文件导出以适配SPM

Procedures

操作步骤

Step 1: Gather Plugin Information

步骤1：收集插件信息

Read these files in the plugin root:
  • package.json
  • the 
    .podspec
  • the main Swift plugin class under 
    ios/
Record:
  • the package name
  • the pod name
  • the iOS deployment target
  • the plugin class name
  • the JavaScript plugin name
  • all exposed plugin methods
  • any third-party CocoaPods dependencies that also need SPM equivalents
读取插件根目录下的以下文件：
  • package.json
  • .podspec
    文件
  • ios/
    目录下的主Swift插件类
记录以下信息：
  • 包名称
  • pod名称
  • iOS部署目标版本
  • 插件类名
  • JavaScript插件名称
  • 所有对外暴露的插件方法
  • 所有需要匹配SPM等效依赖的第三方CocoaPods依赖

Step 2: Create 
Package.swift

步骤2：创建
Package.swift

Add a 
Package.swift
manifest that:
  • declares the plugin package name
  • sets the iOS minimum version
  • points the target at the plugin's iOS source directory
  • depends on the Capacitor Swift package support package used by the project
  • adds any resolved third-party SPM packages
Keep the target structure aligned with the actual plugin source tree.
新增
Package.swift
清单文件，需满足以下要求：
  • 声明插件包名称
  • 设置iOS最低支持版本
  • 将target指向插件的iOS源码目录
  • 依赖项目使用的Capacitor Swift包支持包
  • 添加所有已适配的第三方SPM包
保持target结构与实际插件源码树一致。

Step 3: Convert the Swift Plugin Class

步骤3：转换Swift插件类

Update the plugin class to conform to 
CAPBridgedPlugin
.
Add the bridge properties at the top of the class:
  • identifier
  • jsName
  • pluginMethods
Preserve each method name and return type exactly as the plugin already exposes them.
更新插件类以遵循
CAPBridgedPlugin
协议。
在类顶部添加桥接属性：
  • identifier
  • jsName
  • pluginMethods
精准保留插件原有暴露的每个方法名称和返回类型。

Step 4: Remove Objective-C Bridge Files

步骤4：移除Objective-C桥接文件

Delete the old bridge header and implementation files once the Swift bridge is in place.
Then clean the Xcode project file so it no longer references them.
Swift桥接配置完成后，删除旧的桥接头文件和实现文件。
然后清理Xcode项目文件，移除对这些文件的引用。

Step 5: Update Package Metadata

步骤5：更新包元数据

Update the plugin package manifest so it exports:
  • the iOS sources
  • the podspec
  • Package.swift
Add an iOS SPM install command if the project maintains script helpers.
更新插件包清单，确保导出以下内容：
  • iOS源码
  • podspec文件
  • Package.swift
如果项目维护了脚本工具，新增iOS SPM安装命令。

Step 6: Verify

步骤6：验证

Install dependencies with the repository's existing package manager.
Then 
cd
into the example or test app directory that contains 
capacitor.config.*
, run 
npx cap sync
(or the repository's equivalent runner) there, and build that same app.
使用仓库现有的包管理器安装依赖。
然后进入包含
capacitor.config.*
的示例或测试应用目录，在该目录下运行
npx cap sync
（或仓库对应的等效命令），然后构建该应用。

Error Handling

错误处理

  • Start with the Swift package resolver: check the target path and package dependency names first.
  • Verify bridge registration by matching the class name, 
    identifier
    , and 
    jsName
    against the exported API.
  • For unsupported CocoaPods dependencies, replace them with SPM-compatible packages or keep CocoaPods for that dependency.
  • 优先排查Swift包解析器：首先检查target路径和包依赖名称
  • 通过对比类名、
    identifier
    、
    jsName
    与导出API，验证桥接注册是否正确
  • 对于不支持的CocoaPods依赖，可以替换为兼容SPM的包，或继续使用CocoaPods管理该依赖