URL Encode JavaScript — encodeURIComponent()

Wenn du eine Such-URL erstellst, einen Weiterleitungspfad als Query-Parameter übergibst oder eine OAuth-Autorisierungsanfrage aufbaust, werden Sonderzeichen wie &, = und Leerzeichen die URL still und heimlich korrumpieren, sofern du sie nicht zuvor URL-kodierst. JavaScript bietet drei eingebaute Ansätze — encodeURIComponent(), encodeURI() und URLSearchParams — die jeweils für einen anderen Anwendungsfall konzipiert sind. Die falsche Wahl ist die häufigste Ursache der Kodierungsfehler, auf die ich in Code-Reviews gestoßen bin. Für schnelle Einzel-Kodierungen ohne Code erledigt der URL Encoder von ToolDeck das sofort im Browser. Dieser Leitfaden behandelt alle drei Ansätze ausführlich (JavaScript ES2015+ / Node.js 10+): wann welcher zu verwenden ist, wie sie sich bei Leerzeichen und reservierten Zeichen unterscheiden, praxisnahe Fetch- und API-Muster, CLI-Nutzung sowie die vier Fehler, die die meisten subtilen Produktionsprobleme verursachen.

Was ist URL-Kodierung?

URL-Kodierung (formal als Prozent-Kodierung bezeichnet, definiert in RFC 3986) wandelt Zeichen, die in einer URL nicht erlaubt sind oder eine besondere Bedeutung haben, in eine sichere Darstellung um. Jedes unsichere Byte wird durch ein Prozentzeichen gefolgt von zwei Hexadezimalziffern ersetzt — dem ASCII-Code des Zeichens. Ein Leerzeichen wird zu %20, ein kaufmännisches Und zu %26, ein Schrägstrich zu %2F.

Die Zeichen, die immer sicher sind und niemals kodiert werden, heißen nicht-reservierte Zeichen: Buchstaben A–Z und a–z, Ziffern 0–9 sowie die vier Symbole - _ . ~. Alles andere muss entweder kodiert werden, wenn es als Datenwert verwendet wird, oder hat eine strukturelle Rolle in der URL selbst (wie / zur Trennung von Pfadsegmenten oder &zur Trennung von Query-Parametern). Die praktische Konsequenz: Ein Produktname wie „Wireless Keyboard & Mouse" in einem Query-Parameter zerstört die URL-Struktur, wenn er unkodiert übergeben wird.

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() — Die richtige Funktion für Query-Parameter

