Guide complet Cocos Creator : build et débogage de mini-jeux WeChat, du panneau Build aux outils développeur

Vous avez passé des semaines à finaliser votre jeu dans Cocos Creator.

Le code est prêt, les assets importés, les animations tournent. Vous ouvrez le panneau Build pour publier sur la plateforme mini-jeux WeChat — et c’est là que les vrais problèmes commencent.

Erreur sur le champ libVersion. Écran noir sur appareil réel. Dépassement de la taille du package. Échec du build iOS. Aucun de ces problèmes n’apparaît dans les tutoriels de développement de jeux, mais chacun peut bloquer votre projet à l’étape de publication.

Cet article traite précisément de ces difficultés. Du remplissage de chaque paramètre du panneau Build à la fonction de chaque fichier dans le répertoire de sortie, en passant par les étapes concrètes de débogage sur appareil réel dans les outils développeur WeChat — le flux entier est décortiqué. Nous interpréterons aussi les incitations WeChat mini-jeux 2026 : une fois la publication réussie, maximiser les revenus demande une planification anticipée.

Si vous préparez la publication de votre projet Cocos sur la plateforme mini-jeux WeChat, ou si vous avez déjà rencontré ces pièges et cherchez des solutions, ce guide devrait vous aider.

Configuration pratique du panneau Build

Commencez par ouvrir le panneau Build.

Dans Cocos Creator, deux accès : menu « Projet → Build and Publish », ou raccourci Ctrl+Shift+B (Mac : Cmd+Shift+B). Une fois ouvert, vous verrez de nombreux paramètres — chemin de publication, scène initiale, MD5 Cache, AppID… La première fois, c’est déroutant.

Pas de panique, passons-les en revue un par un.

Paramètres généraux : configuration de base

Chemin de publication : emplacement du répertoire de sortie du build. Par défaut, un dossier build est créé à la racine du projet. Vous pouvez le modifier, mais je recommande de garder la valeur par défaut — la structure de sortie reste prévisible et facile à retrouver pour le débogage.

Scène initiale : première scène chargée au démarrage. Choisissez généralement Boot ou Loading. Si votre projet a plusieurs entrées, sélectionnez l’entrée principale.

Scènes incluses dans le build : liste de toutes les scènes du projet. Cochez celles à empaqueter ; les non cochées n’entrent pas dans le package final. Piège fréquent : tout cocher et voir le package exploser. Ne cochez que les scènes nécessaires ; les autres peuvent être hébergées sur un serveur de ressources distant.

MD5 Cache : faut-il l’activer ?

Activé, tous les noms de fichiers de ressources reçoivent un suffixe MD5. Avantage : lors des mises à jour, le client détecte automatiquement les changements et évite de charger d’anciens caches. Inconvénient : l’accès aux ressources dans le code doit être adapté.

Par exemple, resources.load('texture/hero') devient une URL du type texture/hero-abc123.png. Utilisez cette méthode pour obtenir l’URL correcte :

// Obtenir le chemin de ressource avec suffixe MD5
const url = assetManager.utils.getUrlWithUuid('texture/hero', {
    isScene: false,
    type: 'png'
});

Cette API est standard dans Cocos Creator 3.x. En 2.x, la logique diffère légèrement, mais le principe reste le même : ne codez pas en dur les chemins de ressources, laissez le moteur s’en charger.

Paramètres spécifiques mini-jeux WeChat : configuration plateforme

AppID : obligatoire.

Sans AppID, le bouton de build renvoie une erreur. Vous pouvez utiliser un AppID de test, mais avec des limitations : pas de domaine de données ouvertes, pas de publication en ligne, fonctionnalités publicitaires restreintes.

Pour obtenir un AppID : connectez-vous à la plateforme publique WeChat → Gestion des mini-programmes → Ajouter un mini-jeu → Récupérer l’AppID. Comptez 1 à 3 jours de validation ; anticipez.

Mode debug : le build inclut du code et des ressources de débogage supplémentaires. Désactivez-le pour la publication officielle ; en développement, il fait gagner du temps.

