Cocos Creator WeChat 미니게임 빌드와 디버깅 완전 가이드: Build 패널부터 개발자 도구까지

몇 주를 들여 마침내 Cocos Creator 안에서 게임을 완성했습니다.

코드도 다 썼고, 에셋도 가져왔고, 애니메이션도 돌아갑니다. 이제 Build 패널을 열고 WeChat 미니게임 플랫폼에 출시하려는 순간, 진짜 번거로운 일은 그때부터 시작된다는 사실을 알게 됩니다.

libVersion 필드 오류가 납니다. 실제 기기에서 검은 화면이 뜹니다. 패키지 크기가 제한을 넘습니다. iOS 빌드는 바로 실패합니다. 이런 문제들은 게임 개발 튜토리얼에는 거의 나오지 않지만, 하나하나가 프로젝트를 출시 단계에서 멈춰 세울 수 있습니다.

이 글은 바로 그 문제들을 해결하기 위한 가이드입니다. Build 패널의 각 매개변수를 어떻게 채워야 하는지, 빌드 출력 디렉터리에 있는 파일들이 어떤 역할을 하는지, WeChat 개발자 도구에서 실제 기기 디버깅을 어떻게 진행해야 하는지까지 전체 흐름을 나누어 설명합니다. 마지막에는 2026년 WeChat 미니게임 인센티브 정책도 함께 살펴봅니다. 출시가 성공한 뒤 수익을 어떻게 극대화할지도 미리 계획해야 하니까요.

Cocos 프로젝트를 WeChat 미니게임 플랫폼에 출시하려고 준비 중이거나, 이미 시행착오를 겪고 해결책을 찾고 있다면 이 가이드가 도움이 될 것입니다.

Build 패널 매개변수 설정 실전

먼저 Build 패널을 엽니다.

Cocos Creator에서는 두 가지 방법이 있습니다. 메뉴 바에서 “프로젝트 → 빌드 출시”를 클릭하거나, 단축키 Ctrl+Shift+B를 누르면 됩니다. Mac에서는 Cmd+Shift+B입니다. 패널을 열면 출시 경로부터 초기 씬, MD5 Cache, AppID까지 여러 매개변수가 보입니다. 처음 보면 조금 막막할 수 있습니다.

하지만 서두를 필요는 없습니다. 하나씩 나누어 보겠습니다.

공통 매개변수: 기본 설정

출시 경로: 빌드 출력 디렉터리의 위치입니다. 기본적으로 프로젝트 루트에 build 폴더가 생성됩니다. 다른 경로로 바꿀 수도 있지만, 기본값을 유지하는 것을 권장합니다. 그래야 빌드 산출물의 디렉터리 구조가 고정되고, 이후 디버깅할 때도 찾기 쉽습니다.

초기 씬: 게임이 시작될 때 가장 먼저 로드되는 씬입니다. 보통 Boot 씬이나 Loading 씬을 선택합니다. 프로젝트에 진입점이 여러 개라면 여기서는 메인 진입 씬을 선택해야 합니다.

빌드 참여 씬: 프로젝트 안의 모든 씬이 이곳에 표시되며, 패키징해야 하는 씬을 선택합니다. 선택하지 않은 씬은 최종 패키지에 들어가지 않습니다. 흔한 문제가 하나 있습니다. 어떤 개발자는 모든 씬을 다 선택했다가 패키지 크기가 폭발합니다. 실제로 필요한 씬만 선택하고, 나머지 씬은 원격 리소스 서버에 두는 것이 좋습니다.

MD5 Cache: 이 옵션은 켜야 할까요?

켜면 모든 리소스 파일명에 MD5 접미사가 붙습니다. 장점은 리소스가 업데이트될 때 클라이언트가 파일 변화를 자동으로 감지해 오래된 캐시를 로드하지 않는다는 점입니다. 단점은 코드에서 리소스에 접근하는 방식도 바뀌어야 한다는 점입니다.

예를 들어 원래 resources.load('texture/hero')를 사용했다면, MD5 Cache를 켠 뒤 URL은 texture/hero-abc123.png와 비슷한 형태가 됩니다. 이때는 다음 방법으로 올바른 URL을 가져와야 합니다.

// MD5 접미사가 붙은 리소스 경로 가져오기
const url = assetManager.utils.getUrlWithUuid('texture/hero', {
    isScene: false,
    type: 'png'
});

