企业官网建设流程全解析

MaaAssistantArknights 开发指南：从环境搭建、PR 流程到代码格式化规范

【免费下载链接】MaaAssistantArknights《明日方舟》小助手，全日常一键长草！| A one-click tool for the daily tasks of Arknights, supporting all clients.项目地址: https://gitcode.com/GitHub_Trending/ma/MaaAssistantArknights

本指南以《明日方舟》小助手 MAA（MaaAssistantArknights）的官方开发文档为主体，完整讲解参与该项目开发的完整路径：从零代码的文档/JSON 修改、GitHub Codespaces 在线开发，到 Windows 本地完整环境配置、VS Code 备选方案，以及 MAA 仓库强制执行的代码与资源格式化规范。读完本文，你将能独立完成"Fork → 克隆 → 配置环境 → 构建运行 → 提交 PR → 同步上游更新"的完整开发闭环，并保证提交的代码通过仓库的格式检查。

::: tip 适用前提 本文以仓库 docs/zh-cn/develop/development.md 为骨架，涉及的命令、预设（preset）与版本号均以当前仓库实际内容为准。本指南主要面向修改 MAA 运行逻辑以外的贡献（配置、资源、文档、界面等）；若想深入改动游戏流程、任务逻辑等运行机制，请先阅读协议文档了解 MAA 的任务协议体系。 :::

我不懂编程，只想改 JSON 文件 / 文档，怎么操作？

如果你完全不会编程，只是希望修改 MAA 的资源 JSON（如任务配置、界面文本、本地化文件）或文档，那么最简单的方式是走纯网页端操作：参考牛牛也能看懂的 GitHub Pull Request 使用指南，全程在浏览器中完成 Fork、编辑与提交 Pull Request，无需在本地安装任何开发环境。

只想改几行代码，又不想配环境？用在线开发环境

如果只需要小改几行代码，但本地配置完整环境成本太高、纯网页编辑又过于难用，MAA 官方推荐使用 GitHub Codespaces 在线开发环境。仓库为开发者预置了三种环境，可按需选择：

在线环境适合快速尝试与验证改动；若你准备长期、深度参与 MAA Core 开发，务必按下一节在本地搭建完整环境。

完整环境配置流程（Windows）

1. Fork 并克隆 dev-v2 分支

MAA 的主开发分支是dev-v2（注意不要与发布分支master-v2混淆）。流程如下：

1. 如果你很久以前 Fork 过仓库，先去自己仓库的Settings页面底部删除旧 Fork，避免旧配置干扰。

2. 打开 MAA 主仓库页面，点击Fork，再点击Create fork。

3. 克隆你自己 Fork 仓库下的dev-v2分支到本地，并同时拉取子模块：

   git clone --recurse-submodules <你的仓库的 git 链接> -b dev-v2 --single-branch

   ::: tip 关于 --single-branch--single-branch只会拉取dev-v2的提交记录。如果之后想切换到其他分支，需要先执行git remote set-branches origin '*'并重新拉取以补齐其他分支信息；或者重新克隆一个不带--single-branch的仓库。 :::

   ::: warning 使用 Git GUI 时 如果正在使用 Visual Studio 等不附带--recurse-submodules参数的 Git GUI，克隆后必须手动执行git submodule update --init拉取子模块，否则构建时会因缺少依赖子模块而失败。 :::

2. 下载预构建的第三方库

MAA 的第三方依赖（如 OpenCV、ONNX Runtime 等）以预构建产物形式发布，无需本地逐个编译。需要先安装 Python 环境，然后在项目根目录执行：

python tools/maadeps-download.py

从 tools/maadeps-download.py 的源码可以看到该脚本的实现要点：

• 默认从MaaAssistantArknights/MaaDeps仓库下载固定版本v2.14.1的依赖包；
• 若不传参数，脚本通过detect_host_triplet()自动识别当前主机的三元组（如 Windows x64 对应maa-x64-windows）；也可显式传入triplet参数指定平台；
• 支持--cache-asset参数：启用后会在本地缓存已下载的资产，便于重复配置环境时加速。

3. 安装 CMake 与 Visual Studio

• 下载并安装CMake（需要 3.23.0 及以上，见 CMakePresets.json 中的cmakeMinimumRequired约束）；
• 下载并安装Visual Studio 2026 Community，安装时务必勾选"基于 C++ 的桌面开发"与".NET 桌面开发"两个工作负载——前者用于编译 MAA Core，后者用于构建 WPF 图形界面MaaWpfGui。

4. 执行 CMake 项目配置

在项目根目录执行：