Séparation du moteur : réduit significativement la taille du package.

Cochée, le code moteur Cocos n’est pas empaqueté dans le jeu mais chargé depuis les serveurs WeChat. Conditions préalables :

• Debug Base Library ≥ 2.9.0 (dans les outils développeur WeChat)
• WebAssembly requiert WeChat client ≥ v7.0.17

Avantages : le premier package reste sous 4 Mo. Inconvénient : le chargement du moteur prend du temps ; le joueur attend brièvement à la première entrée. Si votre projet contient beaucoup de ressources, la séparation du moteur est quasi indispensable.

Configuration du sous-domaine : pour classements, partage entre amis et autres fonctions du domaine de données ouvertes, configurez ici les informations du sous-domaine. C’est un environnement d’exécution isolé du jeu principal, dédié aux données sociales. Une mauvaise configuration fait échouer le classement.

Un détail souvent oublié

En bas du panneau Build, un bouton « Build » et à côté un bouton « Generate ».

Beaucoup pensent avoir terminé après « Build ». En réalité, « Build » ne génère que le répertoire de sortie ; « Generate » exécute l’empaquetage complet et crée game.js, game.json et les fichiers d’entrée requis.

Lors de ma première publication, j’ai cliqué « Build » puis importé directement dans les outils développeur WeChat — erreur : fichier d’entrée introuvable. J’avais oublié « Generate ». Ce détail est dans la doc officielle, mais facile à manquer.

Analyse de la sortie du build et pièges courants

Une fois le build terminé, regardez le dossier build à la racine du projet.

Vous y trouverez un répertoire wechatgame — la sortie pour la plateforme mini-jeux WeChat. Ouvrez-le : fichiers et dossiers générés par Cocos et configurations spécifiques WeChat. Voyons leur rôle.

Fichiers de configuration clés

game.js : point d’entrée du moteur.

La plateforme mini-jeux WeChat exécute ce fichier en premier. Il contient l’initialisation du moteur Cocos et la logique de chargement des scènes. Pas besoin de le modifier manuellement, mais en cas de problème de build, vérifiez l’absence d’erreurs de syntaxe.

🔥 Ne perdez plus des mois sur des produits sans demande ! Validez vos promesses SaaS avec Adsterra à petit budget →

Tester l'MVP →Pub

game.json : configuration globale.

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

Champs importants :

• deviceOrientation : orientation de l’écran — portrait (vertical), landscape (horizontal)
• networkTimeout : délai d’expiration des requêtes réseau, en millisecondes
• enginePlugins : plugins moteur ; avec séparation du moteur, affiche "cocos"
• optimization : options d’optimisation des performances — render et fps activés par défaut

project.config.json : configuration du projet pour les outils développeur WeChat.

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

Attention au piège : le champ libVersion.

Pièges courants : cinq problèmes fréquents

Piège 1 : libVersion invalide

Symptôme : les outils développeur WeChat signalent une version de bibliothèque de base invalide.

Cause : le libVersion généré automatiquement par Cocos peut ne pas correspondre aux versions supportées par WeChat. Par exemple "2.25.0" dans la sortie, alors que l’outil ne propose que "2.20.3" ou "latest".

Solution : modifiez manuellement project.config.json et remplacez libVersion par "widelyUsed" ou "latest".

{
    "libVersion": "widelyUsed"
}

widelyUsed est la version stable recommandée par WeChat, meilleure compatibilité. latest offre plus de fonctionnalités mais peut introduire de nouveaux problèmes. Commencez par widelyUsed, puis testez latest une fois stable.

Piège 2 : self is not defined

Symptôme : build réussi, mais erreur self is not defined sur appareil réel.

Cause : le projet utilise la bibliothèque socket.io. L’environnement mini-jeux WeChat n’a pas l’objet global window.self ; certaines versions de socket.io y accèdent.

Solution : utilisez socket.io v1.4.4.

npm install [email protected] --save

