Cocos Creator WeChat-Minispiel: Build & Debug – vom Build-Panel bis zu den Developer Tools

Sie haben wochenlang an Ihrem Spiel in Cocos Creator gearbeitet.

Der Code steht, Assets sind importiert, Animationen laufen. Dann öffnen Sie das Build-Panel, um auf die WeChat-Minispiel-Plattform zu veröffentlichen – und merken: Genau hier beginnt der eigentliche Aufwand.

libVersion-Fehler. Schwarzer Bildschirm auf dem Realgerät. Paket zu groß. iOS-Build bricht ab. Keines dieser Probleme taucht in typischen Game-Dev-Tutorials auf – aber jedes einzelne kann Ihr Projekt beim Release stoppen.

Dieser Artikel adressiert genau diese Punkte: jeden Parameter im Build-Panel, die Rolle der Dateien im Build-Ausgabeverzeichnis und konkrete Schritte für Realgeräte-Debug in den WeChat-Developer-Tools. Am Ende folgt die WeChat-Minispiel-Förderpolitik 2026 – denn nach erfolgreichem Release sollten Sie Einnahmen von Anfang an mitplanen.

Wenn Sie ein Cocos-Projekt für WeChat-Minispiele vorbereiten oder nach Lösungen für bekannte Fallen suchen, sollte Ihnen dieser Leitfaden weiterhelfen.

Build-Panel: Parameter in der Praxis

Öffnen Sie zuerst das Build-Panel.

In Cocos Creator geht das über Projekt → Build veröffentlichen im Menü oder per Shortcut Ctrl+Shift+B (Mac: Cmd+Shift+B). Beim ersten Blick wirken die vielen Optionen – Publish-Pfad, Start-Szene, MD5 Cache, AppID – etwas überwältigend.

Kein Problem: Schauen wir uns alles der Reihe nach an.

Allgemeine Parameter: Grundkonfiguration

Publish-Pfad: Verzeichnis für die Build-Ausgabe. Standard ist ein build-Ordner im Projektroot. Sie können einen anderen Pfad wählen – ich empfehle den Standard, damit die Struktur vorhersehbar bleibt und Sie beim Debuggen schneller fündig werden.

Start-Szene: Die Szene, die beim Spielstart geladen wird. Meist Boot- oder Loading-Szene. Bei mehreren Einstiegen wählen Sie den Haupt-Einstieg.

Szenen im Build: Alle Projektszenen werden aufgelistet; nur angehakte Szenen landen im finalen Paket. Häufiger Fehler: alle Szenen ankreuzen und das Paket explodiert. Nur wirklich benötigte Szenen einbinden – den Rest können Sie auf einen Remote-Asset-Server legen.

MD5 Cache: Sollten Sie das aktivieren?

Aktiviert, erhalten alle Asset-Dateinamen ein MD5-Suffix. Vorteil: Bei Asset-Updates erkennt der Client Änderungen und lädt keine veralteten Caches. Nachteil: Der Code für Asset-Zugriffe muss angepasst werden.

Statt resources.load('texture/hero') wird die URL etwa zu texture/hero-abc123.png. So holen Sie die korrekte URL:

// Pfad mit MD5-Suffix abrufen
const url = assetManager.utils.getUrlWithUuid('texture/hero', {
    isScene: false,
    type: 'png'
});

In Cocos Creator 3.x ist das Standard. In 2.x leicht anders, aber das Prinzip gilt: keine hart codierten Pfade – die Engine soll das übernehmen.

WeChat-spezifische Parameter: Plattform

AppID: Pflichtfeld.

Ohne AppID schlägt der Build fehl. Eine Test-AppID funktioniert, ist aber eingeschränkt: kein Open-Data-Subdomain, kein Live-Release, eingeschränkte Werbe-Monetarisierung.

AppID beantragen: WeChat Public Platform → Mini-Programm-Verwaltung → Minispiel hinzufügen → AppID erhalten. Die Prüfung dauert etwa 1–3 Tage – rechtzeitig planen.

Debug-Modus: Mehr Debug-Code und -Ressourcen in der Ausgabe. Für Release deaktivieren; in der Entwicklung spart es Debug-Zeit.

Engine-Separation: Reduziert die Paketgröße deutlich.

