Encodage d’URL expliqué : percent-encoding et erreurs fréquentes

L'encodage d'URL — aussi appelé percent-encoding — est le système qui permet à une URL de transporter des caractères qu'elle n'a jamais été conçue pour contenir. Une URL est, fondamentalement, une chaîne de caractères ASCII strictement formatée. Dès que vous devez y mettre un espace, un accent, un emoji ou un mot arabe, un problème se pose : ces caractères ne sont pas dans le jeu ASCII, et plusieurs signes de ponctuation sont déjà réservés pour la structure.

La solution, c'est la substitution. Tout caractère qui ne peut pas apparaître littéralement est remplacé par un signe pourcent suivi de deux chiffres hexadécimaux, qui représentent la valeur de l'octet du caractère. Un espace est %20, un point d'interrogation est %3F, un dièse est %23, et une esperluette est %26. Lire et écrire ces échappements, c'est exactement ce que fait un encodeur d'URL.

Trois idées expliquent presque tous les bugs d'encodage que vous rencontrerez. L'encodage est sensible au contexte — les règles diffèrent entre le chemin et la chaîne de requête. L'encodage est idempotent quand il est fait une fois — encoder une valeur déjà encodée une seconde fois crée une valeur cassée. Et l'encodage doit respecter la structure — les caractères qui construisent une URL ne doivent jamais être encodés, car les encoder les transforme en données.

Le reste de l'article parcourt quels caractères sont sûrs, comment le chemin et la chaîne de requête diffèrent, pourquoi + et %20 ne sont pas interchangeables, comment UTF-8 gère les scripts non latins, le bug du double encodage et sa signature, et quand il ne faut pas encoder du tout. S'il vous faut juste une conversion, l' encodeur et décodeur d'URL la fait instantanément dans votre navigateur.

Pourquoi les URL ont-elles besoin d'encodage ?

Une URL n'est pas un champ de texte libre ; c'est une adresse structurée avec une grammaire. Les caractères ?, &, =, #, / et % sont réservés, ce qui veut dire qu'ils ont des rôles structurels. Le ? marque où le chemin se termine et où la requête commence ; & sépare les paramètres ; = sépare un paramètre de sa valeur ; # démarre le fragment.

Dès que l'un de ces caractères apparaît dans vos données, l'URL devient ambiguë. Une recherche de a&b serait lue comme deux paramètres, et une valeur contenant #tronquerait tout ce qui suit en un fragment qui n'atteint jamais le serveur. Les encoder — a%26b — lève l'ambiguïté, parce que %26 ne peut signifier que « un caractère esperluette » et jamais « commence un nouveau paramètre ».

La même logique s'applique aux caractères simplement interdits. Les URL sont définies sur un répertoire ASCII limité, donc un espace, un caractère de contrôle, ou quoi que ce soit de non latin ne peut pas apparaître littéralement sans être échappé. Le percent-encoding est l'unique mécanisme qui gère les deux cas : les caractères réservés qui seraient mal interprétés, et les caractères qui ne peuvent pas être écrits du tout.

Quels caractères peut-on laisser tranquilles ?

Il existe un petit ensemble de caractères que vous n'avez jamais besoin d'encoder, appelé les caractères non réservés. Le mémoriser évite beaucoup d'incertitude, parce que tout ce qui est dans cet ensemble signifie exactement lui-même partout dans une URL :

Notez la dernière ligne : les caractères réservés sont conditionnels. Une / qui sépare des segments de chemin doit rester littérale, mais une / dans un nom de fichier doit être encodée en %2F, sinon elle sera lue comme un niveau de répertoire supplémentaire. Cette règle conditionnelle — structure contre données — c'est tout l'enjeu.

Chemin versus chaîne de requête : les règles diffèrent

Une URL a des zones distinctes, et les règles d'encodage ne sont pas uniformes entre elles. La partie avant le ? est le chemin ; tout ce qui suit est la chaîne de requête. Navigateurs, serveurs et bibliothèques d'analyse appliquent des conventions différentes à chacune, ce qui est une source discrète de bugs.

