개발 가이드

약 551 단어약 2 분

팁

본 페이지는 주로 PR 과정 및 MAA의 파일 포맷 요구사항을 설명합니다. MAA의 실행 로직 변경에 대한 구체적인 내용은 프로토콜 문서를 참고하세요.

팁

DeepWiki에 문의하여 MAA 프로젝트의 전체적인 아키텍처를 개략적으로 이해할 수 있습니다.

프로그래밍을 잘 모르지만, json 파일과 docs 문서를 수정하고싶어요. 어떻게 해야하나요?

웹 기반 PR 가이드를 참고하세요! (GitHub.com 웹사이트에서만 가능합니다)

몇 줄의 코드만 간단하게 수정하고 싶지만 환경 설정이 너무 복잡하고, 순수 웹 편집도 불편해요. 어떻게 해야 하나요?

GitHub Codespaces 온라인 개발 환경을 사용해보세요!

다음과 같은 다양한 개발 환경을 사전에 설정했습니다：

빈 환경 (순수 Linux 컨테이너) (기본값)
경량 환경, 문서 사이트 프론트엔드 개발에 적합
전체 환경, MAA Core 관련 개발에 적합 (사용 권장하지 않음, 로컬 개발 권장, 관련 환경을 완전히 설정, 다음 섹션 참조)

완전한 환경 설정 (Windows)

이전에 fork 한 기록이 있다면 저장소 Settings 맨 아래에서 삭제
MAA 메인 저장소에서 Fork → Create fork 클릭
본인 저장소의 dev 브랜치를 서브모듈 포함 클론:
```
git clone --recurse-submodules <저장소 git 링크> -b dev-v2 --single-branch
```
팁
--single-branch는 dev-v2 브랜치 기록만 가져옵니다. 나중에 다른 브랜치로 전환하려면 먼저 git remote set-branches origin '*'를 실행한 뒤 다시 fetch해서 다른 브랜치 정보를 받아오거나, --single-branch 없이 저장소를 다시 클론해야 합니다.
경고
Visual Studio 등 --recurse-submodules 미지원 Git GUI 사용 시, 클론 후 다음 실행:
```
git submodule update --init
```
사전 빌드된 외부 라이브러리 다운로드
Python 환경 필요 (별도 설치 필요)
```
python tools/maadeps-download.py
```
개발 환경 구성
- CMake 다운로드 및 설치
- Visual Studio 2026 Community 설치 시 C++ 데스크톱 개발 및 .NET 데스크톱 개발 필수 선택
cmake 프로젝트 구성 실행
```
cmake --preset windows-x64
```
build/MAA.slnx 파일을 더블 클릭하여 엽니다. Visual Studio가 자동으로 전체 프로젝트를 로드합니다.
VS 설정
- 상단 구성에서 Debug x64 선택
- MaaWpfGui 우클릭 → 시작 프로젝트로 설정
- F5 키를 눌러 실행
팁
Win32Controller(Windows 창 제어) / MaaFwAdbController(MaaFramework 터치 수행 방식) 관련 기능을 실행하려면 MaaFramework Releases에서 해당 플랫폼 압축 파일을 다운로드하고, bin 디렉토리의 MaaWin32ControlUnit.dll / MaaAdbControlUnit.dll을 MAA DLL과 같은 디렉토리(예: build/bin/Debug)에 배치해야 합니다. 자동 다운로드 스크립트 PR 환영!
若需调试相关功能，则需要自行编译 MaaFramework 的 Debug 版本，使用对应的 DLL 文件，否则在断点调试时会神秘闪退。
이제 자유롭게 개조 개발 시작!
주기적 커밋 (메시지 필수 작성)
Git 초보자는 dev 브랜치 대신 새 브랜치 생성 권장:
```
git branch your_own_branch
git checkout your_own_branch
```
dev 브랜치 업데이트 영향에서 자유로움
개발 완료 후 변경사항 원격 저장소로 푸시:
```
git push origin dev-v2
```
MAA 메인 저장소에서 Pull Request 제출 (master 대신 dev 브랜치 지정 필수)
업스트림 저장소 변경사항 동기화 방법:
1. 업스트림 저장소 추가:
```
git remote add upstream https://github.com/MaaAssistantArknights/MaaAssistantArknights.git
```
2. 변경사항 가져오기:
```
git fetch upstream
```
3. 리베이스(권장) 또는 병합:
```
git rebase upstream/dev-v2
```
  또는
```
git merge
```
4. 단계 8, 9, 10, 11 반복 수행

팁

Visual Studio 실행 시 Git 작업은 "Git 변경" 탭에서 명령어 없이 처리 가능

Visual Studio를 사용한 개발을 권장합니다. MAA 프로젝트는 주로 Visual Studio를 기반으로 구축되며, 위의 완전한 환경 설정 과정이 모든 개발 요구를 충족하여 최상의 즉시 사용 가능한 경험을 제공합니다. VS Code 워크플로는 VS Code + CMake + clangd에 이미 익숙한 개발자를 위한 대안으로만 제공되며, 설정 난이도가 상대적으로 높습니다.

VSCode를 선호한다면 CMake, clangd 등의 확장을 사용해 코드 완성, 탐색, 디버깅을 할 수 있습니다. 위 1–6단계(클론, 의존성, CMake 설정)를 완료한 후 다음 단계로 설정하세요.

확장	용도
CMake Tools	CMake 설정, 빌드, 디버깅 통합
clangd	C++ IntelliSense, 코드 탐색, 진단 (LSP 기반)
C/C++	C++ 프로그램 디버깅 (CMake Tools 또는 launch.json과 연동)

설정 단계

VSCode에서 프로젝트 루트 열기
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에서 C++용 Clang 컴파일러 (Windows)(clang-cl)를 선택하여 설치
- windows-x64-clang 프리셋으로 전환 후 Configure를 한 번 실행하면 build/에 compile_commands.json이 생성되며, 이후 clangd가 동작합니다
- 해당 프리셋은 clang-cl을 사용하므로 MSVC가 아니어서 실제 빌드 산출물을 생성할 수 없습니다. 실제 빌드 시에는 windows-x64로 다시 전환해야 합니다
- clangd는 clang-cl의 컴파일 정보로 분석하므로, 일부 코드(예: MSVC 전용 확장)에서 오류가 표시될 수 있으나 무시해도 되며 실제 MSVC 빌드에는 영향을 주지 않습니다
명령줄에서 프리셋 전환 예시 (프로젝트 루트에서 실행):
```
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 또는 Run and Debug 패널에서 구성 선택

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