v1.4.4 est la dernière version stable compatible avec l’environnement mini-jeux WeChat. Les versions supérieures ont introduit une dépendance à self. Si vous devez absolument utiliser une version récente, patchez le code source en remplaçant self par window ou global.

Piège 3 : erreur JSON de référence circulaire

Symptôme : erreur au build indiquant une référence circulaire dans un fichier JSON.

Cause : un objet global a été sérialisé incorrectement. Par exemple, window.global contient un objet complexe ; Cocos tente de le convertir en JSON et détecte une référence circulaire.

Solution : vérifiez la logique d’initialisation de window.global.

// Incorrect : l'objet global se référence lui-même
window.global = {
    self: window.global  // référence circulaire
};

// Correct : éviter l'auto-référence
window.global = {
    config: {},
    gameState: {}
};

Nettoyez ces références circulaires avant le build. Pour des objets complexes, utilisez JSON.stringify et JSON.parse en excluant les parties circulaires.

Piège 4 : MiniGameCenter disparaît après séparation du moteur

Symptôme : séparation du moteur activée, build réussi, mais MiniGameCenter introuvable dans les outils développeur WeChat.

Cause : MiniGameCenter est un composant de service WeChat mini-jeux dépendant du code moteur. Après séparation, certaines fonctions deviennent indisponibles.

Solution : désactivez temporairement la séparation du moteur.

Si vous avez besoin de toutes les fonctions MiniGameCenter (tests publicitaires, achats intégrés), intégrez le moteur dans le premier package. Une fois les tests terminés, réévaluez la séparation avant la mise en ligne.

Piège 5 : échec du build iOS

Symptôme : erreur lors du build iOS, bibliothèque ou ressource introuvable.

Cause : le flux iOS est plus complexe que mini-jeux WeChat. Vérifiez :

• Version Xcode compatible (Xcode 12+ recommandé)
• Chemins des bibliothèques (Podfile ou Carthage)
• Fichiers de ressources complets (images, audio)

Solution :

1. Ouvrez Xcode, consultez les logs de build pour l’erreur précise
2. Vérifiez que les versions dans le Podfile correspondent aux installations locales
3. Nettoyez le cache : rm -rf build/ios, puis rebuild

Les problèmes iOS sont variés ; analysez l’erreur concrète. Dans la plupart des cas, un nettoyage du cache et un rebuild suffisent.

Limites de taille du package : comment contrôler

Deux limites pour les mini-jeux WeChat :

• Premier package : 4 Mo
• Package total : 20 Mo (premier package + sous-packages)

Que faire en cas de dépassement ?

Option 1 : ressources distantes

Placez la plupart des images et audio sur un serveur distant ; le premier package ne contient que le code et les petites ressources essentielles. assetManager de Cocos charge depuis une URL distante :

assetManager.loadRemote('https://your-server.com/assets/hero.png', (err, texture) => {
    if (err) {
        console.error('Échec du chargement de la ressource', err);
        return;
    }
    // Utiliser la ressource chargée
});

Inconvénient : le premier chargement prend du temps et retarde l’expérience. Gardez les ressources les plus utilisées dans le premier package, les autres à distance.

Option 2 : chargement par sous-packages

WeChat mini-jeux supporte les sous-packages. Découpez le jeu en modules ; chaque module = un sous-package, chargé à l’entrée de la scène correspondante.

// Configuration des sous-packages dans game.json
{
    "subpackages": [
        {
            "name": "level-1",
            "root": "subpackages/level-1"
        },
        {
            "name": "level-2",
            "root": "subpackages/level-2"
        }
    ]
}

Le chargement par sous-packages demande une configuration supplémentaire du flux de build Cocos. Consultez le chapitre « Build par sous-packages » de la documentation officielle Cocos.

Débogage pratique avec les outils développeur WeChat

Build terminé, passons aux outils développeur WeChat.

Erreur fréquente ici : cliquer « Nouveau projet » et sélectionner un mauvais répertoire. La bonne méthode : « Importer le projet », puis choisir le répertoire build/wechatgame généré par Cocos.

