提示
本页面主要描述了 PR 流程以及 MAA 的文件格式化要求，如果你想要具体了解如何对 MAA 的运行逻辑做出更改，请参看 协议文档
欢迎收看 牛牛也能看懂的 GitHub Pull Request 使用指南 （纯网页端操作 GitHub.com）
请使用 GitHub Codespaces 在线开发环境，尽情尝试！
我们预置了多种不同的开发环境以供选择：
如果很久以前 Fork 过，先在自己仓库的 Settings 里，翻到最下面，删除
打开 MAA 主仓库，点击 Fork，继续点击 Create fork
克隆你自己仓库下的 dev-v2 分支到本地，并拉取子模块
git clone --recurse-submodules <你的仓库的 git 链接> -b dev-v2 --single-branch
提示
--single-branch 只会拉取 dev-v2 的提交记录。如果之后想切换到其他分支，需要先执行 git remote set-branches origin '*' 并重新拉取，来补齐其他分支的信息；或者重新克隆一个不带 --single-branch 的仓库。
注意
如果正在使用 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 项目配置
cmake --preset windows-x64
双击打开 build/MAA.slnx 文件，Visual Studio 会自动加载整个项目。
设置 VS
- VS 上方配置选择
Debug x64 - 右键
MaaWpfGui - 设为启动项目 - 按 F5 运行
提示
若需运行 Win32Controller（Windows 窗口控制）/ MaaFwAdbController（MaaFramework 触控模式）相关功能，运行 python tools/maafw-control-unit-download.py 即可自动下载对应平台的 MaaWin32ControlUnit.dll / MaaAdbControlUnit.dll 到构建输出目录（默认取 build/bin 下最新生成的目录，也可用 --output-dir 指定）。
若需调试相关功能，则需要自行编译 MaaFramework 的 Debug 版本，使用对应的 DLL 文件，否则在断点调试时会神秘闪退。
到这里，你就可以愉快地 瞎 JB 改 发电了
开发过程中，每一定数量，记得提交一个 Commit, 别忘了写上 Message
假如你不熟悉 git 的使用，你可能想要新建一个分支进行更改，而不是直接提交在 dev-v2 上
git branch your_own_branch
git checkout your_own_branch
这样你的提交就能在新的分支上生长，不会受到 dev-v2 更新的打扰
完成开发后，推送你修改过的本地分支（以 dev-v2 为例）到远程（Fork 的仓库）
打开 MAA 主仓库。提交一个 Pull Request，等待管理员通过。别忘了你是在 dev-v2 分支上修改，别提交到 master-v2 分支去了
当 MAA 原仓库出现更改（别人做的），你可能需要把这些更改同步到你的分支
关联 MAA 原仓库
git remote add upstream https://github.com/MaaAssistantArknights/MaaAssistantArknights.git
从 MAA 原仓库拉取更新
变基（推荐）或者合并修改
git rebase upstream/dev-v2 # 变基
或者
重复上述 8, 9, 10, 11 中的操作
提示
在打开 VS 之后，和 Git 有关的操作可以不用命令行工具，直接使用 VS 自带的“Git 更改”即可
注意
推荐优先使用 Visual Studio 进行开发。 MAA 项目主要基于 Visual Studio 构建，上述完整环境配置流程已涵盖所有开发需求，开箱即用体验最佳。VSCode 方案仅作为备选，适合已经熟悉 VS Code + CMake + clangd 工作流的开发者，配置门槛相对较高。
如果你偏好使用 VSCode，可以配合 CMake、clangd 等扩展获得代码补全、跳转和调试能力。在完成前述 1–6 步（克隆、依赖、CMake 配置）后，可按以下步骤配置：
在 VS Code 扩展市场安装：
提示
使用 clangd 时，建议禁用 C/C++ 扩展的 IntelliSense（C_Cpp.intelliSenseEngine 设为 disabled），避免与 clangd 冲突。
用 VS Code 打开项目根目录
使用 CMake Tools：
- 状态栏选择 Configure Preset（如
windows-x64、linux-x64 等） - 选择 Build Preset，执行配置与构建
使用 clangd：Linux/macOS 下预设已开启 CMAKE_EXPORT_COMPILE_COMMANDS，clangd 会自动使用 build/compile_commands.json。在 Windows 上如需 clangd 的补全与跳转，需先生成 compile_commands.json：
Windows 下 clangd 配置说明
- 在 VS Installer 中勾选安装 用于 Windows 的 C++ Clang 编译器（clang-cl）
- 需切换为
windows-x64-clang 执行一次 Configure 以在 build/ 下生成 compile_commands.json，此后 clangd 即可使用 - 该 preset 使用 clang-cl 而非 MSVC，无法直接编译出可用产物，实际构建时必须切回
windows-x64 - clangd 基于 clang-cl 的编译信息进行分析，部分代码（如 MSVC 特有扩展）可能仍会显示报错，可忽略，不影响实际 MSVC 编译
命令行切换 preset 示例（在项目根目录执行）：
rem 生成 compile_commands.json（仅 Configure，不构建）
cmake --preset windows-x64-clang
rem 切回 MSVC 进行实际构建
cmake --preset windows-x64
cmake --build --preset windows-x64-RelWithDebInfo
调试：需自行创建 .vscode/launch.json，配置后可启动 MaaWpfGui 或 Debug Demo 进行调试
- 构建：
Ctrl+Shift+B 或通过 CMake Tools 状态栏 - 调试：F5 或运行与调试面板选择对应配置
MAA 使用一系列的格式化工具来保证仓库中的代码和资源文件美观统一，以便于维护和阅读
请确保在提交之前已经格式化，或是启用 Pre-commit Hooks 来进行自动格式化
目前启用的格式化工具如下：
确保你的电脑上有 Python 与 Node 环境
在项目根目录下执行以下命令
pip install pre-commit
pre-commit install
如果pip安装后依然无法运行 Pre-commit，请确认 PIP 安装地址已被添加到 PATH
接下来，每次提交时都将会自动运行格式化工具，来确保你的代码格式符合规范
安装 clang-format 23.1.1 或更高版本
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