cmake --preset windows-x64

从 CMakePresets.json 可以看到windows-x64预设的实际配置：

• 生成器为Visual Studio 18 2026，采用多配置模式，Debug/Release/RelWithDebInfo共享同一个build/目录；
• 默认开启BUILD_WPF_GUI、BUILD_DEBUG_DEMO、BUILD_RESOURCE_UPDATER，关闭INSTALL_RESOURCE与INSTALL_PYTHON；
• 通过MAADEPS_TRIPLET指定依赖平台为maa-x64-windows，与第 2 步下载的第三方库对应。

除windows-x64外，仓库还预置了windows-arm64、linux-x64、linux-arm64、macos-x64、macos-arm64、android-arm64、android-x64等平台预设，以及用于 CI 发布的*-publish-*系列预设，跨平台开发者可参照 CMakePresets.json 按需选用。

5. 打开解决方案并启动调试

1. 双击打开build/MAA.slnx文件，Visual Studio 会自动加载整个项目。
2. 在 VS 顶部的配置下拉框中选择Debug与x64。
3. 右键MaaWpfGui，选择"设为启动项目"。
4. 按F5运行，即可启动带调试的 MAA 主程序。

::: tip 触控控制单元的补充下载 若需运行 Win32Controller（Windows 窗口控制）或 MaaFwAdbController（MaaFramework 触控模式）相关功能，需执行：

python tools/maafw-control-unit-download.py

该脚本会自动下载对应平台的MaaWin32ControlUnit.dll/MaaAdbControlUnit.dll到构建输出目录（默认取build/bin下最新生成的目录，也可用--output-dir参数指定目录）。

若还需调试MaaFramework 控制单元相关功能，则需要自行编译 MaaFramework 的 Debug 版本并替换对应的 DLL 文件，否则断点调试时会意外闪退。 :::

6. 开发过程中的 Git 操作

开发期间建议"每完成一定量的修改就提交一个 Commit"，并写清 Message。如果你不熟悉 git 的分支操作，可以先新建一个独立分支，避免直接提交在dev-v2上被上游更新打扰：

git branch your_own_branch git checkout your_own_branch

完成开发后，将修改过的本地分支推送到你 Fork 的远程仓库：

git push origin dev-v2

然后打开 MAA 主仓库页面，提交一个 Pull Request 等待管理员通过。务必确认你提交的是dev-v2分支的修改，不要误提交到master-v2发布分支。

7. 同步 MAA 原仓库的最新更改

当 MAA 原仓库出现他人提交的更新时，需要把这些更改同步到你的分支：

1. 关联 MAA 原仓库为 upstream（地址以你 Fork 的来源仓库为准）：

   git remote add upstream <MAA 主仓库的 git 链接>

2. 从原仓库拉取更新：

   git fetch upstream

3. 变基（推荐）或合并：

   git rebase upstream/dev-v2 # 变基

   或

   git merge # 合并

4. 同步完成后，重复第 6 步中的提交、推送与 PR 操作。

::: tip 在打开 Visual Studio 之后，Git 相关操作可以直接使用 VS 自带的"Git 更改"面板完成，无需额外使用命令行工具。 :::

使用 VS Code 进行开发（可选）

::: warning 推荐优先使用 Visual Studio MAA 项目主要基于 Visual Studio 构建，上述完整环境配置流程已覆盖全部开发需求，开箱即用体验最佳。VS Code 方案仅作为备选，适合已熟悉 VS Code + CMake + clangd 工作流的开发者，配置门槛相对较高。 :::

如果你偏好 VS Code，可在完成前述第 1～6 步（克隆、依赖、CMake 配置）后按以下步骤配置。

推荐扩展

在 VS Code 扩展市场安装以下扩展：

::: tip 避免冲突 使用 clangd 时，建议禁用 C/C++ 扩展的 IntelliSense（将C_Cpp.intelliSenseEngine设为disabled），避免两个补全引擎互相干扰。 :::

配置步骤

1. 用 VS Code 打开项目根目录。
2. 使用CMake Tools：在状态栏选择 Configure Preset（如windows-x64、linux-x64等），再选择 Build Preset 执行配置与构建。
3. 使用clangd：Linux/macOS 下预设已开启CMAKE_EXPORT_COMPILE_COMMANDS（见 CMakePresets.json 中linux-base/macos-base的配置），clangd 会自动使用build/compile_commands.json提供补全与跳转。

::: warning Windows 下 clangd 配置说明 在 Windows 上如需 clangd 的补全与跳转，需先生成compile_commands.json：