Aktiviert, wird der Cocos-Engine-Code nicht ins Spielpaket gepackt, sondern von WeChat-Servern geladen. Voraussetzungen:

• Debug Base Library ≥ 2.9.0 (in den WeChat-Developer-Tools)
• WebAssembly: WeChat-Client ≥ v7.0.17

Vorteil: Erstes Paket unter 4 MB. Nachteil: Engine-Ladezeit beim ersten Start. Bei vielen Assets ist Engine-Separation fast Pflicht.

Subdomain-Konfiguration: Für Rankings, Freundes-Sharing und Open-Data-Funktionen Subdomain-Infos setzen. Die Subdomain ist eine isolierte Laufzeitumgebung für Social-Daten – falsche Konfiguration lässt Rankings ausfallen.

Ein leicht übersehenes Detail

Unten im Build-Panel stehen Build und daneben Generate.

Viele klicken nur Build und denken, fertig. Build erzeugt nur das Ausgabeverzeichnis; Generate führt das vollständige Packaging aus und legt game.js, game.json und weitere Einstiegsdateien an.

Beim ersten Release habe ich nach Build direkt in den WeChat-Developer-Tools importiert – Fehler: Einstiegsdatei nicht gefunden. Ursache: Generate vergessen. In der Doku erwähnt, leicht übersehen.

Build-Ausgabe verstehen und typische Fallen

Nach dem Build liegt unter dem Projektroot der Ordner build.

Darin finden Sie wechatgame – die WeChat-Minispiel-Ausgabe. Dateien und Ordner stammen teils von Cocos, teils von WeChat. Kurz ihre Rollen:

Railway - Moderne Deployment-Plattform, ohne DevOps-Aufwand, in Minuten live

Jetzt starten →Anzeige

Wichtige Konfigurationsdateien

game.js: Engine-Einstieg.

Beim Laden führt die Plattform zuerst diese Datei aus – Cocos-Initialisierung und Szenen-Logik. Normalerweise nicht manuell editieren; bei Build-Problemen auf Syntaxfehler prüfen.

game.json: Globale Konfiguration.

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

Wichtige Felder:

• deviceOrientation: portrait = Hochformat, landscape = Querformat
• networkTimeout: Timeouts in Millisekunden
• enginePlugins: bei Engine-Separation erscheint "cocos"
• optimization: Performance-Optionen; render und fps standardmäßig an

project.config.json: Projektkonfiguration der WeChat-Developer-Tools.

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

Vorsicht bei libVersion.

Fallen-Checkliste: fünf häufige Probleme

Falle 1: Ungültiges libVersion

Symptom: Fehler zur ungültigen Basisbibliothek in den Developer Tools.

Ursache: Cocos setzt libVersion auf eine von WeChat nicht unterstützte Version, z. B. "2.25.0", während das Tool nur "2.20.3" oder "latest" anbietet.

Lösung: In project.config.json auf "widelyUsed" oder "latest" ändern.

{
    "libVersion": "widelyUsed"
}

widelyUsed ist die empfohlene stabile Version; latest bietet mehr Features, manchmal neue Bugs. Zuerst widelyUsed, später optional latest.

Falle 2: self is not defined

Symptom: Build ok, auf dem Realgerät self is not defined.

Ursache: socket.io. In WeChat-Minispielen gibt es kein window.self; neuere socket.io-Versionen greifen darauf zu.

Lösung: socket.io v1.4.4.

npm install [email protected] --save

v1.4.4 ist die letzte stabile Version für diese Umgebung. Bei höheren Versionen Quellcode patchen: self durch window oder global ersetzen.

Falle 3: Zirkuläre Referenz in JSON

Symptom: Build-Fehler wegen zirkulärer Referenz in einer JSON-Datei.

Ursache: Ein globales Objekt wurde falsch serialisiert, z. B. window.global mit Selbstreferenz beim JSON-Export durch Cocos.

Lösung: Initialisierung von window.global prüfen.

// Falsch: Selbstreferenz
window.global = {
    self: window.global  // Zirkuläre Referenz
};

// Richtig: keine Selbstreferenz
window.global = {
    config: {},
    gameState: {}
};

Vor dem Build solche Referenzen entfernen. Bei komplexen Objekten gezielt mit JSON.stringify / JSON.parse serialisieren und Zyklen auslassen.

