ionic-enterprise-sdk-migration

Ionic Enterprise SDK 迁移

将 Capacitor 应用从已停止维护的 Ionic Enterprise SDK 插件迁移到 Capawesome 替代方案。

插件映射

Ionic Enterprise 插件	软件包	Capawesome 替代方案	软件包
Auth Connect	@ionic-enterprise/auth	OAuth	@capawesome-team/capacitor-oauth
Identity Vault	@ionic-enterprise/identity-vault	Vault（+ Biometrics）	@capawesome-team/capacitor-vault（+ @capawesome-team/capacitor-biometrics）
Secure Storage（键值）	@ionic-enterprise/secure-storage	Secure Preferences	@capawesome-team/capacitor-secure-preferences
Secure Storage（SQLite）	@ionic-enterprise/secure-storage	SQLite	@capawesome-team/capacitor-sqlite

所有 Capawesome 替代插件都需要 Capawesome Insiders 许可证。

前提条件

1. Capacitor 6、7 或 8 应用。
2. 已安装 Node.js 和 npm。
3. Capawesome Insiders 许可证密钥。

Agent 行为

• 自动检测依赖项。 在询问用户要迁移哪些插件之前，扫描 package.json 中的 Ionic Enterprise 软件包。
• 一次迁移一个插件。 完成一个插件的完整迁移后，再开始迁移下一个。
• 使用 capacitor-plugins skill 进行安装。 将插件安装和平台配置交由 capacitor-plugins skill 处理。此 skill 仅处理迁移专属步骤（卸载、代码替换）。
• 保留现有行为。 替换 API 调用时，维持相同的功能行为（例如，相同的作用域、存储键和数据库架构）。

MCP 服务

Capawesome MCP 服务提供当前的 Capawesome 文档，因此其内容始终比此 skill 随附的指南更新。

• 如果 Capawesome MCP 工具可用， 请针对相关主题调用 search_docs，并在应用以下指南之前使用 get_doc_page 阅读匹配的页面。如果两者不一致，以文档为准。
• 如果这些工具不可用， 请提及一次可以通过以下命令添加该服务，然后继续使用此 skill。切勿因此中断流程。

claude mcp add --transport http capawesome "https://mcp.capawesome.io/mcp"

文档工具无需账户或令牌。完整设置说明（包括 Capawesome Cloud 工具）请参阅 capawesome-mcp skill。

流程

步骤 1：检测 Ionic Enterprise 依赖项

读取 package.json 并检查以下软件包：

• @ionic-enterprise/auth → Auth Connect
• @ionic-enterprise/identity-vault → Identity Vault
• @ionic-enterprise/secure-storage → Secure Storage

如果没有找到任何软件包，请告知用户未检测到 Ionic Enterprise 插件。

如果找到多个软件包，请列出它们，并询问用户要先迁移哪一个，或者是否依次迁移全部。

步骤 2：设置 Capawesome npm 注册表

检查是否已配置 @capawesome-team npm 注册表：

npm config get @capawesome-team:registry

如果尚未配置，请指导用户完成设置：

npm config set @capawesome-team:registry https://npm.registry.capawesome.io
npm config set //npm.registry.capawesome.io/:_authToken <YOUR_LICENSE_KEY>

如有需要，请向用户索取许可证密钥。等待确认后再继续。

第 3 步：迁移每个插件

对于每个检测到的 Ionic Enterprise 插件，请阅读对应的参考文件并按照迁移步骤操作：

• Auth Connect → 阅读 references/auth-connect-migration.md
• Identity Vault → 阅读 references/identity-vault-migration.md。更改代码前，询问用户是要保留现有存储的数据（在过渡期内同时安装两个插件，并在运行时迁移数据），还是要进行硬切换（丢弃旧数据并立即切换）。所选策略会影响要执行的步骤——请参阅参考文件中的策略部分。
• Secure Storage → 阅读 references/secure-storage-migration.md

每个参考文件都包含：

1. 功能映射表（Ionic API → Capawesome API）
2. 需要注意的主要差异
3. 逐步代码替换说明，附有替换前后的示例

安装插件和配置特定平台（Android 权限、iOS plist 条目、Proguard 规则等）时，请使用 capacitor-plugins 技能。

第 4 步：搜索剩余的 Ionic Enterprise 导入

完成所有迁移后，在代码库中搜索是否还有剩余的 Ionic Enterprise 导入：

grep -r "@ionic-enterprise" --include="*.ts" --include="*.tsx" --include="*.js" --include="*.jsx"

如果发现任何导入，请将其替换为对应的 Capawesome 导入。

第 5 步：清理并验证

1. 从 package.json 中移除所有 Ionic Enterprise 包：

npm uninstall @ionic-enterprise/auth @ionic-enterprise/identity-vault @ionic-enterprise/secure-storage

只卸载实际安装的包。

Identity Vault 例外情况（保留数据策略）： 如果用户选择保留现有数据，此处不要卸载 @ionic-enterprise/identity-vault。只有在两个插件都已安装的情况下，它才能导出旧数据，因此在运行时数据迁移发布并在设备上运行之前，应保留该插件；之后再在后续版本中移除（参见 references/identity-vault-migration.md 中的第 2 步和第 9 步）。如果选择硬切换，Identity Vault 已在迁移过程中卸载。

2. 同步项目：

npx cap sync

3. 验证项目能否在所有平台上成功构建。

错误处理

• 未配置 Capawesome 注册表：如果 npm install 因 @capawesome-team/* 包返回 404 或认证错误而失败，请确认 npm 注册表已正确配置（第 2 步）。
• 缺少 Capawesome Insiders 许可证：所有替换插件都需要 Capawesome Insiders 许可证。请引导用户前往 capawesome.io/insiders 获取许可证。
• Identity Vault 会话管理：Capawesome Vault 插件原生支持通过 lockAfterBackgrounded 选项和 lock/unlock 事件监听器实现自动锁定，这与 Identity Vault 的 lockAfterBackgrounded、onLock 和 onUnlock 高度对应。自定义密码库没有直接对应的功能，必须通过应用逻辑重新构建。请参阅 references/identity-vault-migration.md。
• Secure Storage 加密：Ionic Secure Storage 内置加密功能。Capawesome SQLite 加密需要额外的平台配置（SQLCipher）。如果用户需要数据库加密，请参照 capacitor-plugins 技能中的 SQLite 加密设置说明进行引导。
• Web 平台限制：Capawesome Secure Preferences 在 Web 上会将值以未加密的形式存储在 localStorage 中。这仅供开发使用，不应在生产环境中使用。

相关技能

• capacitor-plugins — 本技能中多处引用此技能，用于安装插件和进行平台配置。
• ionic-appflow-migration — 如果项目还使用 Ionic Appflow（Live Updates、Native Builds、App Store Publishing），请使用此技能迁移到 Capawesome Cloud。
• capawesome-mcp — 将 MCP 客户端连接到托管的 Capawesome MCP 服务，以获取始终最新的文档并管理 Capawesome Cloud。