이 API는 Cocos Creator 3.x에서 표준적인 사용법입니다. 아직 2.x를 사용하고 있다면 로직이 약간 다르지만, 핵심은 같습니다. 리소스 경로를 하드코딩하지 말고 엔진이 처리하게 하십시오.

WeChat 미니게임 전용 매개변수: 플랫폼 설정

AppID: 반드시 입력해야 합니다.

AppID가 없으면 빌드 버튼을 클릭했을 때 오류가 납니다. 테스트 계정의 AppID를 사용할 수도 있지만, 테스트 계정에는 기능 제한이 많습니다. 예를 들어 오픈 데이터 도메인을 사용할 수 없고, 정식 출시가 불가능하며, 광고 수익화 기능도 제한됩니다.

AppID 신청 절차는 다음과 같습니다. WeChat 공식 계정 플랫폼에 로그인 → 미니프로그램 관리 → 미니게임 추가 → AppID 획득. 전체 과정에는 보통 1-3일의 심사 시간이 필요하므로 미리 준비하는 것이 좋습니다.

디버그 모드: 빌드 출력에 디버깅 관련 코드와 리소스가 더 포함됩니다. 정식 출시 때는 끄는 것을 권장하지만, 개발 단계에서는 켜 두면 디버깅 시간을 많이 줄일 수 있습니다.

엔진 분리: 이 옵션은 패키지 크기를 크게 줄일 수 있습니다.

선택하면 Cocos 엔진 코드는 게임 본체에 패키징되지 않고 WeChat 서버에서 로드됩니다. 엔진 분리를 켜려면 몇 가지 전제 조건이 있습니다.

• Debug Base Library 버전 2.9.0 이상(WeChat 개발자 도구에서 설정)
• WebAssembly 기능은 WeChat 클라이언트 버전 v7.0.17 이상 필요

엔진 분리의 장점은 첫 패키지를 4MB 이하로 제어하기 쉽다는 것입니다. 단점은 엔진 로딩에 시간이 걸려, 플레이어가 처음 게임에 진입할 때 짧은 대기 시간이 생긴다는 점입니다. 프로젝트 리소스가 많다면 엔진 분리는 거의 필수 옵션에 가깝습니다.

서브도메인 설정: 게임에서 랭킹, 친구 공유 같은 오픈 데이터 도메인 기능을 사용하려면 여기에서 서브도메인 관련 정보를 설정해야 합니다. 서브도메인은 메인 게임과 격리된 독립 실행 환경이며, 소셜 데이터를 전담합니다. 설정이 잘못되면 랭킹 기능이 동작하지 않을 수 있습니다.

쉽게 놓치는 작은 디테일

Build 패널 하단에는 “빌드” 버튼이 있고, 그 옆에 “생성” 버튼이 있습니다.

많은 사람이 “빌드”를 누른 뒤 작업이 끝났다고 생각합니다. 하지만 “빌드”는 빌드 출력 디렉터리를 생성할 뿐, 최종 코드 패키징까지 수행하지는 않습니다. “생성”을 눌러야 전체 패키징 절차가 실행되고 WeChat 미니게임에 필요한 game.js, game.json 같은 진입 파일이 만들어집니다.

저도 처음 출시할 때 “빌드”만 누르고 바로 WeChat 개발자 도구로 프로젝트를 가져갔다가 “진입 파일을 찾을 수 없음” 오류를 만났습니다. 이유는 “생성”을 누르지 않았기 때문입니다. 공식 문서에도 쓰여 있지만, 아주 쉽게 놓치는 디테일입니다.

빌드 산출물 해석과 자주 만나는 함정 체크리스트

빌드가 끝나면 프로젝트 루트의 build 폴더를 확인합니다.

그 안에는 wechatgame 디렉터리가 있습니다. 이것이 WeChat 미니게임 플랫폼용 빌드 출력입니다. 이 디렉터리를 열면 여러 파일과 폴더가 보입니다. 일부는 Cocos가 생성한 것이고, 일부는 WeChat 미니게임 전용 설정입니다. 각각의 역할을 살펴보겠습니다.

핵심 설정 파일 해석

game.js: 엔진 시작 진입점입니다.

WeChat 미니게임 플랫폼이 게임을 로드할 때 가장 먼저 실행하는 파일입니다. Cocos 엔진 초기화 코드와 씬 로딩 로직이 들어 있습니다. 이 파일을 직접 수정할 필요는 없지만, 빌드에 문제가 생겼다면 문법 오류가 있는지 확인할 수 있습니다.

