URL Encode JavaScript — encodeURIComponent()

Quando costruisci un URL di ricerca, passi un percorso di reindirizzamento come parametro di query, o componi una richiesta di autorizzazione OAuth, i caratteri speciali come &, = e gli spazi corrompono silenziosamente l'URL se non li codifichi prima. JavaScript offre tre approcci nativi — encodeURIComponent(), encodeURI() e URLSearchParams— ognuno progettato per un caso d'uso diverso, e scegliere quello sbagliato è la causa principale della maggior parte dei bug di codifica che ho incontrato nelle code review. Per una codifica rapida senza scrivere codice, il Codificatore URL di ToolDeck lo gestisce istantaneamente nel browser. Questa guida copre tutti e tre gli approcci in profondità (JavaScript ES2015+ / Node.js 10+): quando usare ciascuno, come differiscono per spazi e caratteri riservati, pattern reali con Fetch e API, utilizzo da CLI, e i quattro errori che causano i bug di produzione più subdoli.

Cos'è la codifica URL?

La codifica URL (formalmente chiamata percent-encoding, definita nella RFC 3986) converte i caratteri non consentiti o con significato speciale in un URL in una rappresentazione sicura. Ogni byte non sicuro viene sostituito con un segno percentuale seguito da due cifre esadecimali — il codice ASCII del carattere. Uno spazio diventa %20, una e commerciale diventa %26, una barra diagonale diventa %2F.

I caratteri sempre sicuri e mai codificati sono chiamati caratteri non riservati: le lettere A–Z e a–z, le cifre 0–9, e i quattro simboli - _ . ~. Tutto il resto deve essere codificato quando usato come dato, o ha un ruolo strutturale nell'URL (come / che separa i segmenti di percorso o &che separa i parametri di query). La conseguenza pratica: un nome di prodotto come “Tastiera Wireless & Mouse” in un parametro di query distrugge la struttura dell'URL se passato senza codifica.

https://shop.example.com/search?q=Wireless Keyboard & Mouse&category=peripherals

https://shop.example.com/search?q=Wireless%20Keyboard%20%26%20Mouse&category=peripherals

encodeURIComponent() — La funzione giusta per i parametri di query

