企业官网建设流程全解析

MaaAssistantArknights 开发环境搭建与代码格式化规范完全指南

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

本篇指南以 MaaAssistantArknights 官方开发者文档（docs/ja-jp/develop/development.md）为主线，系统讲解从零搭建 Windows 完整开发环境、借助 GitHub Codespaces 快速起步、配置 VSCode + CMake + clangd 开发工作流，以及项目强制执行的代码与资源文件格式化规范。读完本文，你将能够独立完成 MAA 的 fork、克隆、构建、调试、格式化提交与向上游同步的完整开发闭环，并理解这些流程背后的仓库级实现细节。

说明：该开发文档主要面向PR（Pull Request）流程与 MAA 的文件格式要求。若你想修改 MAA 的"运行逻辑"（如任务流程、战斗策略），请参阅协议文档，本文聚焦环境与规范本身。

一、开始之前：理解 MAA 的开发分支模型

MAA 的核心开发分支是dev-v2，所有新功能与修复都在该分支上合入，发布时再合并到稳定分支。因此：

• 不要直接在 dev 分支上改代码，建议为每个功能新建独立分支；
• 提交 PR 时目标分支必须是dev-v2，而不是master-v2；
• 长期维护自己的 fork 时，需要定期同步上游更新。

如果你完全不会编程，只是想修改 JSON 资源文件或文档，官方提供了纯网页操作的 PR 教程，可参考「帕拉斯」也能看懂的 GitHub Pull Request 使用指南，无需本地搭建环境。

二、零配置起步：GitHub Codespaces 在线开发环境

如果只是"改几行代码"却不想折腾本地环境，官方在仓库的 .devcontainer 目录下预置了三套不同的在线开发环境（Dev Container），用浏览器即可完成编辑、提交与 PR：

三个环境的实际差异在配置中清晰可见：

• 轻量环境（.devcontainer/0）预装了文档站前端所需的扩展，包括esbenp.prettier-vscode（Prettier 格式化）、DavidAnson.vscode-markdownlint（markdownlint）、vue.volar以及 MAA 专属的nekosu.maa-support，并开启editor.formatOnSave，适合直接修改 docs 目录下的多语言文档。
• 完全环境（.devcontainer/1）在此基础上额外预装了ms-vscode.cmake-tools、xaver.clang-format、llvm-vs-code-extensions.vscode-clangd、ms-python.python与charliermarsh.ruff，并在设置中按语言绑定格式化器（C/C++ 使用 clang-format、Python 使用 ruff），还预置了 venv 路径python.defaultInterpreterPath，开箱即可编译 MAA Core。

官方明确建议：完全环境仅作参考，不推荐作为主力开发方式——MAA Core 的完整构建仍以本地开发为准（见下节）。

三、Windows 完整环境搭建（推荐方式）

官方明确推荐使用Visual Studio作为 MAA 的主力开发环境，下面按官方文档的完整流程逐步展开，并补充仓库中的实际配置作为佐证。

3.1 Fork 与克隆

1. 如果 fork 时间较早，先在个人仓库的Settings最底部删除旧 fork，避免历史包袱。
2. 打开 MAA 主仓库，点击Fork→Create fork创建新 fork。
3. 克隆个人仓库的dev-v2分支（必须包含子模块）：

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

提示：--single-branch只会拉取dev-v2的历史。若之后想切换到其他分支，先执行git remote set-branches origin '*'再git fetch；或者放弃--single-branch重新克隆一次以补全分支信息。

警告：Visual Studio 等不支持--recurse-submodules参数的 Git GUI 克隆后，需要手动补初始化子模块：

git submodule update --init

MAA 使用 git submodule 管理第三方依赖与资源仓库，.devcontainer/post-create.sh中同样执行了git submodule update --init --recursive来保证容器内子模块就绪，可见子模块是该项目的硬性依赖。

3.2 下载预编译的第三方依赖库

克隆完成后需要下载预编译的第三方库（如 OpenCV、ONNX Runtime 等）。项目提供了下载脚本，运行前需确保本机有 Python 环境：

python tools/maadeps-download.py

该脚本位于 tools/maadeps-download.py，它会根据当前平台（Windows/Linux/macOS）与架构自动下载与 CMake preset 中MAADEPS_TRIPLET（如maa-x64-windows）匹配的依赖包，避免从源码逐个编译第三方库的漫长过程。