game.json: 전역 설정 파일입니다.

{
    "deviceOrientation": "portrait",
    "networkTimeout": {
        "request": 60000,
        "connectSocket": 60000,
        "uploadFile": 60000,
        "downloadFile": 60000
    },
    "enginePlugins": [
        "cocos"
    ],
    "optimization": {
        "render": true,
        "fps": true
    }
}

핵심 필드는 다음과 같습니다.

• deviceOrientation: 화면 방향입니다. portrait는 세로 화면, landscape는 가로 화면입니다.
• networkTimeout: 네트워크 요청 타임아웃이며 단위는 밀리초입니다.
• enginePlugins: 엔진 플러그인 설정입니다. 엔진 분리를 켜면 여기에 "cocos"가 표시됩니다.
• optimization: 성능 최적화 옵션입니다. render와 fps는 기본적으로 켜져 있습니다.

project.config.json: WeChat 개발자 도구의 프로젝트 설정입니다.

{
    "miniprogramRoot": "./",
    "setting": {
        "urlCheck": false,
        "es6": true,
        "postcss": true,
        "minified": true
    },
    "compileType": "game",
    "libVersion": "2.25.0",
    "appid": "wx1234567890abcdef",
    "projectname": "my-game"
}

여기에 함정이 하나 있습니다. 바로 libVersion 필드입니다.

함정 체크리스트: 자주 만나는 다섯 가지 문제

함정 1: libVersion 필드가 무효

증상: WeChat 개발자 도구에서 기본 라이브러리 버전이 유효하지 않다는 오류가 납니다.

원인: Cocos 빌드 시 자동 생성된 libVersion 필드가 현재 WeChat 플랫폼에서 지원하는 버전 번호가 아닐 수 있습니다. 예를 들어 빌드 출력은 "2.25.0"인데, WeChat 개발자 도구에는 "2.20.3" 또는 "latest" 옵션만 있을 수 있습니다.

해결책: project.config.json을 직접 수정해 libVersion을 "widelyUsed" 또는 "latest"로 바꿉니다.

{
    "libVersion": "widelyUsed"
}

widelyUsed는 WeChat 플랫폼이 권장하는 안정 버전이라 호환성이 가장 좋습니다. latest는 최신 버전이어서 기능은 더 많지만 새로운 문제가 있을 수 있습니다. 먼저 widelyUsed를 사용하고, 안정화된 뒤 latest를 시도하는 편이 좋습니다.

함정 2: self is not defined

증상: 빌드는 성공했지만 실제 기기에서 실행할 때 self is not defined 오류가 납니다.

원인: 프로젝트에서 socket.io 라이브러리를 사용했습니다. WeChat 미니게임 환경에는 window.self 전역 객체가 없고, socket.io의 일부 버전은 이 객체에 접근하려고 합니다.

해결책: socket.io v1.4.4 버전을 사용합니다.

npm install [email protected] --save

v1.4.4는 WeChat 미니게임 환경과 호환되는 마지막 안정 버전입니다. 더 높은 버전은 많은 리팩터링을 거쳤지만 self 의존성을 도입했습니다. 프로젝트에서 반드시 높은 버전의 socket.io를 써야 한다면 소스 코드를 직접 patch해 self를 window 또는 global로 바꿔야 합니다.

함정 3: 순환 참조 JSON 오류

증상: 빌드 중 특정 JSON 파일에 순환 참조가 있다는 오류가 납니다.

원인: 코드 안의 어떤 전역 객체가 잘못 직렬화되었습니다. 예를 들어 window.global에 복잡한 객체가 저장되어 있고, 빌드 시 Cocos가 이를 JSON으로 변환하려다 객체 내부의 순환 참조를 발견하는 경우입니다.

해결책: window.global 초기화 로직을 확인합니다.

// 잘못된 예: 전역 객체가 자기 자신을 참조함
window.global = {
    self: window.global  // 순환 참조
};

// 올바른 예: 자기 참조를 피함
window.global = {
    config: {},
    gameState: {}
};

빌드 전에 이런 순환 참조를 정리하십시오. 복잡한 객체를 반드시 저장해야 한다면 JSON.stringify와 JSON.parse로 직접 직렬화하고, 순환 참조가 있는 부분을 건너뛰는 방식으로 처리할 수 있습니다.

