MAA 藉由 GitHub Actions 完成了大量的自動化工作，包括網站建置、資源自動更新、最終檔案的編譯與發布等過程。隨著時間推移，這些 CI 逐漸開始嵌套，部分甚至連結到了其他的倉庫。本文檔旨在為想要改進 MAA CI 系統的開發者提供一份簡要介紹。

閱讀本文之前，建議先對 MAA 的專案結構與組成有基本的概念。

提示

您可以透過在本頁面內搜尋 CI 檔名來快速導航到想看的內容。

工作流（Workflow）檔案均存放於 .github/workflows 目錄下，各檔案可依功能分為以下幾部分：

• 程式碼測試
• 程式碼建置
• 程式碼安全檢查
• 版本發布
• 資源更新
• 網站建置
• Issues 管理
• Pull Requests 管理
• MirrorChyan 相關
• 其他

此外，我們還透過 pre-commit.ci 實現了程式碼自動格式化與圖片資源自動優化，它在發起 PR 後會自動執行，一般無需特別在意。

GitHub Actions 部分

程式碼測試

smoke-testing.yml

本工作流主要負責對 MaaCore 進行基礎檢測，包括資源檔案載入、部分簡單任務（Task）執行測試等。

由於測試案例（Test Cases）已較久未更新，該工作流目前的初衷是確保資源檔案不會出錯，以及 MaaCore 的程式碼沒有出現影響建置的致命性錯誤。

程式碼建置

ci.yml

本工作流負責對程式碼進行全量建置工作，包含 MAA 的所有組件，建置產物即為可執行的 MAA。

除了必要的 MaaCore 外，Windows 建置產物會包含 MaaWpfGui，macOS 建置產物會包含 MaaMacGui，Linux 建置產物則包含 MaaCLI。

該工作流在有任何新提交（Commit）或 PR 時都會自動執行；當該工作流由發版 PR 觸發時，本次的建置產物將直接用於發布，並自動建立一個 Release。

程式碼安全檢查

程式碼安全檢查透過 CodeQL 對程式碼與工作流進行安全分析，具體工作流如下：

codeql-core.yml

負責對 MaaCore 與 MaaWpfGui 的 C++ 和 C# 程式碼進行安全分析，偵測潛在的安全漏洞。

該工作流在修改相關原始碼的 PR 時會自動執行，同時於每天 UTC 時間 11:45 進行定期檢查。

codeql-wf.yml

負責對 GitHub Actions 工作流檔案本身進行安全分析，確保 CI/CD 流程的安全性。

該工作流在修改工作流檔案的 PR 時會自動執行，同時於每天 UTC 時間 12:00 進行定期檢查。

版本發布

版本發布（簡稱發版）是向用戶發布更新的必要操作，由以下工作流組成：

• release-nightly-ota.yml 發布內測版（Nightly）
• release-ota.yml 發布正式版 / 公測版（Beta）
  • release-preparation.yml 為正式版 / 公測版產生 Changelog 並準備發布
  • pr-auto-tag.yml 對正式版 / 公測版產生 Tag

提示

上述檔名稱內的 OTA 意為 Over-the-Air（雲端更新），也就是我們常說的 增量更新檔案，因此 MAA 的發版過程實際上包含了對過往版本建置 OTA 檔案的步驟。

內測版

release-nightly-ota.yml

本工作流會在每天 UTC 時間 22 點自動執行，以保證內測版的更新頻率。當然，您也可以在做出更改需要驗證時手動觸發發布。

需要注意的是，內測版發布僅針對 Windows 用戶，macOS 與 Linux 用戶目前無法接收到內測更新。

正式版 / 公測版

這兩個版本的發布流程相對複雜，我們透過模擬一次發布步驟來解釋各工作流的作用：

1. 建立從 dev-v2 到 master 分支的 PR，且該 PR 的標題需為 Release v******。
2. release-preparation.yml 會產生從最近版本到當前版本的 Changelog（以一個新 PR 的形式呈現）。
3. 對 Changelog 進行手動調整，並加入簡要描述。
4. 合併 PR，觸發 pr-auto-tag.yml 建立 Tag 並同步分支。
5. Release 事件觸發 release-ota.yml，對 master 標上 Tag 後進行 OTA 包建置及附件上傳。

資源更新

這部分工作流主要負責 MAA 的資源更新與優化，具體如下：

• res-update-game.yml 定期執行，從指定倉庫拉取遊戲資源。
• sync-resource.yml 將資源同步到 MaaResource 倉庫，用於資源更新。
• optimize-templates.yml 優化包括範本圖片在內的圖片檔案大小。

網站建置

website-workflow.yml

本工作流主要負責 MAA 文件站的建置與發布。

請注意，網站的發布與版本更新強烈綁定。平時修改網頁組件時僅會進行建置以確保無誤，只有在正式發布版本時才會部署到 GitHub Pages。

Issues 管理

issue-checker.yml

透過正規表達式（Regex）比對為各個 Issue 標記 Tag，以此分類 Issue 內容，方便查看與管理。

issue-checkbox-checker.yml

透過正規表達式自動關閉勾選「我未仔細閱讀」的 Issue；若該項未被勾選，則將所有勾選框（Checkbox）折疊。

stale.yml

檢查超過 90 天沒有活動的 Bug Issue 並標記通知，若 7 天後仍無活動則自動關閉。

Pull Requests 管理

pr-checker.yml

檢查 PR 中的 Commit Message 是否符合 約定式提交，以及是否包含 Merge Commit，若不符合則會發出提示。

MirrorChyan 相關

MirrorChyan 是有償的更新鏡像服務，相關工作流如下：

• release-package-distribution.yml 同步更新包至 MirrorChyan。
• mirrorchyan_release_note.yml 產生 MirrorChyan 的 Release Note。

其他

markdown-checker.yml

檢查倉庫中所有 Markdown 檔案是否包含無效連結（死連結）。

blame-ignore.yml

自動忽略 Commit Message 包含 blame ignore 的提交，以保持 Git Blame 歷史紀錄的簡潔。

cache-delete.yml

在 PR 合併後清理相關快取（Cache），以節省 GitHub 儲存空間。

update-submodules.yml

定期將 MaaMacGui 與 maa-cli 等子模組更新至最新版本。該工作流於每天 UTC 時間 21:50 自動執行（在每日內測版發布之前），確保子模組保持在最新狀態。