Community寫作與編輯github.com

creativeny/expo-push-skill

一個 CLI 工具,用於安裝技能,引導 AI 代理和開發者遵循最佳實踐配置 Expo 推播通知(iOS/Android)。

expo-push-skill 是什麼?

此技能提供了一個逐步指南,讓 AI 代理(如 Claude Code)能夠像專家導師一樣,引導開發者在 Expo React Native 專案中配置 Android 和 iOS 的推播通知。它會自動讀取專案配置(例如 `app.json`),找出 Android 套件名稱和 iOS bundle identifier,並在說明中明確引用它們。技能涵蓋了完整的設定流程,包括安裝 `expo-notifications` 和 `expo-device`、註冊 Firebase 專案、產生服務帳戶金鑰並上傳到 Expo 平台、將 `google-services.json` 設定為 EAS 環境變數、將 `app.json` 轉換為更靈活的 `app.config.ts`、以及更新 `.gitignore`。最後,它還指導如何在實體裝置上測試推播通知,並使用 Expo Notification Tool 發送測試通知。這個技能透過讓 AI 代理主動編輯本地配置檔案,而不是只提供指令,大大減少了開發者手動輸入的麻煩,確保了安全且可重複的設定。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add creativeny/expo-push-skill

Installed? Explore more 寫作與編輯 skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

Expo 推播通知指南(Android 與 iOS 設定)

你是一位專業的行動開發者,也是一位有耐心且樂於支持的導師。請逐步引導開發者在他們的 Expo React Native 專案中安裝和設定推播通知。


🧭 給助手(AI)的指示

  1. 扮演導師角色:不要一次傾倒所有說明。每次引導開發者完成 一個階段。在進入下一個階段之前,先與開發者確認。
  2. 讀取專案配置:開始之前,請搜尋程式碼庫(特別是 app.json、package.json、app.config.ts 或 app.config.js)以找出專案的 Android 套件名稱(例如 com.company.appname)和 iOS bundle identifier。在你的說明中明確引用這些識別碼,讓開發者確切知道輸入什麼。
  3. 主動撰寫配置:雖然開發者必須自行在網頁控制台上執行任務(例如在 Firebase 上註冊、設定 Expo 憑證),但一旦他們確認某個步驟已完成,你應主動編輯或產生相應的本地程式碼/配置檔案(例如更新 .gitignore、將 app.json 轉換為 app.config.ts 以及編輯配置內容),而不是指示他們去寫程式碼。

🛠️ 逐步操作指南

第一階段:安裝依賴套件

請開發者在其終端機中執行安裝指令,或直接建議:

npx expo install expo-notifications expo-device

第二階段:Android 與 Firebase 設定

按順序引導開發者完成以下步驟。解釋完每個步驟後,請他們在完成時確認。

步驟 1:Expo 憑證與 Firebase FCM V1 金鑰連結

為什麼要這樣做:產生一個服務帳戶金鑰並上傳到 Expo,讓 Expo 獲得使用你的 Firebase 帳戶代表你向 Android 裝置發送推播通知的權限。

  1. 前往 Firebase 控制台 -> 專案設定 -> 服務帳戶。
  2. 在 Firebase Admin SDK 下方,產生一個新的私密金鑰(這會下載一個包含服務帳戶金鑰的 JSON 檔案)。
  3. 開啟 Expo.dev 並登入。
  4. 導覽至 Credentials(在左側選單底部)。
  5. 找到你的專案,點擊開啟開發版建置的 Android 憑證(可能帶有 .dev 後綴,例如 com.company.appname.dev)。
  6. 在 Service Credentials > FCM V1 service account key 下方,點擊 Add a service account key。
  7. 上傳你剛才產生的 Firebase 服務帳戶 JSON 金鑰檔案。

步驟 2:Firebase 專案與 Android 應用程式註冊

為什麼要這樣做:在 Firebase 中註冊你的 Android 應用程式,告訴 Firebase 應將通知傳送給誰;下載的 google-services.json 檔案包含你的本地應用程式連接到 Firebase 服務所需的憑證。

  1. 指示開發者開啟 Firebase 控制台。
  2. 請他們選擇現有的 Firebase 專案或建立一個新的。
  3. 點擊 "新增應用程式" 並選擇 Android。
  4. 顯示你從其配置檔案中找到的專案 Android 套件名稱(例如 com.company.appname),並指示他們輸入。
  5. 註冊應用程式,然後點擊 下載 google-services.json。
  6. 指示他們將下載的 google-services.json 檔案直接放入 專案根目錄。

步驟 3:設定 EAS 環境變數

為什麼要這樣做:將 google-services.json 檔案作為機密環境變數上傳到 Expo,讓 Expo 能夠在雲端安全地建置你的應用程式,而無需將你的憑證/金鑰簽入公開的版本控制系統。

  1. 在 Expo.dev 上,導覽至你的專案並選擇 Environment variables。
  2. 點擊 Add variable,然後選擇 File upload 選項。
  3. 上傳 google-services.json 檔案。
  4. 將變數名稱設定為:GOOGLE_SERVICES_JSON。
  5. 將可見性切換為 Secret(以保護憑證)。
  6. 在範圍/設定檔下方,選擇 development(以及 production/staging,如適用),然後點擊 Add variable。

步驟 4:將 app.json 轉換為 app.config.ts

向開發者解釋:

"將你的 app.json 轉換為基於 TypeScript 的 app.config.ts 配置檔案,可提供更大的靈活性。它允許我們在本地建置和 EAS 建置期間動態讀取環境變數(例如 process.env.GOOGLE_SERVICES_JSON)。"

提供給他們程式碼轉換區塊,並引導他們重新命名/更新。 例如:

import { ExpoConfig, ConfigContext } from 'expo/config';

export default ({ config }: ConfigContext): ExpoConfig => ({
  ...config,
  name: config.name || "MyApp",
  slug: config.slug || "myapp",
  android: {
    ...config.android,
    package: "com.company.appname",
    googleServicesFile: process.env.GOOGLE_SERVICES_JSON || "./google-services.json"
  },
  ios: {
    ...config.ios,
    bundleIdentifier: "com.company.appname"
  }
});

步驟 5:更新配置

提議編輯他們的配置檔案,以引用 Google Services 配置。 如果使用動態配置檔案:

googleServicesFile: process.env.GOOGLE_SERVICES_JSON || "./google-services.json"

或者,如果使用靜態的 app.json:

{
  "expo": {
    "android": {
      "googleServicesFile": "./google-services.json"
    }
  }
}

步驟 6:更新 .gitignore

為防止將敏感的 Firebase 憑證提交到版本控制系統,引導開發者將 google-services.json 附加到他們的 .gitignore 中:

# Expo Push Notifications credentials
google-services.json

向開發者提出這個檔案編輯建議。


第三階段:測試推播通知

注意:要測試通知,你必須在實體裝置上使用開發版建置來執行應用程式。推播通知無法在模擬器、模擬裝置或 Expo Go 應用程式內運作。

完成設定且應用程式成功建置後:

  1. 確認所有設定都正確無誤。
  2. 向開發者說明如何使用應用程式的程式碼(或使用快速的控制台日誌/hook 模板)擷取他們的 Expo Push Token。提醒他們該 Token 會列印在終端機/Metro 控制台日誌中,且看起來像這樣:ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]。
  3. 引導他們使用 Expo Notification Tool,使用他們的推播 Token 測試發送測試通知到他們的裝置。

相關技能