capacitor-app-spm-migration

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Capacitor App: CocoaPods → SPM Migration

Capacitor应用：从CocoaPods迁移至SPM

Migrate an existing Capacitor app project's iOS dependency management from CocoaPods to Swift Package Manager (SPM). The migration is destructive — the existing

ios/

folder is deleted and re-scaffolded, then user-authored files are restored from a temporary backup.

将现有Capacitor应用项目的iOS依赖管理从CocoaPods迁移到Swift Package Manager（SPM）。该迁移具有破坏性——会删除现有

ios/

文件夹并重新搭建，之后从临时备份恢复用户编写的文件。

Prerequisites

前置条件

Requirement	Version
Capacitor	6+
Node.js	18+
Xcode	15+
CocoaPods	installed (only used for verification before deletion)

The project must be a Capacitor app (not a plugin) and must currently use CocoaPods (

ios/App/Podfile

exists).

要求	版本
Capacitor	6+
Node.js	18+
Xcode	15+
CocoaPods	已安装（仅用于删除前的验证）

项目必须是Capacitor app（而非插件），且当前使用CocoaPods（存在

ios/App/Podfile

文件）。

Procedures

操作步骤

Step 1: Verify Project State

步骤1：验证项目状态

Verify the project is a Capacitor app, not a plugin. Confirm
```
package.json
```
lists
```
@capacitor/ios
```
in
```
dependencies
```
and the project root contains a
```
capacitor.config.*
```
file.
Verify the project currently uses CocoaPods. The file
```
ios/App/Podfile
```
must exist. If it does not exist and
```
ios/App/CapApp-SPM/Package.swift
```
exists, the project is already on SPM — abort and inform the user.
Read
```
@capacitor/core
```
version from
```
package.json
```
(
```
dependencies
```
or
```
devDependencies
```
). Confirm the major version is 6 or higher. If lower, abort and direct the user to the
```
capacitor-app-upgrades
```
skill first.
Verify the working tree is clean. Run
```
git status --porcelain
```
— if the output is non-empty, instruct the user to commit or stash changes before proceeding. The migration is destructive and must be reversible via
```
git checkout
```
.

验证项目为Capacitor app，而非插件。确认
```
package.json
```
的
```
dependencies
```
中包含
```
@capacitor/ios
```
，且项目根目录存在
```
capacitor.config.*
```
文件。
验证项目当前使用CocoaPods。必须存在
```
ios/App/Podfile
```
文件。若该文件不存在，但存在
```
ios/App/CapApp-SPM/Package.swift
```
，则项目已采用SPM——终止操作并告知用户。
从
```
package.json
```
的
```
dependencies
```
或
```
devDependencies
```
中读取
```
@capacitor/core
```
版本。确认主版本为6或更高。若版本较低，终止操作并引导用户先使用
```
capacitor-app-upgrades
```
技能进行升级。
验证工作树已清理。运行
```
git status --porcelain
```
——若输出非空，指导用户在继续前提交或暂存更改。迁移具有破坏性，必须可通过
```
git checkout
```
撤销。

Step 2: Inventory Installed Capacitor Plugins

步骤2：盘点已安装的Capacitor插件

Read

package.json

and record every installed Capacitor plugin under

dependencies

. Match these prefixes:

```
@capacitor/*
```
(official plugins)
```
@capawesome/*
```
and
```
@capawesome-team/*
```
```
@capacitor-community/*
```
```
@capacitor-firebase/*
```
```
@capacitor-mlkit/*
```
```
@revenuecat/*
```
Any other package with
```
"capacitor"
```
in its
```
package.json
```
```
keywords
```
array

Record each plugin's package name and installed version. This list is used in Step 8 to verify all plugins resolve under SPM after re-sync.

读取

package.json

，记录

dependencies

下所有已安装的Capacitor插件。匹配以下前缀：

```
@capacitor/*
```
（官方插件）
```
@capawesome/*
```
和
```
@capawesome-team/*
```
```
@capacitor-community/*
```
```
@capacitor-firebase/*
```
```
@capacitor-mlkit/*
```
```
@revenuecat/*
```
其他在
```
package.json
```
的
```
keywords
```
数组中包含
```
"capacitor"
```
的包

记录每个插件的包名和已安装版本。此列表将用于步骤8，以验证重新同步后所有插件均可在SPM下解析。

Step 3: Identify Files to Preserve

步骤3：确定需保留的文件

