GitHub - UM-ARK/UM-All-Frontend: 要成為澳大師生人手一個的校園資訊大一統APP，ARK就是方舟！

🎉ARK ALL 是一個免費的開源 APP🎉

感興趣的話可以來 Wiki 看看更多關於 ARK 的故事~
如果 ARK ALL 有幫助到您，可以請我們喝杯咖啡！
如果您也想參與到 ARK ALL 的開發中，立即聯繫我們 umacark@gmail.com！

APP熒幕截圖

🎉ARK ALL 是一個免費的開源 APP🎉
🎉 首次運行該項目
🌈 開發本項目準備
- ⛵ 啟動流程
- 🐛 如何 Debug?
  - Google Firebase Analytics
📦 打包方式
⛵ 維護須知

🎉 首次運行該項目

在此查看已知 BUG，現在可以參考./AGENTS.md文件看項目說明了~~AI萬歲~~。

🤖 Android 環境 Setup

確保自己是 Android API 33 或 API 31 的模擬器環境，下載安裝 JDK、SDK
在項目根目錄(package.json所在的目錄)打開命令行運行 yarn install 安裝依賴
執行 npx expo prebuild --clean 生成 Android 原生項目
- 僅生成 Android：npx expo prebuild --clean --platform android
- 僅生成 iOS：npx expo prebuild --clean --platform ios
- 如安裝了跨平台庫，直接使用 npx expo prebuild --clean 生成兩個平台
前往 Android Studio 啟動所需的模擬器
敲入 yarn android 運行本項目吧!

🍎 iOS 環境 Setup

基於 Expo SDK 54 + React Native 0.81.5，iOS APP 目前只能在 Mac 開發調試

先安裝node包（Node ≥18），方便之後使用指令

brew install node
brew install watchman

確保安裝了 Xcode (版本 15 或以上)，建議在官網下載
在項目根目錄(package.json所在的目錄)打開命令行運行 yarn install 安裝依賴
執行 npx expo prebuild --clean 生成 iOS 原生項目
- 僅生成 iOS：npx expo prebuild --clean --platform ios
- 僅生成 Android：npx expo prebuild --clean --platform android
- 如安裝了跨平台庫，直接使用 npx expo prebuild --clean 生成兩個平台
使用 Expo 運行 iOS（不需要手動管理 CocoaPods）

yarn ios          # 運行 iPhone 16 Pro 模擬器
yarn iosNew       # 運行 iPhone 17 Pro 模擬器
yarn iosTrue      # 運行到真實設備
yarn iosBig       # 運行 iPad Pro 13-inch 模擬器

注意：Expo CNG 會自動處理 iOS 原生代碼生成和 CocoaPods 依賴，無需手動運行 pod install 或 prebuild。首次運行 yarn ios 時會自動生成原生項目文件。

📘 Expo CNG 工作流說明

項目使用 Expo CNG (Continuous Native Generation) 自動管理原生項目：

操作	命令	說明
安裝依賴	`yarn install` 或 `expo install`	推薦使用 yarn
生成原生項目	`npx expo prebuild --clean`	首次運行前必須執行，可加 `--platform ios/android` 指定平台
------	------	------
運行 iOS	`yarn ios`	運行 iOS 模擬器或真機
運行 Android	`yarn android`	運行 Android 模擬器

重要：

首次運行前必須先執行 npx expo prebuild --clean 生成原生項目文件
生成後會創建 ./ios 和 ./android 目錄
無需手動運行 pod install：Expo CNG 會自動處理
如果遇到原生構建問題，可重新運行 npx expo prebuild --clean 重新生成

🌈 開發本項目準備

⛵ 啟動流程

克隆倉庫的代碼到本地（推薦使用GitHub Desktop）

git clone https://github.com/UM-ARK/UM-All-Frontend.git

在項目根目錄下(./package.json所在的目錄)啟動 Terminal/命令行安裝依賴包

yarn install
# 或使用 expo install（自動處理依賴兼容性）
expo install

執行 npx expo prebuild --clean 生成 iOS/Android 原生項目
- 僅生成 iOS：npx expo prebuild --clean --platform ios
- 僅生成 Android：npx expo prebuild --clean --platform android
- 如安裝了跨平台庫，直接使用 npx expo prebuild --clean 生成兩個平台
配置 UM Open Data API Token（新聞、活動、停車場即時資料等 api.data.um.edu.mo 請求需要 Authorization）。請見下方 🔑 UM Open Data API Token 配置。

🔑 UM Open Data API Token 配置

