path y url

node:path construye rutas del sistema de archivos; node:url analiza y resuelve URLs HTTP y file:// - confundirlos causa importaciones rotas, redirecciones incorrectas y errores SSRF.

Receta

import path from 'node:path';
import { fileURLToPath } from 'node:url';
 
const dir = path.dirname(fileURLToPath(import.meta.url));
const config = path.join(dir, 'config.json');

import { URL } from 'node:url';
 
const u = new URL('https://api.example.com/v1/users?page=2');
u.searchParams.set('limit', '50');

Cuándo usarlo:

• Resolver archivos de configuración junto a la salida dist/ compilada
• Construir URLs de API salientes con parámetros de consulta
• Validar objetivos de redirección contra listas de permitidos (prevención de SSRF)
• Convertir import.meta.url a una ruta de sistema de archivos absoluta

Ejemplo de trabajo

import path from 'node:path';
import { fileURLToPath, URL } from 'node:url';
 
// Equivalente a __dirname en ESM
const root = path.dirname(fileURLToPath(import.meta.url));
const dataFile = path.resolve(root, '..', 'data', 'users.json');
 
// URL de API con construcción segura de consultas
function usersEndpoint(base: string, page: number): string {
  const url = new URL('/v1/users', base);
  url.searchParams.set('page', String(page));
  return url.href;
}
 
// Protección SSRF - solo permite https a un host conocido
function assertAllowedTarget(href: string, allowedHosts: Set<string>): URL {
  const parsed = new URL(href);
  if (parsed.protocol !== 'https:') throw new Error('https requerido');
  if (!allowedHosts.has(parsed.hostname)) throw new Error('host no permitido');
  return parsed;
}

Lo que esto demuestra:

• path.resolve y join previenen errores manuales de barras
• El constructor URL resuelve rutas relativas contra una URL base
• searchParams codifica las cadenas de consulta correctamente
• Las comprobaciones SSRF inspeccionan protocol y hostname antes de fetch

Análisis profundo

Cómo funciona

• path es consciente de la plataforma (internos win32 vs posix) - path.join elige separadores.
• URL sigue la especificación WHATWG - igual que URL del navegador.
• fileURLToPath / pathToFileURL conectan URLs de archivo y rutas del sistema de archivos.
• import.meta.resolve (experimental/estable según la versión) resuelve especificadores como import.

path vs URL

Notas de TypeScript

import path from 'node:path';
 
export function safeJoin(base: string, userSegment: string): string {
  const resolved = path.resolve(base, userSegment);
  if (!resolved.startsWith(path.resolve(base))) {
    throw new Error('path traversal');
  }
  return resolved;
}

Errores comunes

• Usar path para URLs HTTP - pierde la semántica de consulta/fragmento. Solución: URL para HTTP, path para disco.
• Recorrido de ruta en path.join(base, userInput) - ../etc/passwd. Solución: resolver y verificar el prefijo bajo la base.
• Asumir que url.pathname es una ruta del sistema de archivos en Windows - barra inicial tipo POSIX. Solución: fileURLToPath solo para URLs file:.
• Barras dobles en la concatenación manual de cadenas - redirecciones rotas. Solución: new URL(relative, base).
• URLs IPv6 sin corchetes - fallos de análisis. Solución: new URL maneja el host entre corchetes http://[::1]:8080.

Alternativas

Preguntas frecuentes

Relacionado

• fs y fs/promises - abrir rutas resueltas
• Importación de módulos ES - import.meta.url
• Guardias SSRF - validación de URL
• Conceptos básicos de las API integradas - resumen

Versiones de la 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.