> For the complete documentation index, see [llms.txt](https://weekly-essay.mikey.wang/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://weekly-essay.mikey.wang/fr/2026/w03-lessons-from-advanced-troubleshooting.md).

# W03-Leçons tirées de diagnostics techniques difficiles

La semaine dernière, nous avons beaucoup progressé sur un problème fantôme de Webpack qui nous tourmentait depuis près de trois ans. C'est l'occasion de résumer les particularités des problèmes frontend les plus étranges et les plus difficiles, ainsi que ce que j'ai appris en les traitant.

***

#### Deux catégories de problèmes difficiles, selon que le code est en cause ou non

* La première vient de défauts de conception très discrets dans le code. Ces défauts logiques latents ne se manifestent que dans des conditions particulières. De mauvaises hypothèses sur l'asynchronisme, la concurrence ou l'état peuvent n'apparaître que sur des appareils peu performants ou dans un ordre d'exécution précis. Les cas que je rencontre le plus souvent sont des conditions de course ; j'en donnerai des exemples plus loin.
* Dans la seconde, la cause profonde ne réside généralement pas dans le code lui-même. Il faut chercher la vérité dans un système plein d'incertitudes. C'est précisément ce qui rend le diagnostic frontend exigeant : il faut savoir écrire du code correct, mais aussi comprendre le monde dans lequel il s'exécutera. Appelons ce monde un environnement d'exécution incertain. Son degré d'incertitude rend souvent l'observation et la reproduction difficiles.

***

#### L'environnement d'exécution incertain

On peut y voir une hypothèse technique : tout ce qui entoure le code est peu fiable. Le but est de préparer les défenses nécessaires.

L'incertitude commence dès la compilation du code.

> Build (choix humains) → Container (fortement personnalisé) → OS & Hardware (très fragmentés) → User & Physical Context (incontrôlables).

**1. Build : différences d'infrastructure et d'artefacts de compilation**

Des versions différentes de polyfills, de bibliothèques d'exécution ou de configurations de compilation peuvent provoquer des erreurs de syntaxe dans les anciens environnements, ou des anomalies dues à des injections doubles ou incorrectes.

> Récemment, après le passage de Webpack à Rspack pour Yuefu, nous avons constaté un ordre d'exécution anormal de Promise/thenable sur des appareils d'entrée de gamme. L'outil de compilation lui-même n'avait pas nécessairement de bug : une différence de comportement du runtime produit pouvait suffire à déclencher le problème. Webpack possède en effet un runtime complexe qui coordonne le chargement des modules avec Promise/thenable.
>
> Le module de paiement marchand a également rencontré un échec de set cookie dans l'application Kuailü, dû à l'ordre d'exécution entre plusieurs threads du client.

**2. Container : différences entre applications hôtes et moteurs WebView**

Les WebView ne se comportent pas exactement de la même manière pour l'exécution JS, le rendu CSS, la sécurité et les interfaces. L'enveloppe peut aussi injecter ou restreindre des API, si bien qu'une même page H5 fonctionne différemment selon le conteneur.

> Les intercepteurs iOS sont un cas typique. Le conteneur intercepte les requêtes réseau et les changements de route ; une implémentation incorrecte ou redondante peut causer des problèmes. Sur Huixiao, par exemple, un échec de set cookie a invalidé le token. Nous avons aussi rencontré des difficultés liées au mode hors ligne dans l'application marchande de livraison.
>
> Dans cette dernière, nous avons découvert un hook injecté qui chargeait automatiquement la version 1.9.1 si knb.js était absent. Sur Android, l'abonnement à appear réussissait parfois sans que le callback s'exécute.

**3. OS & Hardware : fragmentation des systèmes et des appareils**

Les différences de ROM constructeur, de modèle, de résolution ou de version du système peuvent provoquer des plantages, des défauts de mise en page ou des problèmes de performance propres à certains appareils.

> Dans l'application iOS destinée aux marchands de livraison, un seul utilisateur pouvait déclencher un grand nombre d'appels répétés à yoda. L'année suivante, en résolvant un autre problème, nous avons compris que les deux avaient une cause commune : le manque de mémoire disponible sur les appareils d'entrée de gamme. Après une alerte mémoire, le mécanisme de maintien en vie amenait le WebView à appeler reload plusieurs fois de suite ; le même utilisateur semblait alors ouvrir fréquemment la page en peu de temps.

**4. User & Physical Context : différences entre les environnements réels des utilisateurs**

Les usages et les conditions varient énormément : réseau faible, batterie presque vide, stockage insuffisant. Ces variables incontrôlables produisent des anomalies dans des cas limites. Difficiles à reproduire, elles compliquent fortement le diagnostic. Il faut croiser les journaux de télémétrie et les traces d'actions des utilisateurs pour trouver des indices.

> Dans le paiement par un tiers, nous avons rencontré des échecs dus au clonage de WeChat. Certains utilisateurs se servent d'une fonction du système ou d'un outil tiers pour exécuter deux instances de la même application sur un téléphone. Ce mécanisme peut rompre l'hypothèse d'une instance unique ou la chaîne IPC et provoquer des problèmes inattendus.

***

#### Quelques leçons tirées de mes erreurs, puis deux cas concrets

Premièrement, se défaire de l'attachement à sa propre explication. Tous les problèmes difficiles n'ont pas besoin d'une explication parfaite immédiate. Si un incident est déjà survenu, la priorité est de réduire la pression autour de soi. Un contournement maîtrisé permet d'abord de contenir le risque et de déplacer rapidement l'attention. La plupart des gens ne se préoccupent pas de la cause ultime. Stabiliser la situation donne le temps de chercher ensuite la vérité.

Deuxièmement, la persévérance et le courage face aux difficultés permettent d'acquérir de la profondeur technique. Beaucoup de problèmes se résolvent soudain après une longue attente. Quand on atteint une impasse, on peut laisser le problème de côté, attendre une occasion ou une idée et compléter ce qui manque. Mais il ne faut pas abandonner.

***

#### Cas 1 : des artefacts Webpack instables

Le problème d'instabilité des artefacts Webpack évoqué au début a demandé près de trois ans d'approfondissement progressif pour approcher la vérité.

1. Symptôme. Certains artefacts Webpack étaient inutilisables et provoquaient occasionnellement des écrans blancs en production. Au début, nous n'avons pas trouvé la cause, mais nous avons amélioré le mécanisme de livraison de paquets du pipeline. Nous avons ainsi garanti que le paquet validé en production auprès de la liste autorisée était celui déployé à tous.
2. Analyse de la configuration. Hongze a ensuite mené une analyse dédiée de la configuration Webpack. Il a identifié des anomalies liées au mélange d'ESM et de CJS dans des dépendances tierces. Les ajustements de configuration n'ont toutefois pas éliminé tous les artefacts défectueux.
3. Expérience collective et compromis. L'an dernier, lors d'une séance de transmission des fondamentaux, Jianzuan a présenté ces anomalies de compilation. Il a reproduit l'instabilité en direct avec l'équipe. Cette expérience collective a approfondi notre compréhension du build. Elle a aussi révélé un paramètre plus efficace : désactiver la compilation asynchrone faisait disparaître les artefacts anormaux, au prix de la vitesse.
4. Solution finale. La semaine dernière, Jianzuan a proposé une nouvelle solution. Il a identifié une signature importante dans les artefacts, l'enveloppe n.n(). Vérifier que les caractéristiques de minification CJS correspondent aux attentes permet de garantir la validité des paquets de production et de fermer complètement cette faille de qualité.

Je considère désormais ce problème comme clos. S'il reste du temps, nous pourrons aider Webpack à résoudre à la source son problème de compilation asynchrone des modules CJS et proposer une PR.

***

#### Cas 2 : la refonte marketing du projet Alpha

Un problème peut être résolu sans recevoir d'explication technique complète. La manière de le traiter compte davantage.

Une refonte marketing du projet Alpha a fait baisser le taux de conversion des ouvertures de compte. Il a fallu plus de deux mois pour résoudre la situation, qui a révélé une série de problèmes. Nous n'avons jamais trouvé la cause technique et ne disposons plus des conditions nécessaires pour reproduire le cas. Une explication technique complète restera donc impossible.

Mais ce travail nous a donné une compréhension profonde de la qualité. Pendant cette période, nous avons complété l'observation en temps réel des indicateurs métier, les capacités d'expérimentation A/B et le suivi régulier de la qualité hors production. Nous avons aussi réexaminé en profondeur nos stratégies et nos décisions de retour arrière. Cet incident a directement conduit à la refonte globale du projet Alpha l'année suivante, qui a fourni à l'équipe une bonne référence en matière de maintenabilité.