• Dans le chemin, un espace doit être encodé en %20. Un + dans le chemin est un signe plus littéral, pas un espace.
• Dans la chaîne de requête, %20 et + peuvent tous deux signifier un espace, mais seulement parce que les chaînes de requête suivent traditionnellement la convention application/x-www-form-urlencoded des formulaires HTML.
• Les décodeurs ne sont pas d'accord. En JavaScript, URLSearchParams transforme + en espace, tandis que decodeURIComponent laisse + comme un plus littéral. Mélangez-les, et la même URL donne deux valeurs différentes.

L'apprentissage pratique, c'est de savoir pour quelle zone vous encodez, et de décoder avec le décodeur correspondant. Si une valeur fait un aller-retour incorrect alors que le texte semble bon, vérifiez si un + parasite est interprété comme un espace à un endroit et comme un plus ailleurs.

Le piège du + contre le %20

Cela mérite sa propre section car c'est le bug d'encodage le plus fréquent, et il est invisible jusqu'à ce qu'il vous tombe dessus. + et %20 peuvent tous deux représenter un espace — mais seulement à l'intérieur d'une chaîne de requête, et seulement sous la convention d'encodage de formulaire.

La convention du + vient de la soumission des formulaires HTML. Quand un formulaire envoie des données en application/x-www-form-urlencoded, les espaces dans les valeurs des champs sont écrits +. Cette convention s'est reportée aux chaînes de requête, c'est pourquoi ?q=hello+world et ?q=hello%20world arrivent tous les deux comme « hello world » sur la plupart des serveurs.

Le mode d'échec est subtil. Si vous encodez le texte littéral 1+1 parce que vous voulez que le signe plus survive, vous obtenez 1%2B1 — correct. Mais si vous substituez naïvement les espaces par des + dans un chemin, ou si vous laissez un décodeur de formulaire toucher une valeur où + était censé être littéral, vous obtenez une corruption silencieuse : « 1 1 » au lieu de « 1+1 ».

L'habitude sûre, c'est d'utiliser %20 pour les espaces partout, ce qui est sans ambiguïté dans toutes les zones, et de réserver + au cas spécifique de l'encodage de formulaire où vous savez que le destinaire l'attend. En débogage, rappelez-vous l'asymétrie : URLSearchParams décode + en espace, decodeURIComponent non.

UTF-8, accents et scripts non latins

Le texte non latin ajoute une complication qui surprend tout le monde la première fois. Une URL est en ASCII, donc une lettre accentuée ou un caractère arabe doit d'abord être converti en octets — en UTF-8 — puis chaque octet est encodé en pourcent individuellement.

Le mot français café s'encode en caf%C3%A9 : les lettres ASCII passent inchangées, tandis que le é est deux octets en UTF-8, donnant %C3 et %A9. Un mot arabe s'étend davantage — chaque lettre est plusieurs octets, donc un mot court devient une longue suite de groupes de pourcent comme %D9%85%D8%B1....

• Un caractère peut être plusieurs groupes. Ne supposez jamais qu'un groupe de pourcent égale un caractère ; comptez les octets, pas les échappements.
• Le mauvais jeu de caractères brouille le texte. Si le serveur décode les octets avec un encodage à un seul octet au lieu d'UTF-8, les accents deviennent de la bouillie. UTF-8 est le standard par défaut pour une raison — tenez-vous-y sauf raison ancienne spécifique.
• Les navigateurs modernes masquent cela. Ils affichent des URL lisibles et font l'encodage à la soumission, donc une URL arabe collée a l'air propre dans la barre d'adresse même si la requête sur le fil est encodée en pourcent. Cet écart entre l'affichage et le fil est précisément pourquoi un encodeur explicite est parfois nécessaire.

C'est aussi le cas où un outil dédié aide le plus, parce que l'encodage manuel du texte non latin est propice aux erreurs. L' encodeur d'URL convertit le texte vers sa forme percent UTF-8 correcte et inversement.

Le bug du double encodage et sa signature