Falle 4: MiniGameCenter nach Engine-Separation weg

Symptom: Mit Engine-Separation baut es durch, aber MiniGameCenter-Funktionen fehlen in den Developer Tools.

Ursache: MiniGameCenter hängt an Engine-Code; bei Separation fallen Teile aus.

Lösung: Engine-Separation vorübergehend deaktivieren.

Für vollständige MiniGameCenter-Tests (Werbung, IAP) Engine ins Erstpaket packen. Nach den Tests vor dem Live-Gang erneut über Separation nachdenken.

Falle 5: iOS-Build schlägt fehl

Symptom: Fehler beim iOS-Build – fehlende Library oder Assets.

Ursache: iOS-Build ist komplexer. Prüfen:

• Xcode-Version (empfohlen: 12+)
• Pfade der Dependencies (Podfile / Carthage)
• Vollständigkeit der Assets (Bilder, Audio)

Lösung:

1. Xcode-Build-Log für die konkrete Meldung
2. Podfile-Versionen mit lokal installierten Libraries abgleichen
3. Cache leeren: rm -rf build/ios, neu bauen

iOS-Fehler sind vielfältig; oft reicht Cache-Löschen und Neubuild.

Paketgröße: Limits und Strategien

WeChat-Minispiele haben zwei Grenzen:

• Erstes Paket: 4 MB
• Gesamt: 20 MB (Erstpaket + Subpackages)

Option 1: Remote Assets

Die meisten Bilder und Audios auf einen Server; im Erstpaket nur Code und kleine Essentials. Cocos assetManager lädt von Remote-URLs:

assetManager.loadRemote('https://your-server.com/assets/hero.png', (err, texture) => {
    if (err) {
        console.error('Asset-Laden fehlgeschlagen', err);
        return;
    }
    // Geladenes Asset verwenden
});

Nachteil: Erstes Laden dauert länger. Häufig genutzte Assets ins Erstpaket, seltene remote.

Option 2: Subpackages

Das Spiel in Module splitten; Subpackages laden beim Szenenwechsel.

// Subpackages in game.json
{
    "subpackages": [
        {
            "name": "level-1",
            "root": "subpackages/level-1"
        },
        {
            "name": "level-2",
            "root": "subpackages/level-2"
        }
    ]
}

Subpackages erfordern zusätzliche Cocos-Build-Konfiguration – siehe offizielle Doku „Subpackage Build“.

Debugging in den WeChat-Developer-Tools

Build fertig – weiter in den WeChat-Developer-Tools.

Häufiger Fehler: Neues Projekt und falsches Verzeichnis. Richtig: Projekt importieren und build/wechatgame wählen.

Nach dem Import erscheinen wichtige Einstellungen:

Alibaba Cloud - Top-Wahl für Entwickler, exklusiv 15 % Rabatt auf Lighthouse-Server

15 % Rabatt sichern →Anzeige

Basisbibliothek

Oben rechts Details → Tab Lokale Einstellungen.

Dropdown Debug-Basisbibliothek: widelyUsed oder latest – wie in project.config.json. Ungültige Version → Fehler.

Legale Domain nicht prüfen

In der Testphase ist Ihre Asset-Domain oft noch nicht in der WeChat-Plattform registriert. Option aktivieren: Legale Domain, web-view (Business-Domain), TLS-Version und HTTPS-Zertifikat nicht prüfen.

So blockiert das Tool keine Test-Requests. Vor Live-Gang Domains auf die Whitelist setzen – sonst laden Spieler keine Remote-Assets.

Realgeräte-Debug

Toolbar: Realgeräte-Debug.

Ab WeChat-Developer-Tools v1.05+: Realgeräte-Debug v2. Verbesserungen gegenüber v1:

1. Stabileres QR-Preview
2. Remote-Debug nahtlos mit Chrome DevTools
3. Breakpoints und Performance-Monitoring synchron

Ablauf:

1. Realgeräte-Debug → QR-Code
2. WeChat auf dem Handy scannen → Debug-Modus
3. Rechts erscheint ein Panel wie Chrome DevTools

Nützliche Bereiche:

• Console: Logs in Echtzeit
• Sources: Quellcode und Breakpoints
• Network: Requests und Asset-Laden
• Memory: Speicherlecks finden