Après import, vous verrez l’interface de configuration. Réglages clés :

Version de la bibliothèque de base

En haut à droite, bouton « Détails » → onglet « Paramètres locaux ».

Menu déroulant « Bibliothèque de base de débogage ». Choisissez widelyUsed ou latest — comme pour project.config.json. Une version inexistante provoque une erreur.

Ne pas vérifier les domaines autorisés

En phase de test, le domaine de votre serveur de ressources peut ne pas être enregistré sur la plateforme publique WeChat. Cochez « Ne pas vérifier les domaines autorisés, web-view (domaines métier), version TLS et certificats HTTPS ».

L’outil n’interceptera plus les requêtes vers des domaines non enregistrés. Avant la mise en ligne, ajoutez le domaine à la liste blanche, sinon les joueurs ne pourront pas charger les ressources distantes.

Vultr - Serveur cloud NVMe haute performance, 32 emplacements mondiaux, déploiement Docker en un clic

Voir les tarifs →Pub

Flux de débogage sur appareil réel

Cliquez sur « Débogage sur appareil réel » dans la barre d’outils.

Les outils développeur WeChat v1.05+ proposent le débogage sur appareil réel v2. Par rapport à l’ancienne version :

1. Aperçu par scan QR plus stable
2. Débogage distant intégré à Chrome DevTools
3. Points d’arrêt et monitoring des performances synchronisés

Étapes :

1. Cliquez « Débogage sur appareil réel », un QR code s’affiche
2. Scannez avec WeChat sur mobile pour entrer en mode débogage
3. Le panneau de débogage apparaît à droite, comme Chrome DevTools

Fonctions utiles du panneau :

• Console : logs en temps réel, contenu de console.log
• Sources : code source avec points d’arrêt
• Network : requêtes réseau, vérification du chargement des ressources
• Memory : analyse mémoire, détection de fuites

Le débogage sur appareil réel est plus fidèle que l’émulateur. L’écart de performance est important, surtout sur Android bas de gamme. Testez plusieurs fois sur différents appareils.

Outils de monitoring des performances

Les outils développeur WeChat incluent un ensemble complet de monitoring.

Cliquez « Boîte à outils R&D » (barre d’outils à droite) pour ouvrir le panneau de diagnostic. Fonctions principales :

Monitoring des performances sur appareil réel

Après scan QR, le jeu tourne sur le téléphone ; l’outil affiche FPS, mémoire et CPU en temps réel.

Données en graphiques :

• FPS stable (60 FPS idéal ; sous 30 FPS = saccades visibles)
• Mémoire en croissance continue (fuite mémoire probable)
• CPU élevé (au-delà de 50 % = charge de calcul importante)

Analyse du rendu du premier écran

Option « Rendu du premier écran » : enregistre le temps du démarrage à l’affichage complet.

Critique : au-delà de 3 secondes d’attente, le taux d’abandon augmente nettement. Si votre temps dépasse 3 secondes, optimisez :

• Réduisez le nombre de ressources du premier écran
• Utilisez des images plus petites
• Chargez les ressources non essentielles après le premier écran

Analyse des performances de chargement

Liste le temps de chargement de chaque ressource. Identifiez les plus lentes pour optimiser.

Par exemple, un PNG de 2 Mo chargé en 500 ms :

• Convertir en WebP (volume réduit de 30 à 50 %)
• Compresser la résolution
• Précharger en cache

Analyse des performances à l’exécution

Enregistre les goulots d’étranglement pendant l’exécution.

Par exemple, chute de FPS lors d’un changement de scène — l’outil indique la cause : animation trop coûteuse, script trop long, etc.

Mode haute performance : optimisation iOS

Sur iOS, WeChat mini-jeux propose un « mode haute performance ».

Activé, le jeu s’exécute dans un processus indépendant du client WeChat. CPU et mémoire sont plus isolés ; le gain de performance est net.