3.3 安装开发工具链

• 下载并安装CMake；
• 安装Visual Studio 2026 Community，安装时必须勾选以下两个工作负载：
  • C++ 桌面开发（MaaCore 原生代码编译）；
  • .NET 桌面开发（MaaWpfGui 图形界面）。

3.4 配置 CMake 工程

在项目根目录执行：

cmake --preset windows-x64

这一命令对应仓库根目录 CMakePresets.json 中的windows-x64preset。从该文件可以看到：

• windows-x64继承自windows-base，生成器为Visual Studio 18 2026（多配置生成器，Debug/Release/RelWithDebInfo 共用同一 build 目录）；
• 默认开启BUILD_WPF_GUI（WPF 界面）、BUILD_DEBUG_DEMO（Debug 演示程序）与BUILD_RESOURCE_UPDATER；
• 依赖三元组MAADEPS_TRIPLET为maa-x64-windows。

此外仓库还提供了windows-arm64、linux-x64、linux-arm64、macos-x64、macos-arm64及android-*等跨平台 preset，以及windows-x64-RelWithDebInfo等 build preset，供 CI 与多平台开发使用。

3.5 打开工程并启动调试

1. 双击build/MAA.slnx，Visual Studio 会自动加载项目；
2. 在顶部配置栏选择Debug与x64；
3. 右键MaaWpfGui→ 设置为启动项目；
4. 按F5启动调试。

至此环境就绪，可以自由开展开发了。

3.6 补充：Windows 窗口控制与 MaaFramework 触摸模式的控制单元

若要调试Win32Controller（Windows 窗口控制）与MaaFwAdbController（MaaFramework 触摸模式）相关功能，需要额外下载 MaaFramework 发布的"控制单元"（Control Unit）二进制：

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

该脚本（tools/maafw-control-unit-download.py）会自动将对应平台的MaaWin32ControlUnit.dll/MaaAdbControlUnit.dll（macOS 下为libMaaAdbControlUnit.dylib，Linux 下为libMaaAdbControlUnit.so）放入构建输出目录——默认是build/bin下最新的版本目录，可通过--output-dir参数显式指定；--force可强制重新下载。

需要特别注意的是：脚本下载的是 MaaFramework 的Release 构建，与 MAA 的 Release/RelWithDebInfo 构建 ABI 兼容，但与 Debug 构建不兼容（MSVC 的 Debug/Release STL 布局不同，混用会崩溃）。因此调试相关功能时，需要自行编译 MaaFramework 的 Debug 版本并使用其 DLL，否则断点调试时可能发生难以排查的崩溃。

四、VSCode 开发工作流（可选）

官方明确提示：推荐使用 Visual Studio 开发，MAA 项目主要围绕 VS 构建。VSCode 工作流仅作为熟悉 VSCode + CMake + clangd 的开发者的替代方案，配置门槛相对更高。

完成前述步骤 1～6（克隆、依赖、CMake 配置）后，可按以下方式配置：

4.1 推荐扩展

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

4.2 配置步骤

1. 在 VSCode 中打开项目根目录；
2. CMake Tools：在状态栏选择 Configure Preset（如windows-x64、linux-x64），再通过 Build Preset 执行构建；
3. clangd：Linux/macOS 的 preset 已默认开启CMAKE_EXPORT_COMPILE_COMMANDS（见 CMakePresets.json 中linux-base与macos-base的cacheVariables），clangd 会自动使用build/compile_commands.json。Windows 上则需要先手动生成该文件：

Windows 下 clangd 配置要点

• 在 VS Installer 中勾选安装C++ Clang 编译器 for Windows（clang-cl）；
• 切换到windows-x64-clangpreset 执行一次 Configure，即可在build/下生成compile_commands.json；
• 该 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

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

4.3 快捷键

• 构建：Ctrl+Shift+B，或通过 CMake Tools 状态栏；
• 调试：F5，或在 Run and Debug 面板中选择配置。

五、MAA 的文件格式规范

为保证仓库中代码与资源文件风格统一、易于维护与阅读，MAA 使用一整套格式化工具。提交代码前请先格式化，或使用 Pre-commit Hooks 自动格式化。目前启用的格式化工具如下：

这些规则在仓库中有完整落地，具体见 .pre-commit-config.yaml，其中：