Realgeräte sind näher an der Produktion als der Simulator – besonders auf günstigen Android-Geräten. Mehrere Geräte testen.

Performance-Monitoring

Über Entwicklungstoolbox (rechts in der Toolbar) öffnet sich das Diagnose-Panel.

Realgeräte-Performance

Nach dem Scan zeigt das Tool FPS, Speicher und CPU live.

Beobachten Sie:

• FPS stabil? (60 ideal, unter 30 spürbar ruckelig)
• Speicher steigt dauerhaft? (Leck-Verdacht)
• CPU über 50 %? (Rechenlast hoch)

First-Screen-Render

Misst Zeit von Start bis vollständig gerenderter erster Szene.

Über 3 Sekunden Wartezeit steigt die Abbruchrate. Optimieren:

• Weniger Assets auf dem First Screen
• Kleinere Bildauflösungen
• Nicht-kritische Assets später laden

Lade-Performance

Liste aller Asset-Ladezeiten – langsame Kandidaten gezielt optimieren.

2-MB-PNG mit 500 ms? WebP (30–50 % kleiner), Kompression, Preload in Cache.

Runtime-Performance

Zeigt Engpässe während des Spiels – z. B. FPS-Einbruch beim Szenenwechsel durch schwere Animation oder lange Skript-Laufzeit.

High-Performance-Modus (iOS)

Auf iOS gibt es den High-Performance-Modus.

Das Spiel läuft in einem eigenen Prozess statt im WeChat-Prozess – mehr CPU- und RAM-Isolation, spürbar bessere Performance.

Offizielle Tests: iPhone 11 Pro Max, Aquarium-Demo – FPS von 13 auf 49. Deutlicher Sprung.

Aktivierung

1. WeChat Public Platform
2. Seite Produktionseffizienz-Paket
3. iOS-High-Performance-Modus freischalten

In game.json:

{
    "iOSHighPerformance": true
}

Speicherlimits

• 2 GB RAM (iPhone 8, iPhone 7): Limit 1 GB
• 3 GB RAM (iPhone 11, iPhone 12): Limit 1,4 GB

Überschreitung → Warnung oder Crash. Bei vielen Assets Speicher-Spitzen im Blick behalten.

Praxis:

• FPS steigt, Speicherbedarf auch etwas
• Low-End (iPhone 8): unter ~800 MB bleiben
• High-End (iPhone 12): bis ~1,2 GB möglich

Nach Aktivierung Realgeräte-Monitoring für FPS und Speicher.

WeChat-Minispiel-Politik 2026

Nach dem Release folgen Betrieb und Monetarisierung.

2026 gibt es neue WeChat-Minispiel-Anreize – für Entwickler positiv. Die Kernpunkte in Kürze.

IAP (In-App-Käufe)

Bei IAP-Monetarisierung gibt es Launch-Bonus.

Anreizquote: 100 %+

Zusammensetzung:

• Basis: 70 % für Entwickler, 30 % Plattform
• Launch-Anreiz: zusätzlich 40 %

Im Launch-Zeitraum effektiv 110 % – 10 % über dem Umsatz.

Zeitfenster: erste 10 Mio. ¥ Umsatz im Launch neuer Spiele. Darüber: zurück auf 70 %.

Anreiz-Cap: 4 Mio. ¥ (H1 2026)

KiloClaw - Managed OpenClaw für Unternehmen: AI-Agent-Orchestrierung und smartes Modell-Routing

Jetzt starten →Anzeige

Pro Spiel maximal 4 Mio. ¥ Launch-Anreiz. Bei 10 Mio. ¥ Umsatz: 10 Mio. × 40 % = 4 Mio. ¥ – genau am Cap.

Launch-Wachstumsanreiz: alle 2 Mio. ¥ Umsatz +5 % Cash

Zusätzlich zum Launch-Anreiz. Beispiel 6 Mio. ¥ Umsatz im Launch:

• Basis: 6 Mio. × 70 % = 4,2 Mio. ¥
• Launch: 6 Mio. × 40 % = 2,4 Mio. ¥ (unter Cap)
• Wachstum: 6 Mio. ÷ 2 Mio. = 3 × 5 % = 15 % → 0,9 Mio. ¥

Summe: 7,5 Mio. ¥

