用途:帮助 Capacitor 8.4 → 8.5 的 iOS 项目迁移到 UIScene 生命周期。CLI 迁移器(npx cap migrate)只处理仍与模板一致的项目,本技能针对其余情况:先审计再编辑,在需要判断处询问开发者,合并进现有文件而非替换,项目形态允许时把机械工作交给 CLI。
适用:迁移 Capacitor 8.x iOS 应用到 UIScene;npx cap migrate 报告部分状态并跳过;存在手写 SceneDelegate.swift 或定制 AppDelegate.swift(深链路由、第三方 SDK 转发);审计插件仓库的 UIScene 兼容性;诊断 Xcode 的 “CLIENT OF UIKIT REQUIRES UPDATE” 警告。不适用:Cordova 插件迁移、生成新插件、Capacitor 9+ 迁移、Android 生命周期、与场景生命周期无关的调试。
前提:Capacitor 8.x 项目含 ios/ 平台或 iOS 源码;@capacitor/cli 8.5+;如需构建验证需安装 Xcode。
关键事实:场景采用为可选,无 UIApplicationSceneManifest 时仍走 AppDelegate;一旦存在场景清单,iOS 不再调用 application(:open:options:)、application(:continue:) 及四个前后台 AppDelegate 方法,其中的自定义代码会静默停止运行;SceneDelegateProxy 会以相同载荷重发旧通知,冷启动 URL 在桥接视图出现后送达;新增 .capacitorSceneWillConnect 等通知仅 8.5+ 发送;TmpViewController 与 CapacitorBridge.tmpWindow 已移除,引用即构建错误;8.5 模板在 scene(_:willConnectTo:) 中用代码创建窗口,Main.storyboard 不再提供根视图控制器。
流程:检测仓库类型(应用或插件)→ 检测包管理器与版本 → 按三个信号分类项目状态(eligible / already migrated / partial)→ 审计代码库 → 呈现发现并确认 → 决策点询问 → eligible 走 npx cap migrate,partial 或手写走外科式合并 → 运行 npx cap sync ios 并构建 → 验证清单 → 插件仓库仅审计与建议。
限制:不覆盖、不提交、不暂存、不推送;不重写 node_modules 中第三方插件代码;插件仓库不触碰 Info.plist、AppDelegate.swift 或工程文件;无关联域时不承诺通用链接行为。缺失事实暂未提供。