encodeURIComponent() ist das Arbeitspferd der URL-Kodierung in JavaScript. Es kodiert jedes Zeichen außer den nicht-reservierten Zeichen (A–Z, a–z, 0–9, - _ . ! ~ * ' ( )). Entscheidend ist, dass es alle Zeichen kodiert, die in URLs eine strukturelle Bedeutung haben — &, =, ?, #, / — was es sicher für die Verwendung in Parameter-Werten macht. Es ist kein Import erforderlich; es handelt sich um eine globale Funktion, die in allen JavaScript-Umgebungen verfügbar ist.

Minimales Funktionsbeispiel

// 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

Eine Weiterleitungs-URL als Query-Parameter kodieren

// 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

Nicht-ASCII- und Unicode-Zeichen kodieren

// encodeURIComponent handles Unicode natively in all modern environments
// Each UTF-8 byte of the character is percent-encoded
const customerName = 'Müller, Sophie'
const productTitle = '東京 wireless adapter'
const reviewText   = 'Sehr gut — funktioniert einwandfrei'

console.log(encodeURIComponent(customerName))
// M%C3%BCller%2C%20Sophie

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

console.log(encodeURIComponent(reviewText))
// Sehr%20gut%20%E2%80%94%20funktioniert%20einwandfrei

// Decoding back
console.log(decodeURIComponent('M%C3%BCller%2C%20Sophie'))
// Müller, Sophie

JavaScript-URL-Kodierungsfunktionen — Zeichenreferenz

Die drei nativen Kodierungsansätze unterscheiden sich darin, welche Zeichen sie genau kodieren. Die folgende Tabelle zeigt die Ausgabe für die am häufigsten problematischen Zeichen:

Die entscheidende Spalte ist encodeURIComponent() vs. encodeURI() für & und =: encodeURI() lässt sie unverändert, was korrekt ist, wenn eine vollständige URL kodiert wird, aber katastrophal, wenn ein Wert mit diesen Zeichen kodiert werden soll.

encodeURI() — Wenn die URL-Struktur erhalten bleiben soll

encodeURI() ist für die Kodierung einer vollständigen URLvorgesehen — es bewahrt alle Zeichen, die gültige strukturelle Bestandteile einer URI sind: das Schema (https://), den Host, Pfadtrennzeichen, Query-Trennzeichen und den Fragment-Bezeichner. Verwende es, wenn du eine URL erhältst, die Leerzeichen oder Nicht-ASCII-Zeichen in Pfadsegmenten enthalten kann, deren Struktur jedoch intakt bleiben soll.

Eine benutzerseitig bereitgestellte URL bereinigen

// 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 — Der moderne Ansatz für Query-Strings

URLSearchParams ist der idiomatische Weg zum Erstellen und Parsen von Query-Strings in modernem JavaScript. Es ist global in allen modernen Browsern und Node.js 10+ verfügbar und behandelt die Kodierung automatisch — du arbeitest mit einfachen Schlüssel-Wert-Paaren und erhältst die korrekte Ausgabe. Ein wichtiges Detail: Es folgt der application/x-www-form-urlencoded-Spezifikation, die Leerzeichen als + statt %20 kodiert. Dies ist korrekt und weitgehend unterstützt, aber du solltest es im Hinterkopf behalten, wenn dein Server ein bestimmtes Format erwartet.

Eine Such-Anfrage-URL aufbauen

// 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

Einen eingehenden Query-String parsen

// 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']

URL-Parameter in JavaScript-Fetch-Anfragen kodieren

Der häufigste Ort, an dem URL-Kodierung in Produktionscode auftaucht, sind fetch()-Aufrufe — entweder beim Aufbau der Anfrage-URL oder beim Senden von Formulardaten im Anfrage-Body. Jedes Szenario hat seinen eigenen richtigen Ansatz.

GET-Anfrage — Query-Parameter kodieren

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`)

POST-Anfrage — einen Formular-Body URL-kodieren

// 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()
}

Wenn du eine kodierte URL ohne Script-Setup testen oder debuggen möchtest, füge den Rohwert direkt in den URL Encoder ein — er kodiert und dekodiert sofort und zeigt dir genau, was Browser und Server sehen werden. Nützlich für die Inspektion von OAuth-Weiterleitungs-URIs, Webhook-Callback-URLs und signierten CDN-Anfrageparametern.

URL-Kodierung über die Kommandozeile mit Node.js und Shell

Für Shell-Skripte, CI-Pipelines oder schnelles Debugging stehen mehrere Kommandozeilenansätze ohne vollständiges Skript zur Verfügung.

# ── 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

Hochleistungsalternative: qs

Das eingebaute URLSearchParams unterstützt keine verschachtelten Objekte oder Arrays — die Form von Query-Strings, die viele APIs und Frameworks verwenden. Die qs-Bibliothek (30M+ wöchentliche npm-Downloads) verarbeitet das gesamte Spektrum der in der Praxis vorkommenden Query-String-Muster: verschachtelte Objekte mit Klammernotation (filters[status]=active), wiederholte Schlüssel, benutzerdefinierte Encoder und konfigurierbare Array-Serialisierungsformate.

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']

Für flache Schlüssel-Wert-Parameter ist URLSearchParams immer die richtige Wahl — es ist eingebaut, hat keinen Overhead und wird universell unterstützt. Greife auf qs nur zurück, wenn du verschachtelte Strukturen, andere Array-Serialisierungsformate als wiederholte Schlüssel benötigst oder du dich in ein Backend-Framework integrierst, das Klammernotations-Query-Strings erwartet.

Häufige Fehler

Diese vier Fehler begegnen mir wiederholt in Produktionscode-Bases — die meisten sind stille Ausfälle, die erst dann auftauchen, wenn ein Wert ein Sonderzeichen enthält. Genau das ist die Art von Fehler, der durch Unit-Tests schlüpft und erst mit echten Benutzerdaten erscheint.

Fehler 1 — encodeURI() für Query-Parameter-Werte verwenden

Problem: encodeURI() kodiert &, = und + nicht. Wenn ein Wert diese Zeichen enthält, werden sie als Query-String-Syntax interpretiert und teilen oder überschreiben Parameter unbemerkt. Lösung: Verwende immer encodeURIComponent() für einzelne Werte.

// ❌ 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

Fehler 2 — Einen bereits kodierten String doppelt kodieren

Problem: encodeURIComponent() auf einem bereits prozent-kodierten Wert aufzurufen, wandelt das % in %25 um, sodass aus %20 %2520 wird. Der Server dekodiert einmal und erhält ein wörtliches %20 statt eines Leerzeichens. Lösung: Zuerst dekodieren, dann erneut kodieren, oder sicherstellen, dass der Wert nie zweimal kodiert wird.

// ❌ 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

Fehler 3 — Den + / %20-Unterschied zwischen URLSearchParams und encodeURIComponent nicht beachten

Problem: URLSearchParams kodiert Leerzeichen als + (application/x-www-form-urlencoded), während encodeURIComponent() %20 verwendet. Beide in derselben URL zu mischen — beispielsweise einen vorkkodierten String an eine URLSearchParams-Ausgabe anzuhängen — erzeugt inkonsistente Kodierung, die manche Parser verwirrt. Lösung: Wähle einen Ansatz und verwende ihn konsequent in der gesamten URL-Aufbaufunktion.

// ❌ 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

Fehler 4 — Vergessen, Pfadsegmente mit Schrägstrichen zu kodieren

Problem: Ein Ressourcenbezeichner wie ein Dateipfad (reports/2025/q1.pdf) als REST-Pfadsegment enthält /-Zeichen, die der Server-Router als Pfadtrennzeichen interpretiert und zu einem nicht existierenden Endpunkt weiterleitet. Lösung: Verwende immer encodeURIComponent() für Pfadsegmente, die Schrägstriche enthalten können.

// ❌ 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

JavaScript-URL-Kodierungsmethoden — Kurzübersicht

In den allermeisten Fällen reduziert sich die Wahl auf drei Szenarien. Verwende URLSearchParams beim Aufbau von Multi-Parameter-Query-Strings aus strukturierten Daten — es ist die sicherste und lesbarste Option. Verwende encodeURIComponent() zum Kodieren eines einzelnen Werts in einer Template-Literal-URL, für Pfadsegmente oder für Werte in Systemen, die %20 statt + für Leerzeichen erwarten (wie AWS S3 Signed URLs). Greife auf qs nur zurück, wenn dein Query-String verschachtelte Objekte oder Arrays enthält, die URLSearchParams nicht nativ darstellen kann.

Häufig gestellte Fragen

Verwandte Tools

Für eine Ein-Klick-Kodierung oder -Dekodierung ohne Code füge deine Zeichenkette direkt in den URL Encoder ein — er verarbeitet Prozent-Kodierung und -Dekodierung sofort in deinem Browser, mit der kodierten Ausgabe bereit zum Einfügen in einen Fetch-Aufruf oder ein Terminal.