程式透過 src/utils/pathMap.js 匯出的 UM_API_TOKEN 讀取 process.env.EXPO_PUBLIC_UM_API_TOKEN（Expo 會在打包／開發時把 EXPO_PUBLIC_* 內嵌進 JS，因此必須使用此前綴）。

本機開發

在專案根目錄（與 package.json 同層）新增 .env 或 .env.local。
寫入一行（將值換成你向澳大 Open Data 申請到的金鑰，勿使用範例字串）：

EXPO_PUBLIC_UM_API_TOKEN=你的_UM_Open_Data_Token

修改環境變數後請重新啟動 Metro；若仍讀不到，可嘗試 yarn start --clear 清快取再啟動。

版控與安全

.env、.env.local 與歷史上的 umAPIToken.json 均已列於 .gitignore，請勿把真實 Token 提交到 Git。
舊版文件曾要求根目錄 umAPIToken.json；目前程式碼已不再讀取該 JSON，請改用上方的 EXPO_PUBLIC_UM_API_TOKEN。

EAS / 雲端建置

雲端機器不會自動帶上你電腦裡的 .env。使用 EAS Build 時，請在 Expo 專案 Environment variables 為對應建置 profile 設定同名變數 EXPO_PUBLIC_UM_API_TOKEN，否則正式版中相關 API 可能無法通過驗證。

取得 Token

請依澳門大學 Open Data／Data API 官方流程申請；維護者或團隊內部文件會說明申請管道與權限範圍。開源貢獻者若無金鑰，與上述 API 有關的畫面可能無法取得資料，屬預期行為。

需要配置 Firebase 配置文件（用於 Analytics 等功能）：

📋 Firebase 配置文件說明

本項目需要以下 Firebase 配置文件：

平台	文件路徑	用途
Android	`google-services.json`（項目根目錄）	Firebase Analytics、Crashlytics
iOS	`GoogleService-Info.plist`（項目根目錄）	Firebase Analytics、Crashlytics

獲取方式：

前往 Firebase Console 創建項目
註冊 Android/iOS 應用（包名：one.umall）
下載配置文件並放到對應目錄

如果只需運行項目（不使用 Firebase 功能）：

可以嘗試使用空文件或模板文件。以下是文件結構僅供參考（請勿填入真實隱私 key）：

`google-services.json` 模板結構

{
  "project_info": {
    "project_number": "000000000000",
    "project_id": "your-project-id",
    "storage_bucket": "your-project-id.appspot.com"
  },
  "client": [
    {
      "client_info": {
        "mobilesdk_app_id": "1:000000000000:android:0000000000000000000000",
        "android_client_info": {
          "package_name": "one.umall"
        }
      },
      "oauth_client": [],
      "api_key": [
        {
          "current_key": "YOUR_API_KEY"
        }
      ],
      "services": {
        "appinvite_service": {
          "other_platform_oauth_client": []
        }
      }
    }
  ],
  "configuration_version": "1"
}

`GoogleService-Info.plist` 模板結構

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>CLIENT_ID</key>
    <string>000000000000-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.apps.googleusercontent.com</string>
    <key>REVERSED_CLIENT_ID</key>
    <string>com.googleusercontent.apps.000000000000-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx</string>
    <key>API_KEY</key>
    <string>YOUR_API_KEY</string>
    <key>GCM_SENDER_ID</key>
    <string>000000000000</string>
    <key>PLIST_VERSION</key>
    <string>1</string>
    <key>BUNDLE_ID</key>
    <string>one.umall</string>
    <key>PROJECT_ID</key>
    <string>your-project-id</string>
    <key>STORAGE_BUCKET</key>
    <string>your-project-id.appspot.com</string>
    <key>IS_ADS_ENABLED</key>
    <false/>
    <key>IS_ANALYTICS_ENABLED</key>
    <false/>
    <key>IS_APPINVITE_ENABLED</key>
    <true/>
    <key>IS_GCM_ENABLED</key>
    <true/>
    <key>IS_SIGNIN_ENABLED</key>
    <true/>
    <key>GOOGLE_APP_ID</key>
    <string>1:000000000000:ios:0000000000000000000000</string>
</dict>
</plist>

⚠️ 注意：空文件可能導致 Firebase 功能異常。建議從 Firebase Console 獲取真實配置文件，或至少填入有效的 API_KEY。

🤖 Android 運行

在 Android 上運行 App

yarn android

說明：

Expo CNG 會在首次運行時自動生成 Android 原生項目文件
首次運行前需先執行 npx expo prebuild --clean 生成原生項目
運行 yarn android 前不需要手動執行 prebuild

🍎 iOS 運行

項目使用 Expo SDK 54 與 CNG (Continuous Native Generation)，無需手動管理 CocoaPods

確保已安裝依賴

yarn install

