Passer au contenu principal

​
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 du système d’exploitation/plateforme : Si vous recevez une erreur lors de l’installation, WSL peut utiliser npm 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 PAS sudo)
Erreurs Node non trouvé : Si vous voyez exec: node: not found lors de l’exécution de claude, votre environnement WSL peut utiliser une installation Windows de Node.js. Vous pouvez confirmer cela 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 pouvez rencontrer des conflits de version lors du changement de versions de Node dans WSL. Cela se produit parce que WSL importe le PATH Windows par défaut, ce qui fait que Windows nvm/npm prend priorité sur l’installation WSL. Vous pouvez identifier ce problème par :
  • Exécuter which npm et which node - s’ils pointent vers des chemins Windows (commençant par /mnt/c/), les versions Windows sont utilisées
  • Rencontrer des fonctionnalités cassées après avoir changé de version de Node avec nvm dans WSL
Pour résoudre ce problème, corrigez votre PATH Linux pour vous assurer que les versions Linux de node/npm prennent priorité : Solution principale : Assurez-vous que nvm est correctement chargé dans votre shell La cause la plus courante est que nvm n’est pas chargé dans les shells non interactifs. Ajoutez ce qui suit à votre fichier de configuration shell (~/.bashrc, ~/.zshrc, etc.) : 
# Load nvm if it exists
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"
Ou exécutez directement dans votre session actuelle : 
source ~/.nvm/nvm.sh
Alternative : Ajustez l’ordre du PATH Si nvm est correctement chargé mais que les chemins Windows prennent toujours priorité, vous pouvez explicitement ajouter vos chemins Linux au début du PATH dans votre configuration shell : 
export PATH="$HOME/.nvm/versions/node/$(node -v)/bin:$PATH"
Évitez de désactiver l’importation du PATH Windows (appendWindowsPath = false) car cela casse la capacité à 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 pouvez également rencontrer des erreurs de permission si votre préfixe global npm n’est pas accessible en écriture par l’utilisateur (par exemple /usr ou /usr/local).

​
Solution recommandée : Installation native de Claude Code

Claude Code dispose d’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 : 
# Install stable version (default)
curl -fsSL https://claude.ai/install.sh | bash

# Install latest version
curl -fsSL https://claude.ai/install.sh | bash -s latest

# Install specific version number
curl -fsSL https://claude.ai/install.sh | bash -s 1.0.58
Windows PowerShell : 
# Install stable version (default)
irm https://claude.ai/install.ps1 | iex

# Install latest version
& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) latest

# Install specific version number
& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) 1.0.58
Cette commande installe la version appropriée de Claude Code pour votre système d’exploitation et votre architecture, et ajoute un lien symbolique à l’installation à ~/.local/bin/claude.
Assurez-vous que vous avez le répertoire d’installation dans votre PATH système.
Vérifiez l’installation : 
claude doctor # Check installation health

​
Permissions et authentification

​
Invites de permission répétées

Si vous vous trouvez à approuver à plusieurs reprises 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 :
  1. Exécutez /logout pour vous déconnecter complètement
  2. Fermez Claude Code
  3. Redémarrez avec claude et complétez le processus d’authentification à nouveau
Si les problèmes persistent, essayez : 
rm -rf ~/.config/claude-code/auth.json
claude
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 importantes lors du traitement de grandes bases de code. Si vous rencontrez des problèmes de performance :
  1. Utilisez /compact régulièrement pour réduire la taille du contexte
  2. Fermez et redémarrez Claude Code entre les tâches majeures
  3. Envisagez d’ajouter de grands répertoires de compilation à votre fichier .gitignore

​
Les commandes se figent ou se bloquent

Si Claude Code semble ne pas répondre :
  1. Appuyez sur Ctrl+C pour tenter d’annuler l’opération actuelle
  2. S’il ne répond pas, vous devrez peut-être fermer le terminal et redémarrer

​
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 le système ripgrep : 
# macOS (Homebrew)  
brew install ripgrep

# Windows (winget)
winget install BurntSushi.ripgrep.MSVC

# Ubuntu/Debian
sudo apt install ripgrep

# Alpine Linux
apk add ripgrep

# Arch Linux
pacman -S ripgrep
Ensuite, 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 sur les systèmes de fichiers sur WSL peuvent entraîner moins de correspondances que prévu (mais pas une absence complète de fonctionnalité de recherche) lors de l’utilisation de Claude Code sur WSL.
/doctor affichera Search comme OK dans ce cas.
Solutions :
  1. Soumettez des recherches plus spécifiques : Réduisez le nombre de fichiers recherchés en spécifiant des répertoires ou des 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 ».
  2. 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/).
  3. Utilisez Windows natif à la place : Envisagez d’exécuter Claude Code nativement sur Windows au lieu de via WSL, pour une meilleure performance du système de fichiers.

