Codificaciones de texto

El texto en la red son bytes. UTF-8 es el predeterminado para las API de Node 24, y TextEncoder/TextDecoder proporcionan una conversión estándar web con manejo explícito de errores para entradas malformadas.

Receta

const encoder = new TextEncoder(); // siempre UTF-8
const decoder = new TextDecoder('utf-8', { fatal: true });
 
const bytes = encoder.encode('Hello 世界');
const text = decoder.decode(bytes);

const buf = Buffer.from('café', 'utf8');
console.log(buf.toString('utf8'));

Cuándo usarlo:

• Analizar nombres de archivo subidos con caracteres no ASCII
• Convertir bytes de respuesta de fetch a cadenas
• Validar CSV/XML declarados como UTF-8 de terceros
• Interoperar con TextEncoder del navegador en código isomorfo

Ejemplo de trabajo

import { Buffer } from 'node:buffer';
 
function decodeUtf8Strict(bytes: Uint8Array): string {
  const decoder = new TextDecoder('utf-8', { fatal: true });
  try {
    return decoder.decode(bytes);
  } catch {
    throw new Error('Invalid UTF-8 sequence');
  }
}
 
function decodeUtf8Lossy(bytes: Uint8Array): string {
  return new TextDecoder('utf-8', { fatal: false }).decode(bytes);
}
 
const valid = Buffer.from('hello', 'utf8');
const invalid = Buffer.from([0xff, 0xfe, 0xfd]);
 
console.log(decodeUtf8Strict(valid));
console.log(decodeUtf8Lossy(invalid)); // caracteres de reemplazo

// HTTP Content-Type debe especificar charset=utf-8
const encoder = new TextEncoder();
const body = encoder.encode(JSON.stringify({ greeting: '你好' }));

Lo que esto demuestra:

• fatal: true rechaza secuencias incorrectas, adecuado para analizadores sensibles a la seguridad
• fatal: false sustituye U+FFFD, aceptable para visualización generada por el usuario con advertencias
• TextEncoder solo admite UTF-8 según la especificación; usa iconv-lite para codificaciones heredadas
• Buffer.toString('utf8') reemplaza los bytes inválidos por defecto, similar al decodificador no fatal

Inmersión profunda

Cómo funciona

• Las cadenas de JavaScript son UTF-16 internamente; UTF-8 es la codificación de intercambio para E/S.
• BOM - El BOM de UTF-8 (EF BB BF) es opcional; elimínalo al analizar JSON que debe comenzar con {.
• Normalización - NFC vs NFD importa para la comparación de cadenas (nombres de usuario, nombres de archivo).
• Codificaciones de Buffer - hex, base64, base64url, latin1 para protocolos específicos, no para texto general.

Selección de codificación

Notas de TypeScript

function assertUtf8Json(raw: Buffer): unknown {
  const text = new TextDecoder('utf-8', { fatal: true }).decode(raw);
  return JSON.parse(text);
}

Errores comunes

• Asumir que el modo de cadena binary conserva los bytes - un error heredado. Solución: usa Buffer o Uint8Array para binarios.
• Doble codificación UTF-8 - codificar cadenas ya válidas por "seguridad". Solución: codifica una vez en el límite del sistema.
• Ignorar el juego de caracteres en Content-Type - valores predeterminados ISO-8859-1 en clientes antiguos. Solución: fuerza UTF-8 de principio a fin.
• Codificación de nombres de archivo en multipart - RFC 5987 filename* codificación de porcentaje UTF-8. Solución: usa analizadores de framework probados para i18n.
• Comparar Unicode no normalizado - nombres de usuario visualmente idénticos difieren a nivel de byte. Solución: str.normalize('NFC') antes de comparar.

Alternativas

Preguntas frecuentes

Relacionado

• Conceptos básicos de Buffers - asignación y segmentos
• Protocolos binarios - cargas útiles no textuales
• Seguridad de Buffer - fugas en mensajes de error
• Respuestas HTTP en streaming - encabezados de juego de caracteres

Versiones de pila: Esta página fue escrita para Node.js 24.18.0 (LTS activa), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 y NestJS 11.