함정 4: 엔진 분리 후 MiniGameCenter가 사라짐

증상: 엔진 분리를 켜고 빌드도 성공했지만, WeChat 개발자 도구에서 MiniGameCenter 관련 기능을 찾을 수 없습니다.

원인: MiniGameCenter는 WeChat 미니게임의 서비스 컴포넌트이며 엔진 코드에 의존합니다. 엔진을 분리하면 MiniGameCenter의 일부 기능이 동작하지 않을 수 있습니다.

해결책: 일단 엔진 분리를 켜지 않습니다.

MiniGameCenter의 전체 기능이 필요하다면, 예를 들어 광고나 인앱 구매를 테스트해야 한다면 먼저 엔진 분리 옵션을 끄고 엔진 코드를 첫 패키지에 포함하십시오. 기능 테스트가 끝난 뒤 정식 출시 전에 엔진 분리를 켤지 다시 판단하면 됩니다.

함정 5: iOS 빌드 실패

증상: iOS 플랫폼 버전을 빌드할 때 특정 의존 라이브러리나 리소스 파일을 찾을 수 없다는 오류가 납니다.

원인: iOS 빌드 절차는 WeChat 미니게임보다 더 복잡하며, 몇 가지 조건을 확인해야 합니다.

• Xcode 버전이 맞는지 확인합니다. Xcode 12 이상을 권장합니다.
• 의존 라이브러리 경로가 올바른지 확인합니다. Podfile 또는 Carthage 설정을 점검합니다.
• 리소스 파일이 완전한지 확인합니다. 특히 이미지와 오디오 파일을 확인합니다.

해결책:

1. Xcode를 열고 빌드 로그를 확인해 구체적인 오류 메시지를 찾습니다.
2. Podfile의 의존 라이브러리 버전과 로컬에 설치된 버전이 일치하는지 확인합니다.
3. 빌드 캐시를 정리합니다. rm -rf build/ios를 실행한 뒤 다시 빌드합니다.

iOS 빌드 문제는 종류가 다양해서 구체적인 오류별로 따로 분석해야 합니다. 그래도 대부분의 경우 캐시를 정리하고 다시 빌드하면 해결됩니다.

패키지 제한: 크기를 어떻게 제어할까

WeChat 미니게임에는 두 가지 패키지 크기 제한이 있습니다.

• 첫 패키지 제한: 4MB
• 전체 패키지 제한: 20MB(첫 패키지 + 서브패키지)

제한을 넘으면 어떻게 해야 할까요?

방법 1: 리소스 원격화

대부분의 이미지와 오디오를 원격 서버에 두고, 첫 패키지에는 코드와 필수적인 작은 리소스만 넣습니다. Cocos의 assetManager는 원격 URL에서 리소스를 로드할 수 있습니다.

assetManager.loadRemote('https://your-server.com/assets/hero.png', (err, texture) => {
    if (err) {
        console.error('리소스 로딩 실패', err);
        return;
    }
    // 로드된 리소스 사용
});

원격 리소스 로딩에는 문제가 하나 있습니다. 첫 로딩에 시간이 걸리기 때문에 플레이어 경험에 지연이 생길 수 있습니다. 가장 자주 쓰는 리소스는 첫 패키지에 남기고, 덜 쓰는 리소스만 원격에 두는 것을 권장합니다.

방법 2: 서브패키지 로딩

WeChat 미니게임은 서브패키지를 지원합니다. 게임을 여러 모듈로 나누고, 각 모듈을 하나의 서브패키지로 만듭니다. 플레이어가 특정 씬에 진입할 때만 해당 서브패키지를 로드합니다.

// game.json에서 서브패키지 설정
{
    "subpackages": [
        {
            "name": "level-1",
            "root": "subpackages/level-1"
        },
        {
            "name": "level-2",
            "root": "subpackages/level-2"
        }
    ]
}

서브패키지 로딩에는 Cocos 빌드 절차의 추가 설정이 필요합니다. 구체적인 단계는 Cocos 공식 문서의 “서브패키지 빌드” 장을 참고하면 됩니다.

WeChat 개발자 도구 디버깅 실전

빌드가 끝났다면 이제 WeChat 개발자 도구로 들어갑니다.