encodeURIComponent() è il motore della codifica URL in JavaScript. Codifica tutti i caratteri tranne il set non riservato (A–Z, a–z, 0–9, - _ . ! ~ * ' ( )). In modo critico, codifica tutti i caratteri che hanno significato strutturale negli URL — &, =, ?, #, /— rendendola sicura per l'uso nei valori dei parametri. Non è necessario alcun import; è una funzione globale disponibile in tutti gli ambienti JavaScript.

Esempio minimo funzionante

// Encode a search query parameter that contains special characters
const searchQuery  = 'Wireless Keyboard & Mouse'
const filterStatus = 'in-stock'
const maxPrice     = '149.99'

const searchUrl = `https://shop.example.com/products?` +
  `q=${encodeURIComponent(searchQuery)}` +
  `&status=${encodeURIComponent(filterStatus)}` +
  `&maxPrice=${encodeURIComponent(maxPrice)}`

console.log(searchUrl)
// https://shop.example.com/products?q=Wireless%20Keyboard%20%26%20Mouse&status=in-stock&maxPrice=149.99

Codifica di un URL di reindirizzamento come parametro di query

// The redirect destination is itself a URL — it must be fully encoded
// or the outer URL parser will misinterpret its ? and & as its own
const redirectAfterLogin = 'https://dashboard.internal/reports?view=weekly&team=platform'

const loginUrl = `https://auth.company.com/login?next=${encodeURIComponent(redirectAfterLogin)}`

console.log(loginUrl)
// https://auth.company.com/login?next=https%3A%2F%2Fdashboard.internal%2Freports%3Fview%3Dweekly%26team%3Dplatform

// Decoding on the receiving end
const params    = new URLSearchParams(window.location.search)
const next      = params.get('next')              // Automatically decoded
const nextUrl   = new URL(next!)                  // Safe to parse
console.log(nextUrl.hostname)                     // dashboard.internal

Codifica di caratteri non-ASCII e Unicode

// encodeURIComponent handles Unicode natively in all modern environments
// Each UTF-8 byte of the character is percent-encoded
const customerName = 'Rossi, Marco'
const productTitle = '東京 wireless adapter'
const reviewText   = 'Ottimo — funziona perfettamente'

console.log(encodeURIComponent(customerName))
// Rossi%2C%20Marco

console.log(encodeURIComponent(productTitle))
// %E6%9D%B1%E4%BA%AC%20wireless%20adapter

console.log(encodeURIComponent(reviewText))
// Ottimo%20%E2%80%94%20funziona%20perfettamente

// Decoding back
console.log(decodeURIComponent('Rossi%2C%20Marco'))
// Rossi, Marco

Funzioni di codifica URL in JavaScript — Riferimento dei caratteri

I tre approcci di codifica nativi differiscono esattamente in quali caratteri codificano. La tabella seguente mostra l'output per i caratteri più spesso problematici:

La colonna critica è encodeURIComponent() versus encodeURI() per & e =: encodeURI() li lascia intatti, il che è corretto quando si codifica un URL completo, ma catastrofico quando si codifica un valore che contiene questi caratteri.

encodeURI() — Quando preservare la struttura dell'URL

encodeURI() è progettata per codificare un URL completo— preserva tutti i caratteri che sono parti strutturali valide di una URI: lo schema (https://), l'host, i separatori di percorso, i delimitatori di query e l'identificatore di frammento. Usala quando ricevi un URL che potrebbe contenere spazi o caratteri non-ASCII nei suoi segmenti di percorso, ma hai bisogno di mantenerne la struttura intatta.

Sanificazione di un URL fornito dall'utente

// A URL pasted from a document with spaces in the path and non-ASCII chars
const rawUrl = 'https://cdn.example.com/assets/product images/München chair.png'

const safeUrl = encodeURI(rawUrl)
console.log(safeUrl)
// https://cdn.example.com/assets/product%20images/M%C3%BCnchen%20chair.png

// encodeURIComponent would break it — it encodes the :// and all / characters
const broken = encodeURIComponent(rawUrl)
console.log(broken)
// https%3A%2F%2Fcdn.example.com%2Fassets%2Fproduct%20images%2FM%C3%BCnchen%20chair.png
// ↑ Not a valid URL — the scheme and slashes are destroyed

URLSearchParams — L'approccio moderno per le query string

URLSearchParamsè il modo idiomatico per costruire e analizzare le query string in JavaScript moderno. È disponibile globalmente in tutti i browser moderni e Node.js 10+, e gestisce la codifica automaticamente — lavori con coppie chiave-valore semplici e produce l'output corretto. Un dettaglio importante: segue la specifica application/x-www-form-urlencoded, che codifica gli spazi come + invece di %20. Questo è corretto e ampiamente supportato, ma devi esserne consapevole quando il tuo server si aspetta un formato specifico.

Costruzione di un URL di richiesta di ricerca

// Building a search API URL with multiple parameters
const filters = {
  query:    'standing desk',
  category: 'office-furniture',
  minPrice: '200',
  maxPrice: '800',
  inStock:  'true',
  sortBy:   'price_asc',
}

const params = new URLSearchParams(filters)

const apiUrl = `https://api.example.com/v2/products?${params}`
console.log(apiUrl)
// https://api.example.com/v2/products?query=standing+desk&category=office-furniture&minPrice=200&maxPrice=800&inStock=true&sortBy=price_asc

// Appending additional params after construction
params.append('page', '2')
params.append('tag', 'ergonomic & adjustable')
console.log(params.toString())
// query=standing+desk&...&tag=ergonomic+%26+adjustable

Analisi di una query string in ingresso

// Both browser (window.location.search) and Node.js (req.url) scenarios
function parseWebhookCallbackUrl(rawSearch: string) {
  const params = new URLSearchParams(rawSearch)

  return {
    eventId:     params.get('event_id'),       // null if missing
    timestamp:   Number(params.get('ts')),
    signature:   params.get('sig'),
    redirectUrl: params.get('redirect'),       // Automatically decoded
    tags:        params.getAll('tag'),         // Handles repeated keys
  }
}

const callbackQuery = '?event_id=evt_9c2f&ts=1717200000&sig=sha256%3Dabc123&redirect=https%3A%2F%2Fdashboard.internal%2F&tag=payment&tag=webhook'

const parsed = parseWebhookCallbackUrl(callbackQuery)
console.log(parsed.redirectUrl)  // https://dashboard.internal/
console.log(parsed.tags)         // ['payment', 'webhook']

Come codificare i parametri URL nelle richieste Fetch JavaScript

Il posto più comune dove la codifica URL appare nel codice di produzione è all'interno delle chiamate fetch()— sia costruendo l'URL della richiesta sia inviando dati di form nel corpo della richiesta. Ogni scenario ha il proprio approccio corretto.

Richiesta GET — codifica dei parametri di query

async function searchInventory(params: {
  sku?:      string
  warehouse: string
  minStock:  number
  updatedAfter?: Date
}): Promise<{ items: unknown[]; total: number }> {
  const searchParams = new URLSearchParams()

  if (params.sku)          searchParams.set('sku',          params.sku)
  searchParams.set('warehouse',  params.warehouse)
  searchParams.set('min_stock',  String(params.minStock))
  if (params.updatedAfter) searchParams.set('updated_after', params.updatedAfter.toISOString())

  const url = `https://inventory.internal/api/items?${searchParams}`

  const res = await fetch(url, {
    headers: {
      'Authorization': `Bearer ${process.env.INVENTORY_API_KEY}`,
      'Accept':        'application/json',
    },
  })

  if (!res.ok) {
    throw new Error(`Inventory API ${res.status}: ${await res.text()}`)
  }

  return res.json()
}

const results = await searchInventory({
  warehouse:    'eu-west-1',
  minStock:     10,
  updatedAfter: new Date('2025-01-01'),
})

console.log(`Found ${results.total} items`)

Richiesta POST — codifica URL del corpo di un form

// application/x-www-form-urlencoded POST — used by OAuth token endpoints,
// legacy form-submission APIs, and some webhook providers
async function requestOAuthToken(
  clientId:     string,
  clientSecret: string,
  code:         string,
  redirectUri:  string,
): Promise<{ access_token: string; expires_in: number }> {
  const body = new URLSearchParams({
    grant_type:    'authorization_code',
    client_id:     clientId,
    client_secret: clientSecret,
    code,
    redirect_uri:  redirectUri,  // URLSearchParams encodes this automatically
  })

  const res = await fetch('https://oauth.provider.com/token', {
    method:  'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body:    body.toString(),
    // body: body — also works directly in modern environments (Fetch spec accepts URLSearchParams)
  })

  if (!res.ok) {
    const err = await res.json()
    throw new Error(`OAuth error: ${err.error_description ?? err.error}`)
  }

  return res.json()
}

Quando hai bisogno di testare o debuggare un URL codificato senza configurare uno script, incolla il valore grezzo direttamente nel Codificatore URL — codifica e decodifica istantaneamente, mostrandoti esattamente cosa vedranno il browser e il server. Utile per ispezionare URI di reindirizzamento OAuth, URL di callback di webhook e parametri di richieste firmate CDN.

Codifica URL da riga di comando con Node.js e Shell

Per script shell, pipeline CI, o debug rapido, diversi approcci da riga di comando funzionano senza scrivere uno script completo.

# ── Node.js one-liners — cross-platform (macOS, Linux, Windows) ────────

# encodeURIComponent — encode a single value
node -e "console.log(encodeURIComponent(process.argv[1]))" "Wireless Keyboard & Mouse"
# Wireless%20Keyboard%20%26%20Mouse

# Build a complete query string
node -e "console.log(new URLSearchParams(JSON.parse(process.argv[1])).toString())"   '{"q":"standing desk","category":"office-furniture","page":"1"}'
# q=standing+desk&category=office-furniture&page=1

# Decode a percent-encoded string
node -e "console.log(decodeURIComponent(process.argv[1]))" "Wireless%20Keyboard%20%26%20Mouse"
# Wireless Keyboard & Mouse

# ── curl — automatic encoding ───────────────────────────────────────────
# curl --data-urlencode encodes values automatically in GET and POST
curl -G "https://api.example.com/search"   --data-urlencode "q=Wireless Keyboard & Mouse"   --data-urlencode "category=office furniture"

# ── Python one-liner (available on most systems) ─────────────────────────
python3 -c "from urllib.parse import quote; print(quote(input(), safe=''))"
# (type the string and press Enter)

# ── jq + bash: encode every value in a JSON object ───────────────────────
echo '{"q":"hello world","tag":"node & express"}' |   node -e "const d=JSON.parse(require('fs').readFileSync('/dev/stdin','utf8'));            console.log(new URLSearchParams(d).toString())"
# q=hello+world&tag=node+%26+express

Alternativa ad alte prestazioni: qs

Il URLSearchParams nativo non supporta oggetti annidati o array — la forma di query string usata da molte API e framework. La libreria qs(oltre 30M di download settimanali su npm) gestisce l'intera gamma di pattern di query string usati nella pratica: oggetti annidati con notazione a parentesi quadre (filters[status]=active), chiavi ripetute, encoder personalizzati e formati di serializzazione degli array configurabili.

npm install qs
# or
pnpm add qs

import qs from 'qs'

// URLSearchParams cannot represent this structure natively
const reportFilters = {
  dateRange: {
    from: '2025-01-01',
    to:   '2025-03-31',
  },
  status:    ['published', 'archived'],
  author:    { id: 'usr_4f2a9c1b', role: 'editor' },
  workspace: 'ws-platform-eu',
}

// qs produces bracket-notation query strings used by Express, Rails, Django REST
const query = qs.stringify(reportFilters, { encode: true })
console.log(query)
// dateRange%5Bfrom%5D=2025-01-01&dateRange%5Bto%5D=2025-03-31&status%5B0%5D=published&status%5B1%5D=archived&author%5Bid%5D=usr_4f2a9c1b&author%5Brole%5D=editor&workspace=ws-platform-eu

// Human-readable (no encoding) — useful for debugging
console.log(qs.stringify(reportFilters, { encode: false }))
// dateRange[from]=2025-01-01&dateRange[to]=2025-03-31&status[0]=published&status[1]=archived...

// Parsing back
const parsed = qs.parse(query)
console.log(parsed.dateRange)   // { from: '2025-01-01', to: '2025-03-31' }
console.log(parsed.status)      // ['published', 'archived']

Per i parametri semplici chiave-valore, URLSearchParams è sempre la scelta giusta — è nativo, ha zero overhead ed è universalmente supportato. Ricorri a qs solo quando hai bisogno di strutture annidate, formati di serializzazione degli array diversi dalle chiavi ripetute, o quando ti stai integrando con un framework back-end che si aspetta query string in notazione a parentesi quadre.

Errori comuni

Ho visto questi quattro errori ripetutamente nelle basi di codice di produzione — la maggior parte sono fallimenti silenziosi che emergono solo quando un valore contiene un carattere speciale, che è esattamente il tipo di bug che sfugge ai test unitari e appare solo con dati reali degli utenti.

Errore 1 — Usare encodeURI() per i valori dei parametri di query

Problema: encodeURI() non codifica &, = né +. Quando un valore contiene questi caratteri, vengono interpretati come sintassi di query string, dividendo o sovrascrivendo silenziosamente i parametri. Soluzione: usa sempre encodeURIComponent() per i valori individuali.

// ❌ encodeURI does not encode & and = in the value
//    "plan=pro&promo=SAVE20" is treated as two separate params
const planName = 'Pro Plan (save=20% & free trial)'
const url = `/checkout?plan=${encodeURI(planName)}`
// /checkout?plan=Pro%20Plan%20(save=20%%20&%20free%20trial)
//                                          ↑ & breaks the query string

// ✅ encodeURIComponent encodes & and = safely
const planName = 'Pro Plan (save=20% & free trial)'
const url = `/checkout?plan=${encodeURIComponent(planName)}`
// /checkout?plan=Pro%20Plan%20(save%3D20%25%20%26%20free%20trial)
//                                   ↑ = and & are both encoded

Errore 2 — Doppia codifica di una stringa già codificata

Problema: Chiamare encodeURIComponent() su un valore già codificato in percentuale trasforma il % in %25, quindi %20 diventa %2520. Il server decodifica una volta e riceve un letterale %20 invece di uno spazio. Soluzione: decodifica prima, poi ricodifica, o assicurati che il valore non venga mai codificato due volte.

// ❌ encodedParam already contains %20 — encoding again produces %2520
const encodedParam  = 'Berlin%20Office'
const url = `/api/locations/${encodeURIComponent(encodedParam)}`
// /api/locations/Berlin%2520Office
// Server sees: "Berlin%20Office" (a literal percent-twenty, not a space)

// ✅ Decode first if the value may already be encoded
const maybeEncoded = 'Berlin%20Office'
const clean = decodeURIComponent(maybeEncoded)  // 'Berlin Office'
const url   = `/api/locations/${encodeURIComponent(clean)}`
// /api/locations/Berlin%20Office — correct

Errore 3 — Non considerare la differenza + / %20 tra URLSearchParams e encodeURIComponent

Problema: URLSearchParams codifica gli spazi come + (application/x-www-form-urlencoded), mentre encodeURIComponent() usa %20. Mescolare entrambi nello stesso URL — per esempio, aggiungere una stringa pre-codificata a un output di URLSearchParams — produce una codifica incoerente che confonde alcuni parser. Soluzione: scegli un approccio e usalo in modo coerente in tutta la funzione di costruzione dell'URL.

// ❌ Mixed: URLSearchParams uses + for spaces, but we're appending
//    a manually-encoded segment that uses %20
const base   = new URLSearchParams({ category: 'office furniture' })
const extra  = `sort=${encodeURIComponent('price asc')}`
const url    = `/api/products?${base}&${extra}`
// /api/products?category=office+furniture&sort=price%20asc
//              ↑ two different space encodings in the same URL

// ✅ Use URLSearchParams exclusively — consistent encoding throughout
const params = new URLSearchParams({
  category: 'office furniture',
  sort:     'price asc',
})
const url = `/api/products?${params}`
// /api/products?category=office+furniture&sort=price+asc

Errore 4 — Dimenticare di codificare i segmenti di percorso che contengono barre diagonali

Problema: Un identificatore di risorsa come un percorso file (reports/2025/q1.pdf) usato come segmento di percorso REST contiene caratteri / che il router del server interpreta come separatori di percorso, instradando verso un endpoint inesistente. Soluzione: usa sempre encodeURIComponent() per i segmenti di percorso che potrebbero contenere barre diagonali.

// ❌ The file path contains / — the server receives a 3-segment path
//    instead of a single resource ID
const filePath = 'reports/2025/q1-financials.pdf'
const url      = `https://storage.example.com/objects/${filePath}`
// https://storage.example.com/objects/reports/2025/q1-financials.pdf
// → Server routes to /objects/:year/:filename — 404 or wrong resource

// ✅ encodeURIComponent encodes / as %2F — single path segment
const filePath = 'reports/2025/q1-financials.pdf'
const url      = `https://storage.example.com/objects/${encodeURIComponent(filePath)}`
// https://storage.example.com/objects/reports%2F2025%2Fq1-financials.pdf
// → Server receives the full file path as one resource identifier

Metodi di codifica URL in JavaScript — Confronto rapido

Per la grande maggioranza dei casi, la scelta si riduce a tre scenari. Usa URLSearchParamsquando costruisci query string con più parametri da dati strutturati — è l'opzione più sicura e leggibile. Usa encodeURIComponent() per codificare un singolo valore in un URL con template literal, per i segmenti di percorso, o per i valori in sistemi che si aspettano %20 invece di + per gli spazi (come gli URL firmati di AWS S3). Ricorri a qs solo quando la tua query string contiene oggetti annidati o array che URLSearchParams non può rappresentare nativamente.

Domande frequenti

Strumenti correlati

Per codificare o decodificare con un clic senza scrivere codice, incolla la tua stringa direttamente nel Codificatore URL — gestisce la percent-encoding e la decodifica istantaneamente nel tuo browser, con l'output codificato pronto da copiare in una chiamata fetch o nel terminale.