# 4.1 构建指南

> [!TIP]
> _仅当您准备开发 MaaFramework 本身时，才需要阅读本章节内容。若您仅希望基于 MaaFramework 开发自己的应用，则请参考 [快速开始](1.1-快速开始.md)。_

开始前，请确保已安装 Git、Python 3、CMake 3.24+，以及对应平台的编译链（Windows: MSVC 2022；Linux/macOS: Ninja + g++/clang）。

## 本地开发

1. 完整克隆本仓库及子模块（推荐一次性同步）  
    子模块包含第三方依赖，构建前必须初始化，可重复执行以保证同步。

    ```sh
    git clone --recurse-submodules https://github.com/MaaXYZ/MaaFramework.git
    ```

    或

    ```sh
    git clone https://github.com/MaaXYZ/MaaFramework.git
    cd MaaFramework
    git submodule update --init --recursive
    ```

2. 下载 MaaDeps prebuilt

    ```sh
    python3 tools/maadeps-download.py
    ```

    脚本会自动下载并校验预编译依赖，如遇网络问题可重复执行。

3. 配置 CMake 预设

    - Windows

    ```bash
    cmake --preset "MSVC 2022"
    ```

    - Linux

    ```bash
    # 根据实际情况择一执行
    cmake --preset "NinjaMulti Linux x64"
    # 或者
    cmake --preset "NinjaMulti Linux arm64"
    ```

    - macOS

    ```bash
    cmake --preset "NinjaMulti"
    ```

4. 构建并安装

    ```bash
    cmake --build build --config Release
    cmake --install build --prefix install
    ```

根据需要可将 `--config` 切换为 `Debug`/`RelWithDebInfo`。生成的二进制及相关文件默认位于 `install` 目录。

详情请参考 [Build CI](https://github.com/MaaXYZ/MaaFramework/blob/main/.github/workflows/build.yml) 。

## 在线开发

使用 Codespaces (Dev Container) 一键配置基础开发环境 (Ninja、CMake、g++-13)：

[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://github.com/codespaces/new?hide_repo_select=true&ref=master&repo=632024122)

随后按照 [本地开发](#本地开发) 流程进行配置。
