Dépannage

Le symptôme d'abord. Chaque entrée renvoie à la section qui donne l'explication complète.

$debug n'est pas défini

Erreur de référence à l'exécution

L'erreur ReferenceError: $debug is not defined vient de ce que l'environnement d'exécution n'existe qu'en développement. Sous un lanceur de tests, ou dans tout build où le plugin est inactif, rien n'installe la globale.

• En test : le plugin enregistre automatiquement un bouchon inerte sous Vitest. Avec Jest, une config Vitest que le plugin n'atteint pas, ou un globalName personnalisé, enregistrez-le vous-même : voir Tests.
• En développement : enregistrez le plugin dans le tableau plugins de premier niveau. Sous build.rollupOptions.plugins, ou dans une config Rollup ou Rolldown, il ne fait que supprimer les appels et n'installe rien. Un worker n'a pas d'environnement d'exécution de développement à lui : appelez $debug depuis la page, ou sous la forme globalThis.$debug?.(...) dans le code du worker. Un <script> en ligne classique s'exécute avant le chargement de l'environnement d'exécution : appelez $debug depuis du code de module. Voir Code exécuté dans un Worker.
• En production : les appels sont réécrits en void 0 au build, donc la suppression n'a pas atteint cet appel. Vérifiez d'abord que le plugin est enregistré pour vite build : sans condition, dans le tableau plugins de premier niveau, pas derrière command === "serve" ou apply: "serve" (voir Installer et enregistrer le plugin). Cherchez ensuite un avertissement de build : un <script> en ligne classique ou un attribut on*, une méthode calculée comme $debug['time'](), une référence qui n'est pas un appel (const d = $debug), un fichier que la suppression n'a pas pu analyser, ou un script qu'elle a laissé tel quel (importé avec ?raw, ou un fichier TypeScript que Vite a copié). Voir Builds de production. Certains appels restent sans avertissement : les appels d'une dépendance (voir Les appels $debug de ma bibliothèque font planter l'application consommatrice) ou d'un fichier de public/, une clé dynamique comme globalThis[name](), et trois configurations rares (une page HTML chargée comme ressource, un worker en ligne qui partage son nom de fichier avec un script copié, et un plugin qui remplace worker.plugins tardivement). Voir Limites connues de la suppression.

ESLint signale $debug comme non défini

La règle no-undef signale '$debug' is not defined parce qu'elle ne lit pas les types TypeScript. Étalez la configuration plate fournie : voir Déclarer la globale à ESLint.

La sortie semble incorrecte

Chaque log apparaît deux fois

Vite ne déduplique pas les plugins par nom. Si un préréglage de framework ou un module Nuxt ajoute déjà mtDebug(), l'ajouter vous-même laisse deux instances actives, et chaque log du navigateur apparaît alors deux fois dans le terminal.

Le plugin le détecte : la première instance reste active, les autres se mettent en retrait, et un unique avertissement indique leur nombre :

[MARS-TECH] registered 2 times — a framework preset or module has probably added it alongside your vite.config. Keeping the first instance; the rest stand down. Remove the duplicate to silence this.

Supprimez le doublon pour le faire taire. L'instance conservée est la première enregistrée : ce sont ses options qui s'appliquent, sauf redact et redactDefaults : elle applique les règles de chaque instance en retrait en plus des siennes. Quand le doublon vient d'une autre copie installée du plugin, l'instance conservée ne peut pas lire ses règles, qui peuvent contenir des entrées chaîne : $debug n'affiche alors rien dans Node et le terminal ignore les lignes du navigateur, avec un avertissement, tant que le doublon n'est pas supprimé.

Rien dans la chronologie de Vue DevTools

C'est presque toujours l'une de ces deux causes, qui relèvent du comportement de Vue DevTools et non d'un bogue :

1. Vous regardez l'onglet Timeline de la barre latérale. Il ne liste que Mouse, Keyboard, Component events et Performance, un ensemble codé en dur. Les couches de plugin n'y apparaissent pas. La nôtre se trouve dans l'onglet MARS-TECH → Timeline.
2. L'enregistrement est coupé. Les couches démarrent désactivées, et toute réouverture ou tout rechargement les désactive à nouveau. Cliquez sur le bouton d'enregistrement (●) en haut à droite de cette vue pour l'armer. Les appels faits avant ne sont pas enregistrés.

L'inspecteur State du même onglet n'exige ni l'un ni l'autre et reste toujours alimenté : utilisez-le si vous voulez simplement les derniers appels. Voir la chronologie de Vue DevTools.

Mon log n'a pas de fichier:ligne

C'est attendu dans deux cas : les logs venant d'une bibliothèque construite avec brandPrefix ne portent aucune localisation, par conception (voir Les logs de bibliothèque n'ont pas de localisation source), et showSource: false la désactive globalement (voir l'option showSource).

Le fichier:ligne de mon log est décalé de quelques lignes

La transformation de développement enregistre la position d'origine d'un appel direct, $debug(...) ou $debug.ns("x")(...). Un appel qu'elle ne peut pas enregistrer prend sa position dans la pile d'appels de l'environnement d'exécution : un journaliseur gardé depuis ns() et appelé plus tard (const log = $debug.ns("cart"); log(...)), count(), timeEnd(), assert() et, côté serveur, les libellés de group(), table() et dir().

Cette position a le même format, mais c'est l'endroit où le moteur JavaScript a exécuté le code, sans source map appliquée. Dans un fichier .vue compilé, un fichier TypeScript ou un module SSR, elle peut être décalée de plusieurs lignes, et sa colonne aussi. Appelez $debug(...) directement là où la ligne exacte compte.

$debug n'affiche rien côté serveur

Avec des entrées chaîne dans redact, un $debug qui ne peut pas les lire n'affiche rien, plutôt que de les afficher en clair, et avertit une fois :

[MARS-TECH] $debug prints nothing in this process: the string entries of your redact option do not reach it, and it does not print what it cannot mask. They reach SSR in the Vite process and in a worker thread started after the plugin, and Vitest workers (the forks and vmForks pools from Vitest 4). Elsewhere - SSR in a process of its own, workerd - describe each such value with a RegExp for its shape instead.

C'est le cas, par exemple, du SSR dans un processus à part, ou dans workerd (@cloudflare/vite-plugin). Pour y voir la sortie, remplacez chacune de ces entrées chaîne par une RegExp qui décrit la forme de la valeur. Là où les entrées chaîne n'arrivent pas liste tous les cas, tests compris, avec la solution pour chacun.

Bibliothèques

Les consommateurs de ma bibliothèque n'ont aucun log de développement

La variante de débogage n'est atteignable que si votre package.json dirige une condition development vers elle. Le plugin avertit une fois par build quand il n'en trouve pas : voir Câbler les exports conditionnels.

Les appels $debug de ma bibliothèque font planter l'application consommatrice

Une bibliothèque qui livre des appels $debug(...) bruts sans la double variante lève une ReferenceError à l'exécution dans l'application de production du consommateur. Le build lui-même réussit, donc rien ne l'attrape plus tôt. Construisez la bibliothèque avec library.debugBuild : voir Création de bibliothèque.