많은 사람이 이 단계에서 실수합니다. “새 프로젝트”를 클릭하고 잘못된 디렉터리를 선택하는 것입니다. 올바른 방법은 “프로젝트 가져오기”를 클릭한 뒤 Cocos 빌드 출력인 build/wechatgame 디렉터리를 선택하는 것입니다.

가져온 뒤에는 프로젝트 설정 화면이 보입니다. 핵심 설정 몇 가지를 보겠습니다.

기본 라이브러리 버전 설정

오른쪽 위에 “상세” 버튼이 있고, 클릭하면 “로컬 설정” 탭을 볼 수 있습니다.

그 안에는 “디버그 기본 라이브러리” 드롭다운이 있습니다. 여기서는 widelyUsed 또는 latest를 선택해야 합니다. 앞서 project.config.json을 수정했을 때와 같습니다. 존재하지 않는 버전 번호를 선택하면 도구에서 오류가 납니다.

합법 도메인 검사 안 함

테스트 단계에서는 리소스 서버 도메인이 아직 WeChat 공식 계정 플랫폼에 등록되어 있지 않을 수 있습니다. 이때는 “합법 도메인, web-view(업무 도메인), TLS 버전 및 HTTPS 인증서를 검사하지 않음” 옵션을 선택해야 합니다.

이 옵션을 켜면 도구가 등록되지 않은 도메인의 요청을 차단하지 않습니다. 다만 정식 출시 전에는 도메인을 화이트리스트에 추가해야 합니다. 그렇지 않으면 플레이어가 원격 리소스를 로드할 수 없습니다.

실제 기기 디버깅 절차

도구 모음의 “실제 기기 디버깅” 버튼을 클릭합니다.

WeChat 개발자 도구 v1.05 이상 버전에는 실제 기기 디버깅 v2 기능이 도입되었습니다. 이전 버전과 비교하면 v2에는 몇 가지 개선점이 있습니다.

1. QR 코드 미리 보기가 더 안정적입니다.
2. 원격 디버깅과 Chrome DevTools가 매끄럽게 통합됩니다.
3. 중단점 디버깅과 성능 모니터링의 동시 표시를 지원합니다.

구체적인 절차는 다음과 같습니다.

1. “실제 기기 디버깅”을 클릭해 QR 코드를 생성합니다.
2. 휴대폰에서 WeChat을 열고 QR 코드를 스캔해 디버그 모드로 진입합니다.
3. 도구 화면 오른쪽에 Chrome DevTools와 같은 디버깅 패널이 나타납니다.

디버깅 패널에서 자주 쓰는 기능은 다음과 같습니다.

• Console: 로그 출력을 확인합니다. console.log 내용이 실시간으로 표시됩니다.
• Sources: 소스 코드를 확인하고 중단점을 설정할 수 있습니다.
• Network: 네트워크 요청을 확인하고 리소스가 성공적으로 로드됐는지 점검합니다.
• Memory: 메모리 분석 도구로 메모리 누수가 있는지 확인합니다.

실제 기기 디버깅은 시뮬레이터 디버깅보다 훨씬 현실적입니다. 시뮬레이터의 성능 표현은 실제 기기와 차이가 크며, 특히 저사양 Android 기기에서 차이가 큽니다. 여러 번 실제 기기 디버깅을 실행해 다양한 기기를 커버하는 것을 권장합니다.

성능 모니터링 도구: 어떻게 사용할까

WeChat 개발자 도구에는 완전한 성능 모니터링 도구 세트가 들어 있습니다.

“개발 도구상자” 버튼을 클릭하면, 이 버튼은 도구 모음 오른쪽에 있으며 진단 패널이 열립니다. 그 안에는 몇 가지 핵심 기능이 있습니다.

실제 기기 성능 모니터링

QR 코드를 스캔한 뒤 휴대폰에서 게임을 실행하면, 도구가 FPS, 메모리, CPU 데이터를 실시간으로 표시합니다.

데이터는 차트 형태로 나타납니다. 다음 항목을 직관적으로 볼 수 있습니다.

• FPS가 안정적인지 확인합니다. 60FPS가 이상적이며, 30FPS 미만이면 눈에 띄는 끊김이 생깁니다.
• 메모리가 계속 증가하는지 확인합니다. 계속 오른다면 메모리 누수가 있다는 뜻입니다.
• CPU 점유율이 너무 높은지 확인합니다. 50%를 넘으면 계산 부담이 크다는 신호입니다.

첫 화면 렌더링 분석

