Dépannage
Découvrez des solutions aux problèmes courants d’installation et d’utilisation de Claude Code.
Problèmes d’installation courants
Problèmes d’installation Windows : erreurs dans WSL
Vous pourriez rencontrer les problèmes suivants dans WSL :
Problèmes de détection OS/plateforme : Si vous recevez une erreur lors de l’installation, WSL pourrait utiliser le npm
de Windows. Essayez :
- Exécutez
npm config set os linux
avant l’installation - Installez avec
npm install -g @anthropic-ai/claude-code --force --no-os-check
(N’utilisez PASsudo
)
Erreurs Node non trouvé : Si vous voyez exec: node: not found
lors de l’exécution de claude
, votre environnement WSL pourrait utiliser une installation Windows de Node.js. Vous pouvez le confirmer avec which npm
et which node
, qui devraient pointer vers des chemins Linux commençant par /usr/
plutôt que /mnt/c/
. Pour corriger cela, essayez d’installer Node via le gestionnaire de paquets de votre distribution Linux ou via nvm
.
Conflits de version nvm : Si vous avez nvm installé à la fois dans WSL et Windows, vous pourriez rencontrer des conflits de version lors du changement de versions Node dans WSL. Cela se produit parce que WSL importe le PATH Windows par défaut, causant la priorité de nvm/npm Windows sur l’installation WSL.
Vous pouvez identifier ce problème en :
- Exécutant
which npm
etwhich node
- s’ils pointent vers des chemins Windows (commençant par/mnt/c/
), les versions Windows sont utilisées - Rencontrant des fonctionnalités cassées après avoir changé les versions Node avec nvm dans WSL
Pour résoudre ce problème, corrigez votre PATH Linux pour assurer que les versions Linux node/npm prennent la priorité :
Solution principale : Assurez-vous que nvm est correctement chargé dans votre shell
La cause la plus commune est que nvm n’est pas chargé dans les shells non-interactifs. Ajoutez ce qui suit à votre fichier de configuration shell (~/.bashrc
, ~/.zshrc
, etc.) :
Ou exécutez directement dans votre session actuelle :
Alternative : Ajuster l’ordre du PATH
Si nvm est correctement chargé mais les chemins Windows prennent encore la priorité, vous pouvez explicitement préfixer vos chemins Linux au PATH dans votre configuration shell :
Évitez de désactiver l’importation du PATH Windows (appendWindowsPath = false
) car cela casse la capacité d’appeler facilement les exécutables Windows depuis WSL. De même, évitez de désinstaller Node.js de Windows si vous l’utilisez pour le développement Windows.
Problèmes d’installation Linux et Mac : erreurs de permission ou commande non trouvée
Lors de l’installation de Claude Code avec npm, les problèmes de PATH
peuvent empêcher l’accès à claude
.
Vous pourriez aussi rencontrer des erreurs de permission si votre préfixe global npm n’est pas accessible en écriture par l’utilisateur (ex. /usr
, ou /usr/local
).
Solution recommandée : Installation native de Claude Code
Claude Code a une installation native qui ne dépend pas de npm ou Node.js.
L’installateur natif de Claude Code est actuellement en bêta.
Utilisez la commande suivante pour exécuter l’installateur natif.
macOS, Linux, WSL :
Windows PowerShell :
Cette commande installe la version appropriée de Claude Code pour votre système d’exploitation et architecture et ajoute un lien symbolique vers l’installation à ~/.local/bin/claude
.
Assurez-vous d’avoir le répertoire d’installation dans votre PATH système.
Solution alternative : Migrer vers une installation locale
Alternativement, si Claude Code fonctionne, vous pouvez migrer vers une installation locale :
Cela déplace Claude Code vers ~/.claude/local/
et configure un alias dans votre configuration shell. Aucun sudo
n’est requis pour les futures mises à jour.
Après la migration, redémarrez votre shell, puis vérifiez votre installation :
Sur macOS/Linux/WSL :
Sur Windows :
Vérifiez l’installation :
Permissions et authentification
Invites de permission répétées
Si vous vous trouvez à approuver répétitivement les mêmes commandes, vous pouvez autoriser des outils spécifiques
à s’exécuter sans approbation en utilisant la commande /permissions
. Voir Documentation des permissions.
Problèmes d’authentification
Si vous rencontrez des problèmes d’authentification :
- Exécutez
/logout
pour vous déconnecter complètement - Fermez Claude Code
- Redémarrez avec
claude
et complétez à nouveau le processus d’authentification
Si les problèmes persistent, essayez :
Cela supprime vos informations d’authentification stockées et force une connexion propre.
Performance et stabilité
Utilisation élevée du CPU ou de la mémoire
Claude Code est conçu pour fonctionner avec la plupart des environnements de développement, mais peut consommer des ressources significatives lors du traitement de grandes bases de code. Si vous rencontrez des problèmes de performance :
- Utilisez
/compact
régulièrement pour réduire la taille du contexte - Fermez et redémarrez Claude Code entre les tâches importantes
- Considérez ajouter les grands répertoires de build à votre fichier
.gitignore
La commande se bloque ou se fige
Si Claude Code semble ne pas répondre :
- Appuyez sur Ctrl+C pour tenter d’annuler l’opération actuelle
- Si non réactif, vous pourriez avoir besoin de fermer le terminal et redémarrer
La touche ESC ne fonctionne pas dans les terminaux JetBrains (IntelliJ, PyCharm, etc.)
Si vous utilisez Claude Code dans les terminaux JetBrains et que la touche ESC n’interrompt pas l’agent comme attendu, c’est probablement dû à un conflit de raccourci clavier avec les raccourcis par défaut de JetBrains.
Pour corriger ce problème :
- Allez dans Paramètres → Outils → Terminal
- Cliquez sur le lien hypertexte “Configure terminal keybindings” à côté de “Override IDE Shortcuts”
- Dans les raccourcis clavier du terminal, faites défiler vers le bas jusqu’à “Switch focus to Editor” et supprimez ce raccourci
Cela permettra à la touche ESC de fonctionner correctement pour annuler les opérations Claude Code au lieu d’être capturée par l’action “Switch focus to Editor” de PyCharm.
Problèmes de recherche et de découverte
Si l’outil de recherche, les mentions @file
, les agents personnalisés et les commandes slash personnalisées ne fonctionnent pas, installez ripgrep
système :
Puis définissez USE_BUILTIN_RIPGREP=0
dans votre environnement.
Résultats de recherche lents ou incomplets sur WSL
Les pénalités de performance de lecture de disque lors du travail à travers les systèmes de fichiers sur WSL peuvent résulter en moins de correspondances que prévu (mais pas un manque complet de fonctionnalité de recherche) lors de l’utilisation de Claude Code sur WSL.
/doctor
montrera la recherche comme OK dans ce cas.
Solutions :
-
Soumettez des recherches plus spécifiques : Réduisez le nombre de fichiers recherchés en spécifiant des répertoires ou types de fichiers : “Rechercher la logique de validation JWT dans le package auth-service” ou “Trouver l’utilisation du hash md5 dans les fichiers JS”.
-
Déplacez le projet vers le système de fichiers Linux : Si possible, assurez-vous que votre projet est situé sur le système de fichiers Linux (
/home/
) plutôt que sur le système de fichiers Windows (/mnt/c/
). -
Utilisez Windows natif à la place : Considérez exécuter Claude Code nativement sur Windows au lieu de passer par WSL, pour une meilleure performance du système de fichiers.
Problèmes de formatage Markdown
Claude Code génère parfois des fichiers markdown avec des balises de langage manquantes sur les clôtures de code, ce qui peut affecter la coloration syntaxique et la lisibilité dans GitHub, les éditeurs et les outils de documentation.
Balises de langage manquantes dans les blocs de code
Si vous remarquez des blocs de code comme ceci dans le markdown généré :
Au lieu de blocs correctement balisés comme :
Solutions :
-
Demandez à Claude d’ajouter des balises de langage : Demandez simplement “Veuillez ajouter des balises de langage appropriées à tous les blocs de code dans ce fichier markdown.”
-
Utilisez des hooks de post-traitement : Configurez des hooks de formatage automatique pour détecter et ajouter les balises de langage manquantes. Voir l’exemple de hook de formatage markdown pour les détails d’implémentation.
-
Vérification manuelle : Après avoir généré des fichiers markdown, examinez-les pour un formatage approprié des blocs de code et demandez des corrections si nécessaire.
Espacement et formatage incohérents
Si le markdown généré a des lignes vides excessives ou un espacement incohérent :
Solutions :
-
Demandez des corrections de formatage : Demandez à Claude de “Corriger les problèmes d’espacement et de formatage dans ce fichier markdown.”
-
Utilisez des outils de formatage : Configurez des hooks pour exécuter des formateurs markdown comme
prettier
ou des scripts de formatage personnalisés sur les fichiers markdown générés. -
Spécifiez les préférences de formatage : Incluez les exigences de formatage dans vos invites ou fichiers de mémoire de projet.
Meilleures pratiques pour la génération markdown
Pour minimiser les problèmes de formatage :
- Soyez explicite dans les demandes : Demandez du “markdown correctement formaté avec des blocs de code balisés par langage”
- Utilisez les conventions de projet : Documentez votre style markdown préféré dans CLAUDE.md
- Configurez des hooks de validation : Utilisez des hooks de post-traitement pour vérifier et corriger automatiquement les problèmes de formatage courants
Obtenir plus d’aide
Si vous rencontrez des problèmes non couverts ici :
- Utilisez la commande
/bug
dans Claude Code pour signaler les problèmes directement à Anthropic - Vérifiez le dépôt GitHub pour les problèmes connus
- Exécutez
/doctor
pour vérifier la santé de votre installation Claude Code - Demandez directement à Claude sur ses capacités et fonctionnalités - Claude a un accès intégré à sa documentation