使用 Expo 運行 iOS

yarn ios          # 運行 iPhone 16 Pro 模擬器
yarn iosNew       # 運行 iPhone 17 Pro 模擬器
yarn iosTrue      # 運行到真實設備
yarn iosBig       # 運行 iPad Pro 13-inch 模擬器

說明：

Expo CNG 會自動處理 iOS 原生代碼生成和 CocoaPods 依賴
首次運行前需先執行 npx expo prebuild --clean 生成原生項目
無需手動運行 pod install
無需手動打開 Xcode 進行編譯
如需在 Xcode 中調試，可打開 ./ios 目錄下的項目文件（首次運行 yarn ios 後會生成）

配置Firebase

從Firebase控制台導出配置文件放入項目根目錄 google-services.json 和 GoogleService-Info.plist。

詳細說明見上方「Firebase 配置文件說明」章節。

🐛 如何 Debug?

當需要 log 出對象或者數組時，有 Chrome 的 Web Debugger 肯定更好用。
舊版的項目可以在 Metro 的命令窗口中按下 d 再在模擬器中選擇 Debug 即可直接跳轉瀏覽器查看 log。

react-native@0.81+更新：

在Metro中直接使用j調出React DevTools。
iOS 模擬器支持最新的 Debugging 方案。

Google Firebase Analytics

iOS和Android平台：打開偵錯事件隨後可以在Firebase控制台Debug View中看到近乎實時(可能有1min延遲)的logEvent反饋，用於測試Analytics是否正常。

📦 打包方式

🍎 iOS 打包

項目使用 Expo SDK 54 與 CNG，推薦使用 Expo 進行打包

方式一：使用 Expo 構建（推薦）

確保已安裝 EAS CLI

yarn global add eas-cli
# 或
npm install -g eas-cli

登錄 Expo 賬號

eas login

構建 iOS 應用

eas build --platform ios

按照提示選擇構建類型（內部分發或 App Store 提交）

方式二：本地 Xcode 構建（傳統方式）

如需在 Xcode 中手動構建：

確保已運行過 npx expo prebuild --clean 生成 iOS 項目文件
打開 ./ios/UMALL.xcworkspace
在 Xcode 中配置簽名和版本號
使用 Product -> Archive 進行歸檔和發佈

注意事項：

版本號在 app.json 中統一管理，構建時會自動同步到原生項目
使用 EAS 構建時，不需要手動管理簽名證書
提交 App Store 前確保已在 App Store Connect 創建應用記錄

本地 Release 真機除錯（不走 EAS）

在需要驗證 Production / Release 行為、且希望不經 EAS 雲端建置時，可在本機用 Xcode 簽名，將 Release 組態直接安裝到已以 USB 連接的真機。

npx expo run:ios --configuration Release --device


好處	不必等待 EAS 雲端排隊，本機建置與重裝較快。
條件 / 壞處	需要有效的 Apple 開發者帳號，且本機 Xcode 與簽名環境（Team、憑證、裝置信任等）需設定正確。

首次使用前請先依上文完成 npx expo prebuild 與依賴安裝；若簽名失敗，請在 Xcode 中開啟 ios 內的 workspace，檢查 Signing & Capabilities 與目標裝置是否已加入開發團隊。

🤖 Android 打包

方式一：使用 Expo 構建（推薦）

eas build --platform android

選擇構建類型：

APK：內部分發測試
AAB (Android App Bundle)：Google Play Store 提交

方式二：本地 Gradle 構建

確保已運行過 npx expo prebuild --clean 生成 Android 項目文件
依下方本機 Release 簽名設定完成 Release 簽名（本倉庫透過 Expo config plugin 注入，無需在 android/app/build.gradle 手動改寫）
運行構建命令：

cd android
./gradlew assembleRelease  # 構建 APK
# 或
./gradlew bundleRelease    # 構建 AAB (Google Play)

注意事項：

確保 JDK 版本為 18 或以上
版本號在 app.json 中統一管理
首次發布到 Play Store 需要使用 AAB 格式
內部測試可使用 APK 格式直接安裝

本機 Release 簽名設定

對應最新提交中的 Android Release 簽名與 Expo CNG：app.json 已掛載 ./plugins/withAndroidSigning，在執行 npx expo prebuild 時會自動在 android/app/build.gradle 注入 Release 的 signingConfigs。只有當 Gradle 能讀到 MYAPP_RELEASE_* 屬性時才會套用正式 keystore；密碼與路徑請勿寫入倉庫內的 gradle.properties（避免提交）。

1. Keystore 檔要放哪？