​
Problèmes d’intégration IDE

​
IDE JetBrains non détecté sur WSL2

Si vous utilisez Claude Code sur WSL2 avec les IDE JetBrains et que vous recevez des erreurs « Aucun IDE disponible détecté », cela est probablement dû à la configuration réseau de WSL2 ou au pare-feu Windows bloquant la connexion.

​
Modes de mise en réseau WSL2

WSL2 utilise la mise en réseau NAT par défaut, ce qui peut empêcher la détection de l’IDE. Vous avez deux options : Option 1 : Configurer le pare-feu Windows (recommandé)
  1. Trouvez votre adresse IP WSL2 : 
    wsl hostname -I
# Example output: 172.21.123.456
  2. Ouvrez PowerShell en tant qu’administrateur et créez une règle de pare-feu : 
    New-NetFirewallRule -DisplayName "Allow WSL2 Internal Traffic" -Direction Inbound -Protocol TCP -Action Allow -RemoteAddress 172.21.0.0/16 -LocalAddress 172.21.0.0/16
    (Ajustez la plage d’adresses IP en fonction de votre sous-réseau WSL2 à partir de l’étape 1)
  3. Redémarrez à la fois votre IDE et Claude Code
Option 2 : Basculer vers la mise en réseau en miroir Ajoutez à .wslconfig dans votre répertoire utilisateur Windows : 
[wsl2]
networkingMode=mirrored
Ensuite, redémarrez WSL avec wsl --shutdown depuis PowerShell.
Ces problèmes de mise en réseau n’affectent que WSL2. WSL1 utilise directement le réseau de l’hôte et ne nécessite pas ces configurations.
Pour des conseils de configuration JetBrains supplémentaires, consultez notre guide d’intégration IDE.

​
Signaler les problèmes d’intégration IDE Windows (natif et WSL)

Si vous rencontrez des problèmes d’intégration IDE sur Windows, veuillez créer un problème avec les informations suivantes : si vous êtes natif (git bash) ou WSL1/WSL2, mode de mise en réseau WSL (NAT ou miroir), nom/version de l’IDE, version de l’extension/plugin Claude Code et type de shell (bash/zsh/etc)

​
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 prévu, cela est probablement dû à un conflit de liaison de touches avec les raccourcis par défaut de JetBrains. Pour corriger ce problème :
  1. Allez à Paramètres → Outils → Terminal
  2. Soit :
    • Décochez « Déplacer le focus vers l’éditeur avec Échap », soit
    • Cliquez sur « Configurer les liaisons de touches du terminal » et supprimez le raccourci « Basculer le focus vers l’éditeur »
  3. Appliquez les modifications
Cela permet à la touche ESC d’interrompre correctement les opérations de Claude Code.

​
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 celui-ci dans le markdown généré : 
```
function example() {
  return "hello";
}
```
Au lieu de blocs correctement balisés comme : 
```javascript
function example() {
  return "hello";
}
```
Solutions :
  1. 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. »
  2. Utilisez des crochets de post-traitement : Configurez des crochets de formatage automatiques pour détecter et ajouter les balises de langage manquantes. Consultez l’exemple de crochet de formatage markdown pour les détails de mise en œuvre.
  3. Vérification manuelle : Après la génération de fichiers markdown, vérifiez-les pour un formatage correct 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 vierges excessives ou un espacement incohérent : Solutions :
  1. Demandez des corrections de formatage : Demandez à Claude de « Corriger les problèmes d’espacement et de formatage dans ce fichier markdown. »
  2. Utilisez des outils de formatage : Configurez des crochets pour exécuter des formateurs markdown comme prettier ou des scripts de formatage personnalisés sur les fichiers markdown générés.
  3. Spécifiez les préférences de formatage : Incluez les exigences de formatage dans vos invites ou fichiers mémoire du projet.

​
Meilleures pratiques pour la génération de markdown

Pour minimiser les problèmes de formatage :
  • Soyez explicite dans les demandes : Demandez un « markdown correctement formaté avec des blocs de code balisés par langage »
  • Utilisez les conventions du projet : Documentez votre style markdown préféré dans CLAUDE.md
  • Configurez des crochets de validation : Utilisez des crochets 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 :
  1. Utilisez la commande /bug dans Claude Code pour signaler les problèmes directement à Anthropic
  2. Vérifiez le référentiel GitHub pour les problèmes connus
  3. Exécutez /doctor pour vérifier la santé de votre installation Claude Code
  4. Demandez directement à Claude ses capacités et fonctionnalités - Claude a un accès intégré à sa documentation