Guia Completo de Codificação URL: Princípios e Prática da Codificação Porcentual

Revisão da Estrutura de URL

https://user:pass@www.example.com:8080/path/to/page?name=张三&age=25#section
└──┬──┘ └────┬────┘ └──────┬──────┘└─┬─┘└────┬─────┘└──────┬──────┘└──┬──┘
  scheme   userinfo     host      port    path        query     fragment

Apenas as partes de path, query e fragment precisam de codificação. Scheme e host seguem suas próprias regras.

Por Que a Codificação URL É Necessária

URLs só podem conter caracteres ASCII imprimíveis. Os seguintes devem ser codificados:

Caractere	Codificação	Motivo
Espaço	`%20` ou `+`	Espaços simples não são permitidos
Chinês「张三」	`%E5%BC%A0%E4%B8%89`	Não ASCII
`&`	`%26`	Separador de consulta
`=`	`%3D`	Separador chave=valor
`#`	`%23`	Marcador de fragmento
`?`	`%3F`	Início da consulta
`/`	`%2F`	Separador de caminho

Usando a Ferramenta de Codificação/Decodificação URL do ToolsKu

Passos

Abra a ferramenta de Codificação/Decodificação URL
Insira uma URL ou texto
Escolha codificar ou decodificar
Veja o resultado

encodeURI vs encodeURIComponent

Função	Não codificado	Caso de uso
`encodeURI()`	`: / ? # [ ] @ ! $ & ' ( ) * + , ; =`	URL completa
`encodeURIComponent()`	`A-Z a-z 0-9 - _ . ! ~ * ' ( )`	Valores de parâmetros URL

const base = 'https://example.com/search';

// ✅ Codificar valores de parâmetros
const url = `${base}?q=${encodeURIComponent('hello world')}`;
// → https://example.com/search?q=hello%20world

// ❌ Codificar a URL inteira
const wrong = encodeURIComponent('https://example.com/search?q=test');
// → https%3A%2F%2Fexample.com%2Fsearch%3Fq%3Dtest

Cenários Práticos

Parâmetros de consulta em chinês

Original: https://search.com/q=前端开发
Codificado:  https://search.com/q=%E5%89%8D%E7%AB%AF%E5%BC%80%E5%8F%91

Analisar parâmetros URL

Use a ferramenta de Análise URL para decompor uma URL e exibir os parâmetros de consulta em uma tabela:

Entrada: https://api.com/users?name=张三&role=admin&page=1
Saída:
  name  = 张三
  role  = admin
  page  = 1

Nomes de domínio internacionalizados (IDN)

Codificação Punycode para o domínio chinês「工具库.com」:

工具库.com → xn--6qq986b3xl.com

Use a ferramenta Punycode para converter entre formas.

Parâmetros URL codificados em Base64

Às vezes você precisa codificar um objeto JSON como parâmetro URL:

{"user":"admin","role":"editor"}
  → Base64 → eyJ1c2VyIjoiYWRtaW4iLCJyb2xlIjoiZWRpdG9yIn0=
  → URL encode → eyJ1c2VyIjoiYWRtaW4iLCJyb2xlIjoiZWRpdG9yIn0%3D

Erros Comuns

Codificação dupla

Original:     hello world
Uma vez codificado: hello%20world  ✅
Duas vezes codificado: hello%2520world  ❌ (decodificar uma vez → hello%20world)

Codificar a URL inteira

Use encodeURIComponent apenas nos valores dos parâmetros, não na URL completa.

Espaço: `+` ou `%20`?

Em parâmetros de consulta: + e %20 são equivalentes
Em caminhos: apenas %20 é válido
Recomendação: use %20 consistentemente

Resumo

A codificação URL é uma habilidade fundamental de desenvolvimento Web. Entender a diferença entre encodeURI e encodeURIComponent, a codificação UTF-8 para parâmetros em chinês e Punycode para domínios internacionalizados economiza horas de depuração. O ToolsKu oferece ferramentas de Codificação/Decodificação URL, Análise URL e Punycode.