“첫 화면 렌더링” 옵션을 클릭하면, 도구가 게임 시작부터 첫 화면이 완전히 표시될 때까지 걸린 시간을 기록합니다.

이 데이터는 매우 중요합니다. 플레이어가 3초 이상 기다리면 이탈률이 뚜렷하게 올라갑니다. 첫 화면 렌더링 시간이 3초를 넘는다면 최적화가 필요합니다.

• 첫 화면 리소스 수를 줄입니다.
• 더 작은 이미지 크기를 사용합니다.
• 필수적이지 않은 리소스는 첫 화면 이후에 로드합니다.

로딩 성능 분석

도구는 모든 리소스의 로딩 시간을 나열합니다. 어떤 리소스가 가장 느리게 로드되는지 확인하고, 그에 맞춰 최적화할 수 있습니다.

예를 들어 2MB PNG 이미지 하나를 로드하는 데 500ms가 걸린다면 다음을 고려할 수 있습니다.

• WebP 형식으로 변환합니다. 용량을 30%-50% 줄일 수 있습니다.
• 이미지 해상도를 압축합니다.
• 캐시에 미리 로드합니다.

런타임 성능 분석

이 기능은 게임 실행 중의 성능 병목을 기록합니다.

예를 들어 어떤 씬 전환 중 FPS가 갑자기 떨어지면, 도구가 하락 원인을 표시합니다. 특정 애니메이션의 계산량이 너무 클 수도 있고, 특정 스크립트 실행 시간이 너무 길 수도 있습니다.

고성능 모드: iOS 전용 최적화

iOS 기기에서 WeChat 미니게임에는 “고성능 모드”가 있습니다.

켜면 게임이 WeChat 클라이언트와 프로세스를 공유하지 않고 독립 프로세스에서 실행됩니다. 장점은 CPU와 메모리 리소스가 더 독립적이고, 성능 향상이 뚜렷하다는 것입니다.

공식 테스트 데이터에 따르면 iPhone 11 Pro Max에서 수족관 Demo의 FPS가 13에서 49로 올랐습니다. 상당히 큰 향상입니다.

켜는 방법

1. WeChat 공식 계정 플랫폼에 로그인합니다.
2. “생산 효율 패키지” 관리 페이지로 들어갑니다.
3. iOS 고성능 모드 서비스를 활성화합니다.

활성화한 뒤 game.json에 다음 설정을 추가합니다.

{
    "iOSHighPerformance": true
}

메모리 제한에 주의

고성능 모드에는 추가 메모리 제한이 있습니다.

• 2GB RAM 기기(iPhone 8, iPhone 7): 1GB 제한
• 3GB RAM 기기(iPhone 11, iPhone 12): 1.4GB 제한

제한을 넘으면 메모리 경고가 발생하고, 심하면 크래시가 날 수 있습니다. 게임 리소스가 많다면 메모리 피크를 제어해야 합니다.

실측 기준의 권장 사항은 다음과 같습니다.

• 고성능 모드를 켜면 FPS는 뚜렷하게 향상되지만 메모리 사용량도 증가합니다.
• 저사양 기기(iPhone 8)에서는 리소스를 800MB 이하로 제어하는 것이 비교적 안정적입니다.
• 고사양 기기(iPhone 12)에서는 1.2GB까지 여유를 둘 수 있습니다.

고성능 모드를 켠 뒤에는 실제 기기 성능 모니터링을 한 번 실행해 FPS와 메모리가 모두 안전 범위 안에 있는지 확인하십시오.

2026년 WeChat 미니게임 정책 해석

게임을 출시했다면 다음은 운영과 수익입니다.

2026년 WeChat 미니게임은 새로운 인센티브 정책을 내놓았습니다. 개발자에게는 긍정적인 변화입니다. 핵심 조항을 간단히 해석해 보겠습니다.

IAP(인앱 구매 수익화) 인센티브 신규 정책

게임이 인앱 구매 수익화를 사용한다면 최초 출시 기간에 추가 인센티브가 있습니다.

인센티브 비율: 100%+

구체적인 구성은 다음과 같습니다.

• 기본 수익 배분: 70%(개발자 70%, WeChat 플랫폼 30%)
• 최초 출시 인센티브: 추가 40%

합산하면 최초 출시 기간에 개발자가 실제로 받는 비율은 70% + 40% = **110%**입니다. 맞습니다. 매출보다 10% 더 많습니다.

