capacitor-push-notifications

Capacitor 推送通知

通过 @capacitor-firebase/messaging 插件，使用 Firebase Cloud Messaging（FCM）在 Capacitor 应用中设置和使用推送通知。

前置条件

1. Capacitor 6、7 或 8 应用。
2. 已安装 Node.js 和 npm。
3. 一个 Firebase 项目。如有需要，可在 Firebase 控制台中创建。
4. 对于 iOS：拥有付费的 Apple Developer Program 会员资格，并已安装 Xcode。
5. 对于 Android：已安装 Android Studio。
6. 必须未安装 @capacitor/push-notifications——它会与 @capacitor-firebase/messaging 冲突。

Agent 行为

• 逐步引导。 一次引导用户完成一个步骤。切勿一次提出多个无关问题。
• 先自动检测，再提问。 检查项目中的平台（android/、ios/）、构建工具、框架和 package.json 依赖项。只有在无法检测到某项信息时才询问用户。
• 一次只做一个决定。 某个步骤需要用户输入时，只提出一个问题，等待回答后再继续。
• 提供明确选项。 给出具体选项（例如：“要配置主题订阅吗？（是/否）”），而不是开放式问题。

MCP 服务

有两个托管的 MCP 服务提供当前文档，因此它们始终比此技能附带的指南更新：

• Capawesome MCP 服务 — Capawesome 插件、Capawesome CLI 和 Capawesome Cloud。
• Capacitor MCP 服务（非官方）— Capacitor 本身：CLI、capacitor.config 文件、原生 Android 和 iOS 项目，以及官方插件 API。

两者都提供 search_docs 和 get_doc_page，因此调用前请根据主题选择服务。

• 如果 MCP 工具可用，请在负责该主题的服务上调用 search_docs，并使用 get_doc_page 阅读匹配的页面，然后再应用以下指南。如果两者内容有出入，请遵循文档。
• 如果 MCP 工具不可用，请提及一次可以使用以下命令添加这些服务，然后继续使用此技能。切勿因此而停下。

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

文档无需账号或令牌即可使用这两个服务。完整的设置说明（包括 Capawesome Cloud 工具）请参阅 capawesome-mcp 和 capacitor-mcp 技能。

操作步骤

步骤 1：分析项目

通过读取项目文件自动检测以下信息——不要询问用户可以推断出的信息：

1. 平台：检查哪些目录存在（android/、ios/）。这些就是需要配置的平台。
2. 构建工具 / 框架：检查是否存在 vite.config.ts、angular.json、webpack.config.js、next.config.js 等文件。
3. Capacitor 版本：从 package.json 中读取 @capacitor/core 版本。
4. 冲突的插件：检查 package.json 中是否包含 @capacitor/push-notifications。如果存在，请警告用户必须先将其移除才能继续：

   npm uninstall @capacitor/push-notifications
   

步骤 2：设置 Firebase

检查项目中是否已配置 Firebase：

• Android：检查 android/app/google-services.json 是否存在。
• iOS：检查 ios/App/App/GoogleService-Info.plist 是否存在。

如果检测到的平台尚未配置 Firebase，请阅读 references/firebase-setup.md，并引导用户为每个平台完成 Firebase 设置。

步骤 3：安装插件

npm install @capacitor-firebase/messaging firebase
npx cap sync

步骤 4：配置 Android

如果 android/ 不存在，则跳过。

阅读 references/android-setup.md 并应用 Android 专属配置。

步骤 5：配置 iOS

如果 ios/ 不存在，则跳过。

阅读 references/ios-setup.md 并应用 iOS 专属配置。这包括 APNs 密钥/证书设置、AppDelegate.swift 修改，以及启用功能。

第 6 步：配置 Web（如适用）

如果项目面向 Web（通过构建工具配置或用户确认检测），请：

阅读 references/web-setup.md 并应用 Web 专用配置。

第 7 步：配置 Capacitor 插件选项

询问用户是否要自定义 iOS 前台通知的呈现方式。如果是，请更新 capacitor.config.json 或 capacitor.config.ts：

{
  "plugins": {
    "FirebaseMessaging": {
      "presentationOptions": ["alert", "badge", "sound"]
    }
  }
}

可用选项：badge、sound、alert、criticalAlert。默认值为 ["alert", "badge", "sound"]。

第 8 步：添加推送通知代码

阅读 references/implementation.md，并将推送通知代码添加到项目中。调整导入和结构，使其符合用户使用的框架。

实现内容包括：

1. 请求权限
2. 获取 FCM 令牌
3. 监听收到的通知
4. 处理通知点击

第 9 步：配置可选功能

询问用户要启用哪些可选功能：

1. 主题订阅 — 订阅或取消订阅 FCM 主题（仅限 Android/iOS）。
2. 通知渠道 — 创建自定义 Android 通知渠道（仅限 Android SDK 26+）。
3. 令牌刷新监听器 — 监听 FCM 令牌的变化。

对于每项选中的功能，请阅读 references/implementation.md 并应用相关代码。

第 10 步：同步并测试

1. 同步项目：

   npx cap sync
   

2. 阅读 references/testing.md，指导用户通过 Firebase Console 发送测试通知。

错误处理

• @capacitor/push-notifications 冲突：@capacitor-firebase/messaging 插件无法与 @capacitor/push-notifications 共存。请卸载冲突插件：npm uninstall @capacitor/push-notifications && npx cap sync。
• iOS：未收到推送通知：确认 APNs 密钥/证书已上传到 Firebase Console。确认已启用 Push Notifications 和 Background Modes 功能。确认 AppDelegate.swift 包含所需的委托方法。
• iOS：未调用 didRegisterForRemoteNotificationsWithDeviceToken：确保已在 Xcode 的 Signing & Capabilities 下添加 Push Notifications 功能。检查应用的 bundle ID 是否与 Firebase 和 Apple Developer portal 中注册的 ID 一致。
• Android：未收到推送通知：确认 google-services.json 位于 android/app/google-services.json。确认已应用 Google services Gradle 插件。
• Android：通知图标显示为白色方块：通知图标必须是在透明背景上的白色像素。带颜色的应用图标会显示为白色方块。请添加专用的推送通知图标。
• Web：getToken() 失败：确保 VAPID 密钥正确。确保 firebase-messaging-sw.js 位于域名根目录。检查浏览器是否支持 Push API。
• FCM 令牌为 null：确保在调用 getToken() 前已调用 requestPermissions()，且返回值为 granted。在 iOS 上，确认设备不是模拟器（模拟器无法接收推送通知）。
• checkPermissions() 返回 denied：用户已永久拒绝通知权限。请引导用户前往设备设置重新启用（Settings > App > Notifications）。
• Android 13+：未出现权限提示：在 Android 13（API 33）及更高版本中，必须显式调用 requestPermissions()。较早版本的 Android 默认授予通知权限。

相关技能

• capacitor-app-development — 了解 Capacitor 开发的一般主题、故障排除和最佳实践。
• capacitor-plugins — 了解 Capacitor 插件的安装和配置，包括其他 Firebase 插件。
• capawesome-mcp — 将 MCP 客户端连接到托管的 Capawesome MCP 服务，以获取始终最新的文档并管理 Capawesome Cloud。