Ohne Anreize: 4,2 Mio. ¥ bei 6 Mio. ¥ Umsatz – mit Politik 3,3 Mio. ¥ mehr.

IAA (Werbung)

Bei reiner Werbe-Monetarisierung (IAA) ebenfalls Anreize.

Leichte IAA-Spiele: 40 % Anreiz auf 30-Tage-Umsatz

Casual, Puzzle, Match-3 – große Nutzerbasis, geringe Zahlungsbereitschaft, Werbung passt gut.

Mid-/Hardcore-IAA: 35 % auf 90-Tage-Umsatz

Action, RPG, Strategie – kleinere Basis, längere Sessions, mehr Ad-Impressions.

Einnahmen maximieren

Launch-Timing

Launch-Anreiz gilt für die ersten 10 Mio. ¥. Bei hohem Potenzial Launch in aktive Phasen legen (Ferien, Feiertage) – mehr Umsatz innerhalb des Anreizfensters.

Beispiel:

• Normaler Launch: 5 Mio. ¥ Umsatz, 2 Mio. ¥ Anreiz
• Winterferien-Launch: 10 Mio. ¥, 4 Mio. ¥ Anreiz (Cap)

Umsatz-Tempo

Anreize sind umsatzabhängig. Zu schnelles Wachstum beendet das Fenster früh. Phasen:

1. Launch: kleine Promotion, Feedback
2. Im Anreizfenster: größere Promotion, Umsatz pushen
3. Danach: stabiler Betrieb, Kosten kontrollieren

Monetarisierungsmodell

IAP oder IAA?

• Einfaches Gameplay, viele Nutzer: IAA, 40 % leichter IAA-Anreiz
• Komplex, zahlungswillig: IAP, 110 % Launch

Hybrid (IAP + Werbung) ist möglich – Anreize werden getrennt berechnet.

Prüf-Checkliste vor dem Release

• Software-Copyright (软著): Nachweis des Code-Eigentums
• ICP-Filing: Domain-Registrierung bei Remote-Asset-Server
• Publishing-Lizenz (版号): für offiziellen Live-Betrieb nötig; Minispiele oft zuerst „Testbetrieb“, Lizenz später
• Datenschutzrichtlinie: beim Start anzeigen, Zustimmung vor Spielstart
• Jugendschutz: Real-Name, Spielzeitlimits, Kauf-Limits

Typische Dauer:

• Software-Copyright: 1–2 Monate
• ICP: 1–2 Wochen
• Publishing-Lizenz: 3–6 Monate
• Jugendschutz-Integration: 1–2 Wochen Entwicklung + WeChat-API

Früh planen – Publishing-Lizenz am längsten.

Die Policy-Infos stammen aus offiziellen WeChat-Community-Dokumenten H1 2026. Bedingungen können sich ändern – vor Release in der WeChat Public Platform die aktuelle Fassung prüfen.

Abschluss

Cocos Creator → WeChat-Minispiel ist kein Kurzweg, aber Schritt für Schritt nachvollziehbar.

Build-Panel: AppID Pflicht, MD5-URLs, Voraussetzungen Engine-Separation, Unterschied Build vs. Generate.

Ausgabe: game.js, game.json, project.config.json. Die fünf Fallen – libVersion, self, Zyklen, MiniGameCenter, iOS – haben jeweils Fixes.

Developer Tools: Import, Basisbibliothek, Realgeräte-Debug, Monitoring. iOS-High-Performance boostet FPS, Speicherlimits beachten.

Politik 2026: IAP 110 %, Cap 4 Mio. ¥, IAA 35–40 %. Launch-Zeit, Umsatz-Tempo und Modell gut planen – Einnahmen können sich verdoppeln.

Vor dem Release in dieser Reihenfolge:

1. Build-Konfiguration gegen diesen Leitfaden prüfen
2. Nach Build die Fallen-Checkliste durchgehen
3. Mehrere Realgeräte-Runden, FPS und Speicher messen
4. Qualifikationen vorbereiten, Launch für Anreize timen

WeChat-Minispiele entwickeln sich schnell. Dieser Text basiert auf Doku und Praxis H1 2026 – Updates können nötig sein. Der Kern aus Build und Debug bleibt aber stabil.

Fragen gerne in den Kommentaren.