이 인센티브 정책에는 시간 창이 있습니다. 최초 출시 신작 게임 기간 동안, 앞선 1000만 위안 매출에 110% 인센티브가 적용됩니다. 1000만 위안을 넘으면 기본 70%로 돌아갑니다.

인센티브 상한: 400만 위안(2026년 상반기)

단일 게임은 최초 출시 기간에 최대 400만 위안의 인센티브를 받을 수 있습니다. 게임 매출이 1000만 위안을 돌파하면 인센티브는 비율대로 계산됩니다. 1000만 위안 × 40% = 400만 위안입니다. 정확히 상한에 도달합니다.

최초 출시 성장 인센티브: 매출이 200만 위안씩 찰 때마다 현금 5% 추가

이는 최초 출시 인센티브 위에 더해지는 항목입니다. 예를 들어 게임의 최초 출시 기간 매출이 600만 위안이라면 다음과 같습니다.

• 기본 수익 배분: 600만 × 70% = 420만
• 최초 출시 인센티브: 600만 × 40% = 240만(상한 400만 이내)
• 성장 인센티브: 600만 ÷ 200만 = 3회, 매회 5%, 총 600만 × 15% = 90만

합계: 420 + 240 + 90 = 750만

비교해 보면 인센티브 정책이 없다면 600만 위안 매출에서 받을 수 있는 금액은 420만 위안뿐입니다. 정책이 더해지면 330만 위안을 더 받습니다.

IAA(광고 수익화) 인센티브 신규 정책

게임이 광고 수익화(IAA)를 사용한다면 여기에도 인센티브 정책이 있습니다.

라이트 IAA 게임: 30일 매출의 40% 인센티브

라이트 게임은 캐주얼, 퍼즐, 매치류처럼 플레이 방식이 단순한 게임을 뜻합니다. 이런 게임은 사용자 수가 많지만 사용자 1명당 결제 의향은 낮아 광고 수익화에 적합합니다.

계산 방식은 출시 후 30일 안의 광고 매출 × 40%를 인센티브로 지급하는 방식입니다.

미드/하드코어 IAA 게임: 90일 매출의 35% 인센티브

미드/하드코어 게임은 액션, RPG, 전략처럼 플레이 방식이 더 복잡한 게임을 뜻합니다. 이런 게임은 사용자 수는 상대적으로 작지만, 사용자 1명당 활성 시간이 더 길어 광고 노출 횟수가 많습니다.

계산 방식은 출시 후 90일 안의 광고 매출 × 35%입니다.

수익 극대화 전략

정책 조항을 이해했다면, 이제 수익을 어떻게 극대화할까요?

최초 출시 시점 계획

최초 출시 인센티브 기간은 앞선 1000만 위안 매출만 커버합니다. 게임의 잠재력이 크다면 사용자가 활발한 시기, 예를 들어 겨울/여름 방학이나 공휴일에 최초 출시 시점을 맞추는 것이 좋습니다. 그래야 인센티브 기간 안에 빠르게 매출을 끌어올릴 수 있습니다.

예를 들어 보겠습니다.

• 일반 시기 최초 출시: 인센티브 기간 매출 500만, 인센티브 200만
• 겨울 방학 시기 최초 출시: 인센티브 기간 매출 1000만, 인센티브 400만(상한)

차이가 두 배입니다.

매출 리듬 제어

인센티브는 매출 비율에 따라 지급됩니다. 게임 매출이 너무 빠르게 증가하면 인센티브 기간이 금방 끝납니다. 단계별 홍보를 고려할 수 있습니다.

1. 최초 출시 기간: 소규모 홍보로 사용자 피드백을 테스트합니다.
2. 인센티브 기간 안: 대규모 홍보로 빠르게 매출을 끌어올립니다.
3. 인센티브 기간 이후: 안정적으로 운영하면서 비용을 제어합니다.

이렇게 하면 인센티브 기간 안의 매출을 극대화하면서도 홍보 비용이 지나치게 높아지는 것을 피할 수 있습니다.

수익화 모델 선택

인앱 구매 수익화와 광고 수익화 중 무엇을 선택해야 할까요?

• 플레이 방식이 단순하고 사용자 수가 많다면 광고 수익화가 더 적합합니다. 라이트 IAA 인센티브는 40%입니다.
• 플레이 방식이 복잡하고 사용자 결제 의향이 강하다면 인앱 구매 수익화가 더 적합합니다. 최초 출시 인센티브는 110%입니다.