MYAPP_RELEASE_STORE_FILE 在 Gradle 裡會解析成：相對於專案根目錄（與 package.json 同層）的路徑。
常見做法：把keystore.keystore放在根目錄
亦可將檔案放在倉庫外，只要 MYAPP_RELEASE_STORE_FILE 仍能以「自專案根目錄起算」的相對路徑指到該檔（或依你本機 Gradle／Java 版本使用絕對路徑；仍以不進版控為原則）。

2. 在 ~/.gradle/ 裡怎麼配置？

在使用者家目錄建立或編輯 ~/.gradle/gradle.properties（全機共用、不進專案 Git），寫入以下鍵值（請替換成你自己的路徑與密碼）：

# Android Release 簽名（僅本機，勿提交）
# MYAPP_RELEASE_STORE_FILE：相對「專案根目錄」的 keystore 路徑
MYAPP_RELEASE_STORE_FILE=android/app/release.keystore
MYAPP_RELEASE_STORE_PASSWORD=你的_store_密碼
MYAPP_RELEASE_KEY_ALIAS=你的_key_alias
MYAPP_RELEASE_KEY_PASSWORD=你的_key_密碼

存檔後在專案根目錄執行 cd android && ./gradlew bundleRelease（或 assembleRelease）即可。若未設定上述屬性，Release 區塊不會套用 store 檔，請勿在遺失簽名設定的情況下誤發佈。

3. 維護提醒

重新執行 npx expo prebuild --clean 時，只要 app.json 仍包含 ./plugins/withAndroidSigning，簽名區塊會一併重新產生，無需手動合併 build.gradle。
CI／EAS 請改用 EAS 的 Android 憑證管理或對應的 secrets，而不是依賴某台機器上的 ~/.gradle/gradle.properties。

🐛 故障排除

在此查看Android 解決方案與iOS 解決方案

⛵ 維護須知

澳大日曆更新。從 https://reg.um.edu.mo/university-almanac/?lang=zh-hant 獲取 ics 文件；使用任何工具將 ics 轉為 json（course-data-parse 倉庫內也有 icsToJSON 工具），例如 https://ical-to-json.herokuapp.com/。務必注意最終 json 中的 key 必須為小寫。覆蓋 src/static/UMCalendar/UMCalendar.json 中的內容即可。
- 按照程序注釋增加校曆的繁體中文翻譯內容。
澳大課程更新。使用預選課 Excel，使用 Excel to JSON 工具獲得 JSON 數據，放入src/static/UMCourses/offer courses.json。
- 按照程序注釋增加開設課程的繁體中文翻譯內容。
icon 更新。使用 https://www.appicon.co/ 生成 iOS icon 文件，使用 Android Studio 生成 Android icon 文件（Studio 生成的文件最全面，適配各個廠商的 UI）。

Name		Name	Last commit message	Last commit date
Latest commit History 2,149 Commits
.cursor/rules		.cursor/rules
.github		.github
.yarn/releases		.yarn/releases
README		README
android		android
ios		ios
plugins		plugins
src		src
.eslintrc.js		.eslintrc.js
.gitignore		.gitignore
.prettierrc.js		.prettierrc.js
.yarnrc.yml		.yarnrc.yml
App.js		App.js
CLAUDE.md		CLAUDE.md
Gemfile		Gemfile
Gemfile.lock		Gemfile.lock
JOBS.md		JOBS.md
README.md		README.md
app.json		app.json
babel.config.js		babel.config.js
eas.json		eas.json
index.js		index.js
jest.config.js		jest.config.js
metro.config.js		metro.config.js
npmInstallScript.sh		npmInstallScript.sh
package.json		package.json
yarn.lock		yarn.lock

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

🎉ARK ALL 是一個免費的開源 APP🎉

🎉 首次運行該項目

🤖 Android 環境 Setup

🍎 iOS 環境 Setup

📘 Expo CNG 工作流說明

🌈 開發本項目準備

⛵ 啟動流程

🔑 UM Open Data API Token 配置

📋 Firebase 配置文件說明

google-services.json 模板結構

GoogleService-Info.plist 模板結構

🤖 Android 運行

🍎 iOS 運行

配置Firebase

🐛 如何 Debug?

Google Firebase Analytics

📦 打包方式

🍎 iOS 打包

方式一：使用 Expo 構建（推薦）

方式二：本地 Xcode 構建（傳統方式）

本地 Release 真機除錯（不走 EAS）

🤖 Android 打包

方式一：使用 Expo 構建（推薦）

方式二：本地 Gradle 構建

本機 Release 簽名設定

🐛 故障排除

⛵ 維護須知

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases 29

Sponsor this project

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

`google-services.json` 模板結構

`GoogleService-Info.plist` 模板結構