Build a checklist of files in

ios/

that contain user-authored content and must survive the re-scaffold. For each path below, check whether the file exists. Record only the paths that exist.

Path (relative to project root)	Purpose
`ios/App/App/Info.plist`	App permissions, URL schemes, bundle config, custom keys
`ios/App/App/AppDelegate.swift`	Custom app lifecycle code
`ios/App/App/SceneDelegate.swift`	Custom scene lifecycle code (if present)
`ios/App/App/Assets.xcassets/`	App icon, splash assets, color sets
`ios/App/App/Base.lproj/`	LaunchScreen and Main storyboards
`ios/App/App/App.entitlements`	Push, App Groups, Associated Domains, Keychain Sharing
`ios/App/App/GoogleService-Info.plist`	Firebase configuration (if Firebase plugins are installed)
`ios/App/App/*.xcconfig`	Build configuration overrides
`ios/App/App.xcodeproj/project.pbxproj`	Source for extracting signing values in Step 5

Additionally, scan

ios/App/App/

for any other
.swift
files beyond

AppDelegate.swift

and

SceneDelegate.swift

. These are user-authored Swift sources (e.g., custom Notification Service Extensions, custom view controllers) and must also be preserved.

If the project contains a Notification Service Extension or other Xcode targets under

ios/App/

(e.g.,

ios/App/NotificationService/

), record those directories as well.

列出

ios/

目录中包含用户自定义内容、需在重新搭建后保留的文件清单。检查以下每个路径是否存在，仅记录存在的路径。

路径（相对于项目根目录）	用途
`ios/App/App/Info.plist`	应用权限、URL Scheme、Bundle配置、自定义键
`ios/App/App/AppDelegate.swift`	自定义应用生命周期代码
`ios/App/App/SceneDelegate.swift`	自定义场景生命周期代码（若存在）
`ios/App/App/Assets.xcassets/`	应用图标、启动页资源、颜色集
`ios/App/App/Base.lproj/`	启动页和主故事板
`ios/App/App/App.entitlements`	推送通知、App Groups、关联域名、钥匙串共享
`ios/App/App/GoogleService-Info.plist`	Firebase配置（若安装了Firebase插件）
`ios/App/App/*.xcconfig`	构建配置覆盖项
`ios/App/App.xcodeproj/project.pbxproj`	用于步骤5提取签名值的源文件

此外，扫描

ios/App/App/

目录中除

AppDelegate.swift

和

SceneDelegate.swift

外的所有其他
.swift
文件。这些是用户编写的Swift源码（例如自定义通知服务扩展、自定义视图控制器），也需保留。

若项目包含通知服务扩展或

ios/App/

下的其他Xcode目标（例如

ios/App/NotificationService/

），也需记录这些目录。

Step 4: Back Up Preserved Files

步骤4：备份需保留的文件

Create the backup directory:
bash
```
mkdir -p .spm-migration-backup
```

Add

.spm-migration-backup/

.gitignore

to prevent accidental commits:

diff

 # iOS files
+.spm-migration-backup/

Copy each file recorded in Step 3 into

.spm-migration-backup/

, preserving the relative path. For example:

bash

mkdir -p .spm-migration-backup/ios/App/App
cp ios/App/App/Info.plist .spm-migration-backup/ios/App/App/Info.plist
cp ios/App/App/AppDelegate.swift .spm-migration-backup/ios/App/App/AppDelegate.swift
cp -R ios/App/App/Assets.xcassets .spm-migration-backup/ios/App/App/Assets.xcassets
cp -R ios/App/App/Base.lproj .spm-migration-backup/ios/App/App/Base.lproj

Repeat for every file/directory identified in Step 3. Use

cp -R

for directories.

Always copy the full
```
ios/App/App.xcodeproj/project.pbxproj
```
to
```
.spm-migration-backup/ios/App/App.xcodeproj/project.pbxproj
```
, even though the file itself will not be restored. Step 5 reads it to extract signing values, and Step 11 may reference it for capability reconfiguration.

创建备份目录：
bash
```
mkdir -p .spm-migration-backup
```

将

.spm-migration-backup/

添加到

.gitignore

中，防止意外提交：

diff

 # iOS files
+.spm-migration-backup/

将步骤3中记录的每个文件复制到

.spm-migration-backup/

，保留相对路径。例如：

bash