• clang-format只作用于^src/MaaCore/.*（MAA Core 源码），使用.clang-format配置；
• Prettier覆盖配置文件（YAML/JSON）与 docs 文档；
• markdownlint针对docs与根 README，使用docs/.markdownlint.yaml配置；
• oxipng对所有 PNG 资源做无损压缩（参数-q -o 2 -s --ng）；
• ruff-format格式化 Python 代码。

C++ 侧的风格基线定义在根目录 .clang-format：基于WebKit风格，ColumnLimit: 120、缩进 4 空格、指针靠左对齐、Standard: c++20，并针对 MAA 实际需求做了大量定制（如BinPackArguments: false、InsertBraces: true、SortIncludes: CaseSensitive等）。

5.1 使用 Pre-commit Hooks 自动格式化

1. 确保本机已安装 Python 与 Node 环境；
2. 在项目根目录执行：

pip install pre-commit pre-commit install

安装成功后，每次git commit都会自动运行格式化工具，确保提交内容符合风格规范。若pip安装后仍无法运行 pre-commit，请检查 pip 安装路径是否已加入PATH。

5.2 在 Visual Studio 中启用 clang-format

1. 安装clang-format 20.1.0 及以上版本：

python -m pip install clang-format

2. 使用 Everything 等工具查找clang-format.exe的安装位置（例如使用 Anaconda 时，通常位于YourAnacondaPath/Scripts/clang-format.exe）；
3. 在 Visual Studio 中进入Tools → Options，搜索clang-format；
4. 勾选"启用 clang-format 支持"，并选择"使用自定义的 clang-format.exe 文件"，填入上一步找到的clang-format.exe路径。

完成配置后，Visual Studio 即可使用支持 C++20 语法的 clang-format，与仓库根目录 .clang-format 中的Standard: c++20保持一致。

5.3 使用仓库自带脚本批量格式化

除了 IDE 集成，仓库还提供了独立的批量格式化脚本 tools/ClangFormatter/clang-formatter.py，可递归处理指定目录/文件。在项目根目录执行：

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

脚本支持以下参数：

• --input：输入目录或文件（如src\MaaCore，脚本会递归遍历）;
• --clang-format：clang-format可执行文件路径，默认clang-format；
• --style：格式化风格，默认file（即读取仓库根目录的 .clang-format）；
• --rule：JSON 格式的文件扩展名数组，默认[".c", ".h", ".cpp", ".hpp"]；
• --ignore：JSON 格式的忽略路径数组（可混用文件与目录），例如：

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

六、提交、推送与 PR 流程

开发过程中建议每完成一定量的修改就提交一次，且必须填写提交信息。不熟悉 Git 的开发者尤其不要直接修改 dev 分支，而是新建独立分支：

git branch your_own_branch git checkout your_own_branch

这样可以免受 dev 分支后续更新的影响，独立开发。

开发完成后将修改推送到远程仓库：

git push origin dev-v2

然后在 MAA 主仓库提交 Pull Request，目标分支务必选择dev-v2（而非master-v2）。

6.1 同步上游仓库更新

当上游仓库有更新时，按以下步骤同步：

# 1. 添加上游仓库 git remote add upstream https://github.com/MaaAssistantArknights/MaaAssistantArknights.git # 2. 拉取上游更新 git fetch upstream # 3. 推荐使用 rebase 合并更新 git rebase upstream/dev-v2 # 或使用 merge git merge

rebase 或 merge 完成后，重复前面的构建、调试、提交与推送步骤即可。

提示：Visual Studio 启动后，可在"Git 更改"面板中直接完成全部 Git 操作，无需命令行。

七、小结

MAA 的开发流程可以概括为一条清晰的链路：fork + 克隆 dev-v2（含子模块）→ 下载预编译依赖 → 按 preset 配置 CMake → VS 启动调试 → 格式化提交 → PR 到 dev-v2。对只想改文档或 JSON 的贡献者，Codespaces 与网页版 PR 教程提供了零本地配置的捷径；对核心开发者，windows-x64-clangpreset 生成的compile_commands.json则打通了 VSCode + clangd 的现代 C++ 开发体验。而贯穿始终的格式化规范（.clang-format + .pre-commit-config.yaml）保证了数千个文件在长期迭代中依然保持统一、可读、可维护。

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