Données officielles : sur iPhone 11 Pro Max, le FPS de la démo Aquarium passe de 13 à 49. Amélioration considérable.

Comment l’activer

1. Connectez-vous à la plateforme publique WeChat
2. Page de gestion « Pack productivité production »
3. Activez le service mode haute performance iOS

Après activation, ajoutez dans game.json :

{
    "iOSHighPerformance": true
}

Limites mémoire à respecter

Le mode haute performance impose des limites supplémentaires :

• Appareils 2 Go RAM (iPhone 8, iPhone 7) : limite 1 Go
• Appareils 3 Go RAM (iPhone 11, iPhone 12) : limite 1,4 Go

Dépassement = avertissement mémoire, voire crash. Si votre jeu contient beaucoup de ressources, surveillez le pic mémoire.

Recommandations de test :

• FPS nettement amélioré, mais consommation mémoire accrue
• Sur appareils bas de gamme (iPhone 8), gardez les ressources sous 800 Mo
• Sur appareils haut de gamme (iPhone 12), jusqu’à 1,2 Go acceptable

Après activation, lancez un monitoring sur appareil réel pour confirmer FPS et mémoire dans des limites sûres.

Interprétation des politiques WeChat mini-jeux 2026

Jeu publié, place à l’exploitation et aux revenus.

WeChat mini-jeux a lancé de nouvelles incitations en 2026, une bonne nouvelle pour les développeurs. Voici les clauses essentielles.

Nouvelles incitations IAP (achats intégrés)

Pour les jeux en monétisation IAP, des incitations supplémentaires au lancement.

Taux d’incitation : 100 %+

Composition :

• Partage de base : 70 % (développeur 70 %, plateforme WeChat 30 %)
• Incitation lancement : 40 % supplémentaires

Total au lancement : 70 % + 40 % = 110 %. Oui, 10 % de plus que le chiffre d’affaires.

Fenêtre temporelle : période de lancement d’un nouveau jeu, les 10 premiers millions de revenus bénéficient de 110 %. Au-delà, retour au taux de base de 70 %.

Plafond d’incitation : 4 millions ¥ (premier semestre 2026)

Par jeu au lancement, maximum 4 M ¥ d’incitations. Si le chiffre d’affaires dépasse 10 M ¥ : 10 M × 40 % = 4 M ¥ — exactement le plafond.

Incitation croissance au lancement : +5 % en cash tous les 2 M ¥ de revenus

S’ajoute à l’incitation de lancement. Exemple : 6 M ¥ de revenus au lancement :

Railway - Plateforme de déploiement moderne, sans opérations complexes, en ligne en quelques minutes

Commencer →Pub

• Partage de base : 6 M × 70 % = 4,2 M ¥
• Incitation lancement : 6 M × 40 % = 2,4 M ¥ (sous le plafond de 4 M)
• Incitation croissance : 6 M ÷ 2 M = 3 fois × 5 % = 6 M × 15 % = 0,9 M ¥

Total : 4,2 + 2,4 + 0,9 = 7,5 M ¥

Comparaison : sans incitations, 6 M ¥ de revenus = 4,2 M ¥. Avec la politique : 3,3 M ¥ de plus.

Nouvelles incitations IAA (publicité)

Pour la monétisation publicitaire (IAA), des incitations existent aussi.

Jeux IAA légers : 40 % d’incitation sur 30 jours de revenus

Jeux casual, puzzle, match-3 — gameplay simple, grande base d’utilisateurs, faible volonté de payer individuelle. Idéal pour la publicité.

Calcul : dans les 30 jours suivant la mise en ligne, revenus publicitaires × 40 % en incitation.

Jeux IAA mid-core et hardcore : 35 % sur 90 jours de revenus

Action, RPG, stratégie — gameplay complexe, base plus restreinte mais sessions plus longues, plus d’impressions publicitaires.

Calcul : dans les 90 jours suivant la mise en ligne, revenus publicitaires × 35 %.

Stratégies de maximisation des revenus

Politique comprise, comment maximiser ?

Planification du lancement

