開發指南

約 1401 字大約 5 分鐘

提示

本頁面主要描述了 PR 流程以及 MAA 的檔案格式化要求，如果您想要具體了解如何對 MAA 的運行邏輯進行更改，請參閱協議文件

提示

您可以向 DeepWiki 詢問，以初步了解 MAA 專案的整體架構。

我不懂程式設計，只想改一點點 JSON 檔案 / 文件等，要怎麼操作？

歡迎收看牛牛也能看懂的 GitHub Pull Request 使用指南（純網頁端操作 github.com）

我只想簡單修改幾行程式碼，但配置環境太麻煩，純網頁編輯又很難用，怎麼辦？

請使用 GitHub Codespaces 線上開發環境，盡情嘗試！

我們預置了多種不同的開發環境以供選擇：

基礎環境，純 Linux 容器（預設）
精簡環境，適合文件站前端開發
完整環境，適合 MAA Core 相關開發（不推薦使用，建議本機開發，完整配置相關環境。詳見下一章節）

完整環境配置流程（Windows）

如果很久以前 Fork 過，先在自己倉庫的 Settings 裡，翻到最下面，將其刪除。
打開 MAA 主倉庫，點擊 Fork，繼續點擊 Create fork。
複製（Clone）您自己倉庫下的 dev 分支到在地，並拉取子模組（Submodules）。
```
git clone --recurse-submodules <您的倉庫 git 連結> -b dev
```
注意
如果正在使用 Visual Studio 等不附帶 --recurse-submodules 參數的 Git GUI，則需在複製後再執行 git submodule update --init 以拉取子模組。
下載預編譯的第三方函式庫
需要有 Python 環境，請自行搜尋 Python 安裝教學。
```
python tools/maadeps-download.py
```
配置開發環境
- 下載並安裝 CMake
- 下載並安裝 Visual Studio 2026 Community，安裝時需要選中 使用 C++ 的桌面開發 和 .NET 桌面開發。

執行 CMake 專案配置

mkdir -p build
cmake -G "Visual Studio 18 2026" -B build -DBUILD_WPF_GUI=ON -DBUILD_DEBUG_DEMO=ON

雙擊開啟 build/MAA.slnx 檔案，Visual Studio 會自動載入整個專案。
設定 Visual Studio
- Visual Studio 上方配置選擇 Debug x64
- 右鍵點擊 MaaWpfGui - 設為啟動專案。
- 按 F5 執行。
提示
若需針對 Win32Controller（Windows 視窗控制）相關功能進行除錯，需要自行從 MaaFramework Releases 下載對應平台的壓縮檔案，將 bin 目錄中的 MaaWin32ControlUnit.dll 放到 MAA 的 DLL 同目錄下（例如 build/bin/Debug）。歡迎 PR 一個自動下載腳本！
到這裡，你就可以愉快地 ~~瞎雞巴改~~ 發電了
開發過程中，每一定數量，記得提交一個 Commit, 別忘了寫上 Message
假如你不熟悉 git 的使用，你可能想要新建一個分支進行更改，而不是直接提交在 dev 上
```
git branch your_own_branch
git checkout your_own_branch
```
這樣你的提交就能在新的分支上生長，不會受到 dev 更新的打擾
完成開發後，推送你修改過的本地分支（以 dev 為例）到遠端（Fork 的倉庫）
```
git push origin dev
```
打開 MAA 主倉庫。提交一個 Pull Request，等待管理員通過。別忘了您是在 dev 分支上修改，別提交到 master 分支去了。
當 MAA 原倉庫出現更改（他人貢獻）時，您可能需要把這些更改同步到您的分支：
1. 關聯 MAA 原倉庫
```
git remote add upstream https://github.com/MaaAssistantArknights/MaaAssistantArknights.git
```
2. 從 MAA 原倉庫拉取更新
```
git fetch upstream
```
3. 變基（推薦）或者合併修改
```
git rebase upstream/dev # 變基
```
  或者
```
git merge # 合併
```
4. 重複上述 8, 9, 10, 11 中的操作

提示

開啟 Visual Studio 之後，和 Git 有關的操作可以不用命令列工具，直接使用 Visual Studio 內建的「Git 變更」功能即可。

MAA 的檔案格式化要求

MAA 使用一系列的格式化工具來確保倉庫中的程式碼和資源檔案美觀統一，以便於維護和閱讀。

請確保在提交之前已經完成格式化，或是啟用 Pre-commit Hooks 來進行自動格式化

目前啟用的格式化工具如下：

檔案類型	格式化工具
C++	clang-format
Json/Yaml	Prettier
Markdown	markdownlint

利用 Pre-commit Hooks 自動進行程式碼格式化

確保您的電腦上有 Python 與 Node 環境

在專案根目錄下執行以下命令：

pip install pre-commit
pre-commit install

如果 pip 安裝後依然無法執行 pre-commit，請確認 pip 安裝路徑已被添加到 PATH。

接下來，每次提交時都將會自動執行格式化工具，以確保您的程式碼格式符合規範。

在 Visual Studio 中啟用 clang-format

安裝 clang-format 20.1.0 或更高版本
```
python -m pip install clang-format
```
使用 Everything 等工具找到 clang-format.exe 的安裝位置。作為參考，若您使用了 Anaconda，clang-format.exe 將安裝在 YourAnacondaPath/Scripts/clang-format.exe
在 Visual Studio 工具-選項 中搜尋 clang-format
點擊 啟用 ClangFormat 支援，然後選擇下方的 使用自定義 clang-format.exe 檔案，選擇第 2 步找到的 clang-format.exe

然後您的 Visual Studio 就能愉快地使用支援 C++20 語法的 clang-format 啦！

您也可以使用 tools\ClangFormatter\clang-formatter.py 來直接呼叫 clang-format 進行格式化，只需在專案根目錄下執行：

python tools\ClangFormatter\clang-formatter.py --clang-format=PATH\TO\YOUR\clang-format.exe --input=src\MaaCore