• 在 VS Installer 中勾选安装用于 Windows 的 C++ Clang 编译器（clang-cl）；
• 需先切换为windows-x64-clang执行一次 Configure，在build/下生成compile_commands.json，此后 clangd 即可使用；
• 注意：windows-x64-clang预设使用 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

从 CMakePresets.json 的注释可以看出，windows-x64-clang预设被明确标注为 "NOT for building — only for generating compile_commands.json"，它与linux-base、macos-base一样显式开启CMAKE_EXPORT_COMPILE_COMMANDS，是专为 clangd / VS Code 智能提示服务的。 :::

4. 调试：需自行创建.vscode/launch.json，配置后可启动MaaWpfGui或 Debug Demo 进行调试。

快速构建与调试

• 构建：Ctrl+Shift+B，或通过 CMake Tools 状态栏选择构建目标；
• 调试：F5，或使用"运行与调试"面板选择对应配置。

MAA 的文件格式化要求

MAA 使用一系列格式化工具保证仓库中的代码与资源文件美观统一，便于维护与阅读。请确保在提交之前已经格式化，或启用 Pre-commit Hooks 进行自动格式化。

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

这些工具对应的版本与钩子定义可以在仓库根目录的 .pre-commit-config.yaml 中查到：clang-format 镜像 v21.1.8、Prettier v3.7.4、ruff-format v0.14.10、markdownlint-cli2 v0.18.1、oxipng v10.0.0。其中 clang-format 钩子限定了只处理src/MaaCore/目录下的文件，markdownlint 钩子则覆盖docs/目录与根README.md。

利用 Pre-commit Hooks 自动进行代码格式化

1. 确保电脑上有 Python 与 Node 环境；

2. 在项目根目录下执行：

   pip install pre-commit pre-commit install

如果 pip 安装后仍无法运行 pre-commit，请确认 PIP 安装目录已被添加到PATH环境变量。

配置完成后，每次git commit都会自动运行格式化工具（.pre-commit-config.yaml 中还注册了prepare-commit-msg钩子类型），确保提交的代码格式符合仓库规范；不符合规范的文件会在提交时被自动改写或拦截。

在 Visual Studio 中启用 clang-format

1. 安装 clang-format 20.1.0 或更高版本（建议直接使用较新版本，仓库钩子当前固定为 v21.1.8）：

   python -m pip install clang-format

2. 使用 Everything 等工具找到clang-format.exe的安装位置。作为参考，若使用了 Anaconda，clang-format.exe通常安装在YourAnacondaPath/Scripts/clang-format.exe。

3. 在 Visual Studio 的工具 → 选项中搜索clang-format。

4. 点击"启用 ClangFormat 支持"，然后选择"使用自定义 clang-format.exe 文件"，指向第 2 步找到的clang-format.exe。

配置完成后，你的 Visual Studio 即可使用支持 C++20 语法的 clang-format，在编辑 MAA Core 源码（C++ 代码位于 src/MaaCore）时获得即时的自动格式化能力。仓库根目录的 .clang-format 定义了 MAA 的 C++ 格式风格（例如 pre-commit 钩子通过--assume-filename .clang-format指定），.clangd 则为 clangd 提供了额外的索引与配置指引。

使用 clang-formatter.py 批量格式化

你也可以使用仓库自带的 tools/ClangFormatter/clang-formatter.py 脚本，在项目根目录下直接调用 clang-format 批量格式化指定目录：

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

从脚本源码可以看到其完整参数能力：

例如跳过resource/Arknights-Tile-Pos目录与某个具体文件进行格式化：

python tools\ClangFormatter\clang-formatter.py --input=resource\ --ignore="[\"resource/Arknights-Tile-Pos\", \"resource/infrast.json\"]"

结语

MAA 是一个代码库规模庞大、模块边界清晰的项目：src/MaaCore承载核心逻辑，src/MaaWpfGui提供 WPF 桌面界面，docs/维护多语言文档站，tools/汇集各类开发辅助脚本。无论你是想从修改一处 JSON 资源开始轻量参与，还是准备深度投入 MAA Core 开发，本文覆盖的"环境配置 → 构建调试 → 提交 PR → 同步上游"完整流程与仓库统一的格式化规范，都是你融入项目协作的第一步。开始前也别忘了，改动运行逻辑类代码前，先读一遍协议文档把任务协议体系吃透。

【免费下载链接】MaaAssistantArknights《明日方舟》小助手，全日常一键长草！| A one-click tool for the daily tasks of Arknights, supporting all clients.项目地址: https://gitcode.com/GitHub_Trending/ma/MaaAssistantArknights