L’incitation de lancement couvre les 10 premiers millions de revenus. Si le potentiel est élevé, lancez pendant une période d’activité forte (vacances scolaires, fêtes) pour maximiser les revenus dans la fenêtre d’incitation.

Exemple :

• Lancement en période normale : 5 M ¥ de revenus, 2 M ¥ d’incitations
• Lancement en vacances d’hiver : 10 M ¥ de revenus, 4 M ¥ d’incitations (plafond)

Le double.

Contrôle du rythme des revenus

Les incitations sont proportionnelles aux revenus. Si la croissance est trop rapide, la période d’incitation se termine vite. Envisagez une promotion par phases :

1. Lancement : promotion limitée, test des retours utilisateurs
2. Pendant l’incitation : promotion large, montée rapide des revenus
3. Après l’incitation : exploitation stable, maîtrise des coûts

Maximise les revenus pendant l’incitation tout en évitant des coûts de promotion excessifs.

Choix du modèle de monétisation

IAP ou publicité ?

• Gameplay simple, grande audience : publicité — incitation IAA légère 40 %
• Gameplay complexe, forte volonté de payer : IAP — incitation lancement 110 %

Certains jeux combinent les deux : IAP principal, publicité complémentaire. WeChat calcule les incitations séparément pour chaque mode.

Liste des qualifications pour la revue

Avant publication, préparez :

• Droit d’auteur logiciel : certificat prouvant la propriété du code
• Enregistrement ICP : si le jeu utilise un serveur de ressources distant
• Numéro d’édition : obligatoire pour la mise en ligne officielle (les mini-jeux peuvent d’abord utiliser le statut « essai », numéro d’édition à compléter ensuite)
• Politique de confidentialité : affichée au démarrage, consentement requis avant d’entrer
• Protection des mineurs : authentification réelle, limite de durée de jeu, plafond de recharge

Délais d’obtention :

• Droit d’auteur : 1 à 2 mois
• ICP : 1 à 2 semaines
• Numéro d’édition : 3 à 6 mois (le plus long)
• Fonction anti-addiction : 1 à 2 semaines de développement, interface officielle WeChat

Anticipez. Le numéro d’édition prend le plus de temps — commencez pendant le développement.

Les informations proviennent de la documentation d’incitations 2026 de la communauté officielle WeChat. Les clauses peuvent évoluer ; vérifiez la dernière version sur la plateforme publique WeChat avant publication.

Pour conclure

Publier un mini-jeu WeChat depuis Cocos Creator : le flux est long, mais chaque étape est traçable.

Panneau Build : AppID obligatoire, conversion d’URL avec MD5 Cache activé, conditions de séparation du moteur, différence entre Build et Generate.

Répertoire de sortie : game.js, game.json, project.config.json — chacun a son rôle. Les cinq pièges — libVersion invalide, self non défini, références circulaires, MiniGameCenter disparu, échec build iOS — ont chacun leur solution.

Débogage WeChat : import du projet, version bibliothèque de base, débogage sur appareil réel, monitoring des performances. Le mode haute performance iOS améliore nettement les FPS ; surveillez les limites mémoire.

Incitations 2026 : IAP lancement 110 %, plafond 4 M ¥, IAA 35 à 40 %. Timing du lancement, rythme des revenus, mode de monétisation — bien planifiés, les revenus peuvent doubler.

Si vous préparez une publication, suivez cet ordre :

1. Vérifiez la configuration Build, paramètre par paramètre
2. Après le build, parcourez la liste des pièges
3. Déboguez sur appareil réel, surveillez FPS et mémoire
4. Préparez les qualifications avant publication, planifiez le lancement pour maximiser les incitations

La plateforme mini-jeux WeChat évolue vite en politique et en détails techniques. Cet article s’appuie sur la documentation officielle et l’expérience terrain du premier semestre 2026 ; des mises à jour pourront nécessiter une re-vérification. Mais le flux de build et les méthodes de débogage restent largement stables.

Des questions ? Échangeons en commentaires.