Le double encodage est le bug qui continue de donner, parce qu'il produit une URL qui semble encodée et arrive pourtant fausse. Il se produit quand une valeur déjà encodée est encodée à nouveau — fréquent quand une fonction passe une valeur à une autre sans savoir que la première l'avait déjà échappée.

Suivez l'arithmétique. Un espace devient %20. Encodez ce résultat à nouveau et c'est le signe pourcent lui-même qui est encodé, puisque % est un caractère réservé : %20 devient %2520. Un tour de décodage donne maintenant la chaîne littérale %20 au lieu d'un espace, parce que la valeur contenait un vrai signe pourcent.

La signature révélatrice, c'est un %25 là où un % devrait être — %2520, %2526, %252F sont toutes des valeurs doublement encodées. Si vous les voyez, la valeur a été encodée deux fois.

La correction, c'est de décoder exactement le nombre de fois où la valeur a été encodée, mais la meilleure correction, c'est la prévention : encodez une valeur brute une fois, à la frontière où elle entre dans l'URL, et gardez une source unique de vérité sur le fait qu'une valeur est déjà encodée ou non. Les fonctions qui « gentiment » ré-encodent leur entrée sont les coupables habituelles.

Quand ne faut-il pas encoder ?

L'encodage est un outil, pas une politique de « tout encoder, au cas où ». Appliqué aveuglément, il casse les très URL qu'il était censé protéger, parce que les caractères structurels sont ce qui rend une URL analysable.

• N'encodez jamais le squelette structurel. Le :// après le schème, les / entre les segments de chemin, et les ? & = # de la chaîne de requête doivent rester littéraux. Encodez-les, et l'adresse cesse d'être une adresse.
• N'encodez jamais une valeur déjà encodée. C'est le bug de double encodage de la section précédente, et il est entièrement auto-infligé.
• N'encodez pas pour « nettoyer » une URL que vous ne comprenez pas. Si une URL échoue déjà, encoder davantage au hasard aide rarement et cache souvent le vrai problème. Décodez-la complètement d'abord, voyez quelles sont les valeurs brutes, puis encodez une fois.

Le modèle mental à garder : encodez la valeur, jamais la structure. Construisez l'URL à partir de parties de confiance, encodez chaque valeur de données exactement une fois en entrant, et laissez les délimiteurs faire leur travail.

Là où ça se présente en pratique

Voici les situations où un bug d'encodage coûte vraiment du temps, et où connaître les règles paie.

• Les paramètres de recherche. Une barre de recherche contenant & ou = va se scinder en paramètres supplémentaires à moins que la valeur ne soit encodée. Les constructeurs de requête des frameworks gèrent ça en général ; la concaténation de chaînes, non.
• Les liens de suivi. Les paramètres UTM transportent des titres et des noms de campagne qui contiennent couramment espaces et accents. Un seul espace non encodé dans un lien d'e-mail, et toute l'URL casse pour chaque destinataire qui clique.
• Les requêtes d'API. Les API reçoivent des valeurs comme paramètres d'URL, et un # non encodé tronque silencieusement la requête, tandis qu'un + littéral devient un espace. L'encodage n'est pas optionnel ici — il fait partie du contrat.
• Les redirections et URL transmises. Quand une URL est passée à l'intérieur d'une autre, elle doit être encodée comme une valeur unique, sinon l'URL externe lit mal les délimiteurs de l'interne.

Chacun de ces cas, c'est le même bug sous des habits différents : une valeur n'a pas été encodée là où la grammaire l'exigeait, ou elle a été encodée deux fois par un code qui ne faisait pas confiance à la dernière étape.

Encoder ou décoder une URL sans se prendre la tête

Quel que soit le problème d'URL, la conversion elle-même devrait prendre des secondes :

• Un encodeur et décodeur d'URL gratuit qui gère le percent-encoding dans les deux sens.
• Gestion UTF-8 correcte pour les accents, l'arabe et les autres scripts non latins.
• Entièrement dans votre navigateur — rien de ce que vous collez n'est envoyé.
• Membre de la famille plus large d'outils de texte : compteur de mots, compteur de caractères, convertisseur de casse et encodeur Base64.

Questions fréquentes