ionic-shared

Ionic Shared（Capacitor）指南

适用于 Ionic Capacitor 应用的跨框架指南。框架技能（ionic-angular、ionic-react、ionic-vue）会链接到此处的原生插件和内容主题，避免重复编写相同代码。

何时查阅这些参考资料

• Capacitor 配置 / 原生平台：capacitor-config.md
• 环境与 API 密钥（各框架的环境变量、哪些内容可以安全地随应用发布）：environments-and-keys.md
• 持久化存储（@capacitor/preferences）：storage.md
• 主题切换（浅色 / 深色 / 系统）：theming.md
• AdMob 横幅广告：admob.md
• RevenueCat 购买 / 付费墙逻辑：revenuecat.md
• 推送通知：push-notifications.md
• 翻译字符串（TR / EN）：localization-content.md
• App Store / Play Store 提交说明：app-store-notes.md
• 发布前测试清单：testing-checklist.md

硬性规则（适用于所有框架）

• ✅ 使用 Ionic Framework、Capacitor 和框架（Angular / React / Vue）的最新稳定版本。搭建新项目时，不要固定使用旧版主版本——让 npm install <pkg> 解析出最新版本。如有疑问，请通过 npm view <pkg> version 验证。不要在 SKILL.md 示例中写入具体版本号——它们很快就会过时。
• ✅ 从环境变量读取 API 密钥和广告单元 ID，绝不可在源代码中硬编码。移动应用包不是存放机密的容器——应用中只能包含可公开的密钥（RevenueCat SDK 密钥、AdMob 单元 ID、Firebase Web 配置、Sentry DSN）。机密密钥（Stripe sk_…、OpenAI / Anthropic、RevenueCat REST 密钥）必须由后端保管。参见 environments-and-keys.md。
• ✅ 让 isTesting 标记与构建模式关联，不要硬编码为 true。在生产环境中发布 initializeForTesting: true 或 isTesting: true 可能导致 AdMob 账号被封禁。
• ❌ 绝不要直接使用 localStorage——请使用 @capacitor/preferences。
• ❌ 绝不要使用 @ionic/storage——请使用 @capacitor/preferences。
• ❌ 绝不要使用 cordova-plugin-*——请使用对应的 Capacitor 插件。
• ❌ 绝不要使用 ngx-admob-free 或其他已弃用的广告库——请使用 @capacitor-community/admob。
• ❌ 绝不要同步调用 Capacitor 插件方法——始终使用 await。
• ✅ 始终使用 Capacitor.isNativePlatform() 为仅限原生平台的代码添加保护。
• ✅ 安装或更新任何 Capacitor 插件后，始终运行 npx cap sync。

必需的共享库

npm install \
  @capacitor/app \
  @capacitor/preferences \
  @capacitor/push-notifications \
  @capacitor/splash-screen \
  @capacitor/status-bar \
  @revenuecat/purchases-capacitor \
  @capacitor-community/admob \
  swiper

ionic-deep-links（以及任何监听 appUrlOpen / appStateChange 的技能）需要 @capacitor/app，因此它属于共享基线的一部分。

除各框架特定的 i18n 库外，还需安装以下库（参见各框架的 SKILL.md）。