cordova-to-capacitor

从 Cordova 迁移到 Capacitor

逐步将 Cordova 应用迁移到 Capacitor：先迁移 Capacitor，再逐个迁移插件，最后移除 Cordova。

适用场景

以下情况请使用：

• 存在 config.xml、platforms/、plugins/、cordova-android/cordova-ios 或 cordova-plugin-*，且用户想迁移到 Capacitor。
• 代码等待 deviceready，或调用 navigator.camera、window.plugins.*、cordova.plugins.*、@awesome-cordova-plugins/*、@ionic-native/*。
• 迁移后：首次启动时数据丢失、Cordova 插件行为缺失，或 Capacitor 9 构建错误引用 Cordova 符号。

以下情况请勿使用：

• 将 Cordova 插件的 Java/Objective-C 重写为 Capacitor 插件（插件级移植）→ 遵循 Capacitor 插件文档；使用 capacitor-plugins 查找现有替代方案。
• 升级 Capacitor 主版本 → 使用 capacitor-app-upgrades。
• 替换 Appflow Live Updates（cordova-plugin-ionic）→ 使用 ionic-appflow-migration + capgo-live-updates。
• 框架构建配置（Angular 输出路径、Vite）→ 使用 framework-to-capacitor。

实时项目快照

当前与迁移相关的软件包： !node -e "const fs=require('fs');if(!fs.existsSync('package.json'))process.exit(0);const pkg=JSON.parse(fs.readFileSync('package.json','utf8'));const out=[];for(const section of ['dependencies','devDependencies']){for(const [name,version] of Object.entries(pkg[section]||{})){if(name.includes('cordova')||name.includes('phonegap')||name.startsWith('@capacitor/')||name.startsWith('@capgo/')||name.startsWith('@ionic-native/')||name.startsWith('@awesome-cordova-plugins/')||name.startsWith('@ionic-enterprise/'))out.push(section+'.'+name+'='+version)}}if(pkg.cordova)out.push('cordova.plugins='+Object.keys(pkg.cordova.plugins||{}).join(','));console.log(out.sort().join('\n'))"

相关配置和平台路径： !find . -maxdepth 3 -not -path '*/node_modules/*' \( -name 'config.xml' -o -name 'capacitor.config.json' -o -name 'capacitor.config.ts' -o -name 'capacitor.config.js' -o -path './ios' -o -path './android' -o -path './platforms' -o -path './plugins' -o -name 'www' \)

影响迁移决策的关键差异

• Capacitor 原生项目（ios/、android/）是需要提交并编辑的源代码；npx cap sync 不会重新生成这些项目。Cordova 的 platforms/ 则是构建产物。
• 除了 cap sync 对 Cordova 插件所做的处理外，Capacitor 在构建时不会应用 config.xml 或插件的 <config-file> / <edit-config> 修改。权限、权利配置和 Info.plist 键需要手动一次性修改。
• Cordova 插件在 Capacitor 中仍可使用（通过 npm 安装，并在 cap sync 时应用）。安装钩子和 <variable> 安装提示不会运行；请通过 capacitor.config.* 中的 cordova.preferences 设置变量。
• 来源变更：默认情况下，应用在 iOS 上通过 capacitor://localhost 提供，在 Android 上通过 https://localhost 提供。现有的 localStorage、IndexedDB、Cookie 和服务工作线程数据都与旧来源绑定，因此更新后看起来会“丢失”，除非保留原有方案（参见 references/config-and-data.md）。
• 不需要 deviceready。导入后即可使用插件；对于仍在使用的 Cordova 插件，deviceready 仍会触发，因为 Capacitor 的 Cordova 层会注入 cordova.js。

Capacitor 9：Cordova 运行时为可选项

在 Capacitor 9 中，只有安装了至少一个 Cordova 插件时，npx cap sync 才会接入 Cordova 兼容层：

• Android：没有 Cordova 插件时，capacitor-cordova-android / capacitor-cordova-android-plugins 模块会从 settings.gradle 和 app/build.gradle 中移除。
• iOS：CapacitorCordova 不再添加到 Podfile 或 Package.swift 中。

影响：

• 移除最后一个 Cordova 插件后，应用体积会缩小，也会移除 cordova.js——这是好事；但如果应用代码或原生代码引用了 Cordova 符号（com.getcapacitor.cordova.CordovaPlugin、CDVPlugin、CDVPluginHandleOpenURL、window.cordova），且未安装 Cordova 插件，就会编译失败或在运行时显示为 undefined。
• 没有配置标志可以强制包含运行时。要么移除这些引用，要么保留一个 Cordova 插件。
• 运行时移除后，JS 中遗留的 deviceready 监听器将永远不会触发。移除最后一个 Cordova 插件前，请先移除这些监听器。
• 在 Capacitor 8 中，运行时始终会打包，因此只有升级时才会遇到此问题；升级到 9 前请先检查。

流程

1. 审核（编辑前向用户报告）：
   • cordova --version、cordova platform ls、cordova plugin ls（或查看 package.json 中的 cordova.plugins）。
   • config.xml：widget id、version、<preference>、<platform> 块、<access>/<allow-navigation>、图标/启动画面。
   • 已安装的 WebView 插件（cordova-plugin-ionic-webview、cordova-plugin-wkwebview-engine）以及当前的 scheme/hostname——这决定了如何保留数据。
   • 每个插件：是否有替代项、是否保留为 Cordova 插件，或是否会阻碍迁移。请参阅 references/plugin-mapping.md。
   • 使用 deviceready、navigator.* Cordova 全局变量、window.plugins、Ionic Native 包装器的代码。
2. 在现有项目中安装 Capacitor，并保留相同的应用 ID：

   npm install @capacitor/core @capacitor/ios @capacitor/android
   npm install -D @capacitor/cli
   npx cap init "<name from config.xml>" <widget id from config.xml> --web-dir www
   

   cap init 会将 config.xml 中的偏好设置读入 Capacitor 配置的 cordova.preferences。确保 Web 构建输出到 webDir（Ionic Angular：www）。
3. 在首次发布前决定如何保留数据（scheme）：references/config-and-data.md。
4. 执行 npm run build && npx cap add ios && npx cap add android。package.json 依赖中列出的 Cordova 插件会安装到新的原生项目中；已知不兼容的插件会跳过并显示警告。
5. 手动移植原生配置：使用说明字符串、权限、entitlements、URL scheme、屏幕方向、启动画面/图标（npx @capacitor/assets generate）。请参阅 references/config-and-data.md。
6. 一次替换一个插件（references/plugin-mapping.md），将回调代码转换为 promise（references/code-patterns.md），运行 npx cap sync，并在每次替换后进行设备测试。
7. 没有任何内容依赖 Cordova 后，将其移除（参见“移除”）。没有替代项的 Cordova 插件可以保留；它们仍可正常工作。
8. Capacitor 构建稳定后，提供 Capgo 实时更新（capgo-live-updates）。

移除

只有在两个平台上都验证了所有流程之后，才能执行：

npm uninstall cordova cordova-ios cordova-android
npm uninstall cordova-plugin-ionic-webview cordova-plugin-splashscreen cordova-plugin-statusbar cordova-plugin-ionic-keyboard
rm -rf platforms plugins
git mv config.xml config.xml.bak   # keep for reference until release
npx cap sync
grep -rn "deviceready\|cordova\.\|window\.plugins" src --include=*.ts --include=*.js --include=*.tsx --include=*.vue

如果不再有 Cordova 插件，请从 package.json 中移除 cordova 块。不要循环运行 cordova plugin rm；这些命令会编辑你反正要删除的 platforms/。

验证

• npx cap sync 的输出仅列出预期的 Cordova 插件，且没有意外出现的“不兼容”提示。
• npx cap doctor 显示 core、cli、ios、android 的版本一致。
• 在设备上将 Capacitor 构建版本安装到现有商店版本之上（bundle ID 相同，构建号更高），确认用户仍处于登录状态且本地数据仍然存在。
• 在真机上测试每个已迁移的插件（相机、文件、推送令牌、地理位置、购买）。
• Capacitor 9：移除最后一个 Cordova 插件后，grep -rn "CapacitorCordova\|capacitor-cordova-android" ios android 不返回任何内容，且原生构建成功。

错误处理

错误 / 现象	解决方法
同步期间出现 Found 1 incompatible Cordova plugin for ios, skipped install:	该插件在 Capacitor 已知的不兼容列表中；请使用对应的 Capacitor 插件
从 Cordova 构建版本更新后，用户数据 / 登录信息消失	Origin 已更改；设置 server.iosScheme: 'ionic'（旧版 ionic-webview iOS），或匹配旧的 Android scheme/hostname，然后重新发布
deviceready 处理程序始终不运行	使用的是没有 Cordova 插件的 Capacitor 9，或代码依赖 Cordova 全局对象；请直接调用插件
"Camera" plugin is not implemented on ios（任何插件名称都可能出现）	原生项目中未安装该插件；运行 npx cap sync，并检查 npx cap ls
构建时缺少 Cordova 插件变量（如 API 密钥）	将其添加到 capacitor.config.* 中的 cordova.preferences 下，然后运行 npx cap sync
升级到 Capacitor 9 后，Android 出现 cannot find symbol class CordovaPlugin / iOS 出现 No such module 'Cordova'	不再随附 Cordova 运行时；请移除相关引用，或保留一个 Cordova 插件
带有安装钩子的插件不起作用	Capacitor 不会运行这些钩子；请手动复现钩子对文件所做的修改
cap add 后出现白屏	webDir 配置错误，或尚未运行 Web 构建；请运行 npm run build，然后运行 npx cap sync

参考资料

• references/plugin-mapping.md - Cordova 插件到 Capacitor/Capgo 的替换对照表、不兼容列表，以及保留为 Cordova 插件的指南。
• references/config-and-data.md - config.xml 映射、首选项、scheme 和数据保留、权限、启动画面 / 图标。
• references/code-patterns.md - 常见插件从回调到 Promise 的转换。

相关技能：capacitor-plugins、capacitor-app-upgrades、capgo-live-updates、capacitor-app-store。