mkdir -p .spm-migration-backup/ios/App/App
cp ios/App/App/Info.plist .spm-migration-backup/ios/App/App/Info.plist
cp ios/App/App/AppDelegate.swift .spm-migration-backup/ios/App/App/AppDelegate.swift
cp -R ios/App/App/Assets.xcassets .spm-migration-backup/ios/App/App/Assets.xcassets
cp -R ios/App/App/Base.lproj .spm-migration-backup/ios/App/App/Base.lproj

对步骤3中识别的每个文件/目录重复此操作。目录使用

cp -R

命令。

务必将完整的
```
ios/App/App.xcodeproj/project.pbxproj
```
复制到
```
.spm-migration-backup/ios/App/App.xcodeproj/project.pbxproj
```
，即使该文件本身不会被恢复。步骤5会读取它来提取签名值，步骤11可能会参考它重新配置功能。

Step 5: Extract Signing & Bundle Configuration

步骤5：提取签名与Bundle配置

Read

.spm-migration-backup/ios/App/App.xcodeproj/project.pbxproj

and extract the values of the following build settings from the

App

target's

XCBuildConfiguration

blocks (both

Debug

and

Release

). Search for each key and record the assigned value:

```
PRODUCT_BUNDLE_IDENTIFIER
```
```
DEVELOPMENT_TEAM
```
```
CODE_SIGN_STYLE
```
(e.g.,
```
Automatic
```
or
```
Manual
```
)

PROVISIONING_PROFILE_SPECIFIER

(only if

CODE_SIGN_STYLE = Manual

)

CODE_SIGN_IDENTITY

(only if

CODE_SIGN_STYLE = Manual

)

```
MARKETING_VERSION
```
```
CURRENT_PROJECT_VERSION
```
```
IPHONEOS_DEPLOYMENT_TARGET
```
```
SWIFT_VERSION
```

Also record the list of capabilities by reading

.spm-migration-backup/ios/App/App/App.entitlements