일부 게임은 혼합 수익화를 사용할 수 있습니다. 인앱 구매를 중심으로 하고 광고를 보조로 두는 방식입니다. WeChat 플랫폼도 혼합 수익화 모델을 지원하며, 인센티브 정책은 각각 별도로 계산됩니다.

심사 자격 체크리스트

출시 전에는 다음 자격을 준비하십시오.

• 소프트웨어 저작권: 게임 코드의 저작권 귀속을 증명하는 소프트웨어 저작권 증서입니다.
• ICP 등록: 게임에 원격 리소스 서버가 있다면 도메인 등록이 필요합니다.
• 판호: 온라인 게임 출판물 번호입니다. 정식 출시에는 필수입니다. 현재 미니게임은 먼저 “시범 운영” 자격을 사용할 수 있고, 판호는 이후 보완할 수 있습니다.
• 개인정보 처리방침: 게임 시작 시 개인정보 처리방침을 보여주고, 사용자가 동의한 뒤에만 진입할 수 있어야 합니다.
• 미성년자 과몰입 방지: 실명 인증, 게임 시간 제한, 충전 한도 설정이 필요합니다.

각 자격의 신청 주기는 대략 다음과 같습니다.

• 소프트웨어 저작권: 1-2개월
• ICP 등록: 1-2주
• 판호: 3-6개월(가장 오래 걸림)
• 과몰입 방지 기능: 개발 1-2주, WeChat 공식 인터페이스 연동 필요

미리 계획하는 것이 좋습니다. 판호 신청 주기가 가장 길기 때문에 게임 개발 단계에서부터 준비를 시작할 수 있습니다.

정책 정보는 WeChat 공식 커뮤니티의 2026년 인센티브 정책 문서에서 가져온 것입니다. 구체적인 조항은 조정될 수 있으므로, 출시 전에는 WeChat 공식 계정 플랫폼에서 최신 버전을 다시 확인하는 것을 권장합니다.

마무리

Cocos Creator로 WeChat 미니게임을 출시하는 절차는 짧지 않습니다. 하지만 나누어 보면 각 단계에는 분명한 흐름이 있습니다.

Build 패널 매개변수에서는 AppID 필수 입력, MD5 Cache를 켠 뒤의 URL 변환, 엔진 분리의 전제 조건, 빌드와 생성의 차이를 확인해야 합니다.

빌드 출력 디렉터리에서는 game.js, game.json, project.config.json이 각각 다른 역할을 합니다. 함정 체크리스트의 다섯 가지 문제, 즉 libVersion 무효, self 미정의, 순환 참조, MiniGameCenter 사라짐, iOS 빌드 실패도 각각 대응 방법이 있습니다.

WeChat 개발자 도구 디버깅에서는 프로젝트 가져오기, 기본 라이브러리 버전 설정, 실제 기기 디버깅, 성능 모니터링을 챙겨야 합니다. iOS 고성능 모드는 FPS를 크게 높일 수 있지만 메모리 제한도 함께 주의해야 합니다.

2026년 인센티브 정책은 인앱 구매 최초 출시 110%, 인센티브 상한 400만 위안, 광고 수익화 35%-40%가 핵심입니다. 최초 출시 시점, 매출 리듬, 수익화 모델을 잘 계획하면 수익을 두 배로 늘릴 여지도 있습니다.

출시를 준비 중이라면 다음 순서로 진행하십시오.

1. Build 설정을 확인하고, 매개변수 설명과 대조해 하나씩 점검합니다.
2. 빌드가 끝나면 함정 체크리스트로 문제를 배제합니다.
3. 실제 기기 디버깅을 여러 차례 실행하고, FPS와 메모리를 모두 모니터링합니다.
4. 출시 전 자격을 준비하고, 최초 출시 시점을 계획해 인센티브 수익을 극대화합니다.

WeChat 미니게임 플랫폼의 정책과 기술 세부 사항은 빠르게 바뀝니다. 이 글은 2026년 상반기의 공식 문서와 실전 경험을 바탕으로 작성되었으며, 이후 업데이트가 있다면 다시 확인해야 할 수 있습니다. 그래도 핵심 빌드 절차와 디버깅 방법은 기본적으로 안정적입니다.

궁금한 점이 있다면 댓글 영역에서 함께 이야기해 주세요.