⚠️

重要前提

安装AI Skills的关键前提是：必须科学上网，且开启TUN模式，这一点至关重要，直接决定安装能否顺利完成，在此郑重提醒三遍：科学上网，科学上网，科学上网。查看完整安装教程 →

Capacitor推送通知插件使用指南：Firebase FCM集成与跨平台配置

capacitor-push-notifications by capawesome-team/skills

59 周安装量

9 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/capawesome-team/skills --skill capacitor-push-notifications

开发移动应用 Capacitor

🇨🇳中文介绍

Capacitor 推送通知

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

前提条件

Capacitor 6、7 或 8 应用。
已安装 Node.js 和 npm。
一个 Firebase 项目。如果需要，请在 Firebase 控制台创建一个。
iOS 平台：付费的 Apple Developer Program 会员资格和已安装的 Xcode。
Android 平台：已安装 Android Studio。
不得安装 @capacitor/push-notifications —— 它会与 @capacitor-firebase/messaging 冲突。

代理行为

逐步引导。一步一步地引导用户完成整个过程。切勿一次性提出多个不相关的问题。
先自动检测再提问。检查项目的平台 (android/、)、构建工具、框架和依赖项。只有在无法检测到某些内容时才询问用户。

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

步骤 1：分析项目

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

平台：检查存在哪些目录 (android/、ios/)。这些就是要配置的平台。
构建工具 / 框架：检查是否存在 vite.config.ts、angular.json、webpack.config.js、next.config.js 等文件。
Capacitor 版本：从 package.json 中读取 @capacitor/core 的版本。
冲突的插件：检查 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 并将推送通知代码添加到项目中。调整导入和结构以匹配用户的框架。

请求权限
获取 FCM 令牌
监听传入的通知
处理通知点击

步骤 9：配置可选功能

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

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

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

步骤 10：同步和测试

同步项目：
```
npx cap sync
```
阅读 references/testing.md 并引导用户通过 Firebase 控制台发送测试通知。

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

🇺🇸English

Capacitor Push Notifications

Set up and use push notifications in Capacitor apps using Firebase Cloud Messaging (FCM) via the @capacitor-firebase/messaging plugin.

Prerequisites

Capacitor 6, 7, or 8 app.
Node.js and npm installed.
A Firebase project. Create one at Firebase console if needed.
For iOS : A paid Apple Developer Program membership and Xcode installed.
For Android : Android Studio installed.
@capacitor/push-notifications must not be installed — it conflicts with @capacitor-firebase/messaging.

Agent Behavior

Guide step-by-step. Walk the user through the process one step at a time. Never present multiple unrelated questions at once.
Auto-detect before asking. Check the project for platforms (android/, ios/), build tools, framework, and package.json dependencies. Only ask the user when something cannot be detected.
One decision at a time. When a step requires user input, ask that single question, wait for the answer, then continue.
Present clear options. Provide concrete choices (e.g., "Do you want to configure topic subscriptions? (yes/no)") instead of open-ended questions.

Procedures

Step 1: Analyze the Project

Auto-detect the following by reading project files — do not ask the user for information that can be inferred:

Platforms : Check which directories exist (android/, ios/). These are the platforms to configure.
Build tool / framework : Check for vite.config.ts, angular.json, webpack.config.js, next.config.js, etc.
Capacitor version : Read @capacitor/core version from package.json.
Conflicting plugins : Check if @capacitor/push-notifications is in . If found, warn the user it must be removed before proceeding:

Step 2: Set Up Firebase

Check if Firebase is already configured in the project:

Android : Check if android/app/google-services.json exists.
iOS : Check if ios/App/App/GoogleService-Info.plist exists.

If Firebase is not configured for a detected platform, read references/firebase-setup.md and guide the user through the Firebase setup for each missing platform.

Step 3: Install the Plugin

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

Step 4: Configure Android

Skip if android/ does not exist.

Read references/android-setup.md and apply the Android-specific configuration.

Step 5: Configure iOS

Skip if ios/ does not exist.

Read references/ios-setup.md and apply the iOS-specific configuration. This includes APNs key/certificate setup, AppDelegate.swift modifications, and enabling capabilities.

Step 6: Configure Web (if applicable)

If the project targets the web (detected via build tool config or user confirmation):

Read references/web-setup.md and apply the Web-specific configuration.

Step 7: Configure Capacitor Plugin Options

Ask the user if they want to customize iOS foreground notification presentation. If yes, update capacitor.config.json or capacitor.config.ts:

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

Available options: badge, sound, alert, criticalAlert. Default is ["alert", "badge", "sound"].

Step 8: Add Push Notification Code

Read references/implementation.md and add the push notification code to the project. Adapt imports and structure to match the user's framework.

The implementation covers:

Requesting permissions
Retrieving the FCM token
Listening for incoming notifications
Handling notification taps

Step 9: Configure Optional Features

Ask the user which optional features to enable:

Topic subscriptions — Subscribe/unsubscribe to FCM topics (Android/iOS only).
Notification channels — Create custom Android notification channels (Android SDK 26+ only).
Token refresh listener — Listen for FCM token changes.

For each selected feature, read references/implementation.md and apply the relevant code.

Step 10: Sync and Test

Sync the project:
```
npx cap sync
```
Read references/testing.md and guide the user through sending a test notification via the Firebase Console.

Error Handling

@capacitor/push-notifications conflict: The @capacitor-firebase/messaging plugin cannot coexist with @capacitor/push-notifications. Uninstall the conflicting plugin: npm uninstall @capacitor/push-notifications && npx cap sync.
iOS: No push notifications received : Verify APNs key/certificate is uploaded to Firebase Console. Verify Push Notifications and Background Modes capabilities are enabled. Verify AppDelegate.swift contains the required delegate methods.
iOS:didRegisterForRemoteNotificationsWithDeviceToken not called: Ensure the Push Notifications capability is added in Xcode under Signing & Capabilities. Check that the app's bundle ID matches the one registered in Firebase and Apple Developer portal.
Android: No push notifications received : Verify google-services.json is at . Verify the Google services Gradle plugin is applied.

Weekly Installs

Repository

capawesome-team/skills

GitHub Stars

First Seen

8 days ago

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

opencode58

gemini-cli58

amp58

cline58

github-copilot58

codex58

React 组合模式指南：Vercel 组件架构最佳实践，提升代码可维护性

123,700 周安装

npm uninstall @capacitor/push-notifications

android/app/google-services.json

Android: White square notification icon : The notification icon must be white pixels on a transparent background. Application icons with color will render as a white square. Add a dedicated push notification icon.

Web:getToken() fails: Ensure the VAPID key is correct. Ensure firebase-messaging-sw.js exists at the root of the domain. Check that the browser supports the Push API.

FCM token isnull: Ensure requestPermissions() was called and returned granted before calling getToken(). On iOS, verify the device is not a simulator (simulators cannot receive push notifications).

checkPermissions() returns denied: The user has permanently denied notification permissions. Guide them to re-enable via device settings (Settings > App > Notifications).

Android 13+: No permission prompt : On Android 13 (API 33) and above, requestPermissions() must be called explicitly. Earlier Android versions grant notification permission by default.