(if present). Note all top-level keys (e.g.,

aps-environment

com.apple.security.application-groups

com.apple.developer.associated-domains

Save the extracted values in memory for use in Step 9.

读取

.spm-migration-backup/ios/App/App.xcodeproj/project.pbxproj

，从

App

目标的

XCBuildConfiguration

块（

Debug

和

Release

均需）中提取以下构建设置的值。搜索每个键并记录其赋值：

```
PRODUCT_BUNDLE_IDENTIFIER
```
```
DEVELOPMENT_TEAM
```
```
CODE_SIGN_STYLE
```
（例如
```
Automatic
```
或
```
Manual
```
）

PROVISIONING_PROFILE_SPECIFIER

（仅当

CODE_SIGN_STYLE = Manual

时）

CODE_SIGN_IDENTITY

（仅当

CODE_SIGN_STYLE = Manual

时）

```
MARKETING_VERSION
```
```
CURRENT_PROJECT_VERSION
```
```
IPHONEOS_DEPLOYMENT_TARGET
```
```
SWIFT_VERSION
```

同时，通过读取

.spm-migration-backup/ios/App/App/App.entitlements

（若存在）记录功能列表。记录所有顶级键（例如

aps-environment

、

com.apple.security.application-groups

、

com.apple.developer.associated-domains

）。

将提取的值保存到内存中，供步骤9使用。

Step 6: Delete the

ios/

Folder

步骤6：删除

ios/

文件夹

Confirm with the user that the working tree is committed (re-run

git status --porcelain

if necessary) and that

.spm-migration-backup/

contains every file from Step 3. Then run:

bash

rm -rf ios

确认用户已提交工作树（必要时重新运行

git status --porcelain

），且

.spm-migration-backup/

包含步骤3中的所有文件。然后运行：

bash

rm -rf ios

Step 7: Re-scaffold iOS with SPM

步骤7：使用SPM重新搭建iOS项目

Run:

bash

npx cap add ios --packagemanager SPM

This creates a new

ios/

directory with the SPM-based scaffold. The new structure includes

ios/App/CapApp-SPM/Package.swift

instead of

ios/App/Podfile

运行：

bash

npx cap add ios --packagemanager SPM

此命令会创建新的

ios/

目录，基于SPM搭建项目。新结构包含

ios/App/CapApp-SPM/Package.swift

，而非

ios/App/Podfile

。

Step 8: Restore Preserved Files

步骤8：恢复备份文件

Copy each backed-up file from

.spm-migration-backup/

back to its original path under

ios/

, overwriting the scaffolded defaults. For example:

bash

cp .spm-migration-backup/ios/App/App/Info.plist ios/App/App/Info.plist
cp .spm-migration-backup/ios/App/App/AppDelegate.swift ios/App/App/AppDelegate.swift
cp -R .spm-migration-backup/ios/App/App/Assets.xcassets ios/App/App/Assets.xcassets
cp -R .spm-migration-backup/ios/App/App/Base.lproj ios/App/App/Base.lproj

Repeat for every file/directory backed up in Step 4, except

ios/App/App.xcodeproj/project.pbxproj

— that file is not restored. The new

project.pbxproj

is required for SPM integration; signing values from the old one are reapplied via Step 9.

If any preserved file did not exist in the new scaffold (e.g.,

App.entitlements

GoogleService-Info.plist

, custom Swift files), the file must additionally be added to the Xcode project membership in Step 10.

将

.spm-migration-backup/

中的每个备份文件复制回

ios/

下的原路径，覆盖搭建生成的默认文件。例如：

bash

cp .spm-migration-backup/ios/App/App/Info.plist ios/App/App/Info.plist
cp .spm-migration-backup/ios/App/App/AppDelegate.swift ios/App/App/AppDelegate.swift
cp -R .spm-migration-backup/ios/App/App/Assets.xcassets ios/App/App/Assets.xcassets
cp -R .spm-migration-backup/ios/App/App/Base.lproj ios/App/App/Base.lproj

对步骤4中备份的每个文件/目录重复此操作，除了

ios/App/App.xcodeproj/project.pbxproj

——该文件不恢复。新的

project.pbxproj

是SPM集成所必需的；旧文件中的签名值将通过步骤9重新应用。

若某些备份文件在新搭建的项目中不存在（例如

App.entitlements

、

GoogleService-Info.plist

、自定义Swift文件），则需在步骤10中将这些文件添加到Xcode项目成员中。

Step 9: Reapply Signing & Bundle Configuration

步骤9：重新应用签名与Bundle配置

Edit the new

ios/App/App.xcodeproj/project.pbxproj

and reapply the values extracted in Step 5. For each setting, find every occurrence in the

App

target's

XCBuildConfiguration

blocks and replace the scaffolded value with the recorded value.

Apply this diff pattern for each setting (example for

PRODUCT_BUNDLE_IDENTIFIER

diff

-				PRODUCT_BUNDLE_IDENTIFIER = com.example.app;
+				PRODUCT_BUNDLE_IDENTIFIER = <RECORDED_BUNDLE_ID>;

Settings to reapply (use

replace_all

semantics — update all occurrences across

Debug

and

Release

configurations):

```
PRODUCT_BUNDLE_IDENTIFIER
```
```
DEVELOPMENT_TEAM
```
```
CODE_SIGN_STYLE
```
```
PROVISIONING_PROFILE_SPECIFIER
```
(only if manual signing)
```
CODE_SIGN_IDENTITY
```
(only if manual signing)
```
MARKETING_VERSION
```
```
CURRENT_PROJECT_VERSION
```

IPHONEOS_DEPLOYMENT_TARGET

in the recorded values is higher than the scaffolded value, update it. If lower, keep the scaffolded value (the new scaffold targets a supported minimum).

编辑新的

ios/App/App.xcodeproj/project.pbxproj

，重新应用步骤5中提取的值。对于每个设置，找到

App

目标的

XCBuildConfiguration

块中的所有匹配项，将搭建生成的值替换为记录的值。

对每个设置应用以下差异模式（以

PRODUCT_BUNDLE_IDENTIFIER

为例）：

diff

-				PRODUCT_BUNDLE_IDENTIFIER = com.example.app;
+				PRODUCT_BUNDLE_IDENTIFIER = <RECORDED_BUNDLE_ID>;

需重新应用的设置（使用

replace_all

语义——更新

Debug

和

Release

配置中的所有匹配项）：

```
PRODUCT_BUNDLE_IDENTIFIER
```
```
DEVELOPMENT_TEAM
```
```
CODE_SIGN_STYLE
```
```
PROVISIONING_PROFILE_SPECIFIER
```
（仅手动签名时）
```
CODE_SIGN_IDENTITY
```
（仅手动签名时）
```
MARKETING_VERSION
```
```
CURRENT_PROJECT_VERSION
```

若记录的

IPHONEOS_DEPLOYMENT_TARGET

值高于搭建生成的值，则更新它。若低于，则保留搭建生成的值（新搭建的项目针对受支持的最低版本）。

Step 10: Add Restored Custom Files to the Xcode Project

步骤10：将恢复的自定义文件添加到Xcode项目

The new

project.pbxproj

only references files that the scaffold created. Files restored in Step 8 that did not exist in the scaffold (e.g.,

App.entitlements

GoogleService-Info.plist

, custom Swift files, Notification Service Extension targets) are present on disk but invisible to Xcode until they are added to the project's

PBXBuildFile

PBXFileReference

, and

PBXGroup

entries.

For each custom file that was not part of the scaffold, instruct the user to perform the following one-time action in Xcode (the SPM scaffold has no

App.xcworkspace

— open

App.xcodeproj

directly):

Open the project:

npx cap open ios

(or

open ios/App/App.xcodeproj

In the Xcode Project Navigator, right-click the
```
App
```
group and choose Add Files to "App"….
Select each restored custom file (e.g.,
```
App.entitlements
```
,
```
GoogleService-Info.plist
```
, custom
```
.swift
```
files).
Ensure Copy items if needed is unchecked and the
```
App
```
target is checked.

For the

App.entitlements

file specifically, also set the

CODE_SIGN_ENTITLEMENTS

build setting in

ios/App/App.xcodeproj/project.pbxproj

. Apply this diff pattern in both

Debug

and

Release

XCBuildConfiguration

blocks for the

App

target:

diff

 				CODE_SIGN_STYLE = Automatic;
+				CODE_SIGN_ENTITLEMENTS = App/App.entitlements;
 				CURRENT_PROJECT_VERSION = 1;

If the project had additional Xcode targets (e.g., a Notification Service Extension under

ios/App/NotificationService/

), the user must recreate those targets in Xcode. SPM scaffolding does not regenerate non-

App

targets. Inform the user explicitly.

新的

project.pbxproj

仅引用搭建生成的文件。步骤8中恢复的、不属于搭建内容的文件（例如

App.entitlements

、

GoogleService-Info.plist

、自定义Swift文件、通知服务扩展目标）已存在于磁盘，但在添加到项目的

PBXBuildFile

、

PBXFileReference

和

PBXGroup

条目之前，Xcode无法识别它们。

对于每个不属于搭建内容的自定义文件，指导用户在Xcode中执行以下一次性操作（SPM搭建的项目没有

App.xcworkspace

——直接打开

App.xcodeproj

）：

打开项目：

npx cap open ios

（或

open ios/App/App.xcodeproj

）。

在Xcode项目导航器中，右键点击
```
App
```
组，选择Add Files to "App"…。
选择每个恢复的自定义文件（例如
```
App.entitlements
```
、
```
GoogleService-Info.plist
```
、自定义
```
.swift
```
文件）。
确保Copy items if needed已取消勾选，且
```
App
```
目标已勾选。

对于

App.entitlements

文件，还需在

ios/App/App.xcodeproj/project.pbxproj

中设置

CODE_SIGN_ENTITLEMENTS

构建设置。在

App

目标的

Debug

和

Release

XCBuildConfiguration

块中应用以下差异模式：

diff

 				CODE_SIGN_STYLE = Automatic;
+				CODE_SIGN_ENTITLEMENTS = App/App.entitlements;
 				CURRENT_PROJECT_VERSION = 1;

若项目包含其他Xcode目标（例如

ios/App/NotificationService/

下的通知服务扩展），用户必须在Xcode中重新创建这些目标。SPM搭建不会重新生成非

App

目标。需明确告知用户。

Step 11: Reconfigure Capabilities

步骤11：重新配置功能

For each capability key recorded from

App.entitlements

in Step 5, verify the corresponding capability is enabled in Xcode:

Open
```
ios/App/App.xcodeproj
```
via
```
npx cap open ios
```
.
Select the
```
App
```
target → Signing & Capabilities tab.

For each entitlement key, add the matching capability via the + Capability button:

```
aps-environment
```
→ Push Notifications
```
com.apple.security.application-groups
```
→ App Groups
```
com.apple.developer.associated-domains
```
→ Associated Domains
```
keychain-access-groups
```
→ Keychain Sharing
```
com.apple.developer.in-app-payments
```
→ Apple Pay
```
com.apple.developer.icloud-services
```
→ iCloud

This is the only step that requires Xcode interaction. Inform the user explicitly that this step must be done manually.

对于步骤5中从

App.entitlements

记录的每个功能键，验证Xcode中是否已启用相应功能：

通过
```
npx cap open ios
```
打开
```
ios/App/App.xcodeproj
```
。
选择
```
App
```
目标 → Signing & Capabilities标签页。

对于每个权限键，通过**+ Capability**按钮添加匹配的功能：

```
aps-environment
```
→ Push Notifications
```
com.apple.security.application-groups
```
→ App Groups
```
com.apple.developer.associated-domains
```
→ Associated Domains
```
keychain-access-groups
```
→ Keychain Sharing
```
com.apple.developer.in-app-payments
```
→ Apple Pay
```
com.apple.developer.icloud-services
```
→ iCloud

这是唯一需要Xcode交互的步骤。需明确告知用户此步骤必须手动完成。

Step 12: Re-sync Plugins

步骤12：重新同步插件

Run:

bash

npm install
npx cap sync ios

npx cap sync ios

updates

ios/App/CapApp-SPM/Package.swift

to include every Capacitor plugin recorded in Step 2. Watch for warnings — any plugin without SPM support will be reported here.

If a plugin is reported as incompatible with SPM, inform the user. The user must either:

Wait for upstream SPM support from the plugin maintainer, or
Fork the plugin and add SPM support using the
```
capacitor-plugin-spm-support
```
skill, or
Remove the plugin from the project.

运行：

bash

npm install
npx cap sync ios

npx cap sync ios

会更新

ios/App/CapApp-SPM/Package.swift

，包含步骤2中记录的所有Capacitor插件。注意警告——任何不支持SPM的插件都会在此处被报告。

若插件被报告为与SPM不兼容，告知用户。用户需选择以下操作之一：

等待插件维护者提供上游SPM支持，或
Fork该插件并使用
```
capacitor-plugin-spm-support
```
技能添加SPM支持，或
从项目中移除该插件。

Step 13: Verify the Build

步骤13：验证构建

Open the project in Xcode and resolve SPM packages:
bash
```
npx cap open ios
```
In Xcode, File → Packages → Resolve Package Versions (or wait for automatic resolution on open).
Build for a simulator from the command line to confirm everything compiles:
bash
```
npx cap run ios
```
Verify the app launches and that previously working features (push notifications, deep links, Firebase, etc.) still function.

在Xcode中打开项目并解析SPM包：
bash
```
npx cap open ios
```
在Xcode中，选择File → Packages → Resolve Package Versions（或等待打开时自动解析）。
从命令行针对模拟器构建，确认所有内容均可编译：
bash
```
npx cap run ios
```
验证应用可启动，且之前正常工作的功能（推送通知、深度链接、Firebase等）仍能正常运行。

Step 14: Cleanup

步骤14：清理

Once the build is verified and the app runs correctly:

Delete the backup directory:
bash
```
rm -rf .spm-migration-backup
```
Remove the
```
.spm-migration-backup/
```
entry from
```
.gitignore
```
.
Verify no CocoaPods artifacts remain:
bash
```
find ios -name 'Podfile*' -o -name 'Pods' -o -name '*.xcworkspace'
```
If any results appear, delete them. The SPM workflow uses
```
App.xcodeproj
```
directly — there is no
```
App.xcworkspace
```
.

Commit the migration:

bash

git add -A
git commit -m "chore(ios): migrate from CocoaPods to Swift Package Manager"

确认构建成功且应用正常运行后：

删除备份目录：
bash
```
rm -rf .spm-migration-backup
```
从
```
.gitignore
```
中移除
```
.spm-migration-backup/
```
条目。
验证无CocoaPods残留文件：
bash
```
find ios -name 'Podfile*' -o -name 'Pods' -o -name '*.xcworkspace'
```
若有结果，删除它们。SPM工作流直接使用
```
App.xcodeproj
```
——不存在
```
App.xcworkspace
```
。

提交迁移更改：

bash

git add -A
git commit -m "chore(ios): migrate from CocoaPods to Swift Package Manager"

Error Handling

错误处理

npx cap add ios --packagemanager SPM
fails with "ios platform already exists" — Step 6 was not completed. Re-run
```
rm -rf ios
```
and retry.
npx cap sync ios
reports a plugin without SPM support — that plugin cannot be used under SPM until it ships a
```
Package.swift
```
. Inform the user and pause the migration; do not silently drop the plugin.
Build fails with "Module 'X' not found" — the plugin's SPM package was not resolved. Run File → Packages → Reset Package Caches in Xcode, then File → Packages → Resolve Package Versions.
Build fails with code signing errors — the values reapplied in Step 9 are missing or incorrect. Re-read
```
.spm-migration-backup/ios/App/App.xcodeproj/project.pbxproj
```
and confirm
```
DEVELOPMENT_TEAM
```
and
```
PRODUCT_BUNDLE_IDENTIFIER
```
were applied to both
```
Debug
```
and
```
Release
```
configurations.
Push notifications stop working after migration — the Push Notifications capability was not re-added in Step 11, or
```
App.entitlements
```
is not linked via
```
CODE_SIGN_ENTITLEMENTS
```
(Step 10).
Firebase initializes but no data appears —
```
GoogleService-Info.plist
```
was restored to disk but not added to the Xcode project's target membership in Step 10.
Custom Notification Service Extension target is missing — non-
```
App
```
targets are not regenerated by
```
npx cap add ios
```
. Recreate the target manually in Xcode and re-add its source files.
The user reports they want to revert — because Step 1 verified a clean working tree, the entire migration can be undone with
```
git checkout -- .
```
followed by
```
git clean -fd ios .spm-migration-backup
```
.

npx cap add ios --packagemanager SPM
失败，提示"ios platform already exists" —— 步骤6未完成。重新运行
```
rm -rf ios
```
后重试。
npx cap sync ios
报告插件不支持SPM —— 该插件在提供
```
Package.swift
```
前无法在SPM下使用。告知用户并暂停迁移；请勿静默移除插件。
构建失败，提示"Module 'X' not found" —— 插件的SPM包未解析。在Xcode中选择File → Packages → Reset Package Caches，然后选择File → Packages → Resolve Package Versions。
构建失败，出现签名错误 —— 步骤9中重新应用的值缺失或不正确。重新读取
```
.spm-migration-backup/ios/App/App.xcodeproj/project.pbxproj
```
，确认
```
DEVELOPMENT_TEAM
```
和
```
PRODUCT_BUNDLE_IDENTIFIER
```
已应用到Debug和Release两种配置。
迁移后推送通知停止工作 —— 步骤11中未重新添加Push Notifications功能，或未通过
```
CODE_SIGN_ENTITLEMENTS
```
链接
```
App.entitlements
```
（步骤10）。
Firebase初始化但无数据显示 ——
```
GoogleService-Info.plist
```
已恢复到磁盘，但未在步骤10中添加到Xcode项目的目标成员。
自定义通知服务扩展目标缺失 ——
```
npx cap add ios
```
不会重新生成非
```
App
```
目标。在Xcode中手动重新创建目标并重新添加其源文件。
用户希望回滚 —— 由于步骤1已验证工作树干净，可通过
```
git checkout -- . && git clean -fd ios .spm-migration-backup
```
撤销整个迁移。

capacitor-app-spm-migration

Original

Translation

Capacitor App: CocoaPods → SPM Migration

Capacitor应用：从CocoaPods迁移至SPM

Prerequisites

前置条件

Procedures

操作步骤

Step 1: Verify Project State

步骤1：验证项目状态

Step 2: Inventory Installed Capacitor Plugins

步骤2：盘点已安装的Capacitor插件

Step 3: Identify Files to Preserve

步骤3：确定需保留的文件

Step 4: Back Up Preserved Files

步骤4：备份需保留的文件

Step 5: Extract Signing & Bundle Configuration

步骤5：提取签名与Bundle配置

Step 6: Delete the ios/ Folder

步骤6：删除ios/文件夹

Step 7: Re-scaffold iOS with SPM

步骤7：使用SPM重新搭建iOS项目

Step 8: Restore Preserved Files

步骤8：恢复备份文件

Step 9: Reapply Signing & Bundle Configuration

步骤9：重新应用签名与Bundle配置

Step 10: Add Restored Custom Files to the Xcode Project

步骤10：将恢复的自定义文件添加到Xcode项目

Step 11: Reconfigure Capabilities

步骤11：重新配置功能

Step 12: Re-sync Plugins

步骤12：重新同步插件

Step 13: Verify the Build

步骤13：验证构建

Step 14: Cleanup

步骤14：清理

Error Handling

错误处理

Related Skills

相关技能

Step 6: Delete the
`ios/`
Folder

步骤6：删除
`ios/`
文件夹