path e url

node:path constrói caminhos de sistema de arquivos; node:url analisa e resolve URLs HTTP e file:// - confundi-los causa importações quebradas, redirecionamentos ruins e bugs SSRF.

Receita

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');

Quando usar:

• Resolvendo arquivos de configuração ao lado da saída compilada dist/
• Construindo URLs de API de saída com parâmetros de consulta
• Validando destinos de redirecionamento contra listas de permissões (prevenção de SSRF)
• Convertendo import.meta.url para caminho absoluto do sistema de arquivos

Exemplo de Trabalho

import path from 'node:path';
import { fileURLToPath, URL } from 'node:url';
 
// Equivalente a __dirname em ESM
const root = path.dirname(fileURLToPath(import.meta.url));
const dataFile = path.resolve(root, '..', 'data', 'users.json');
 
// URL da API com construção segura de consulta
function usersEndpoint(base: string, page: number): string {
  const url = new URL('/v1/users', base);
  url.searchParams.set('page', String(page));
  return url.href;
}
 
// Proteção SSRF - permita apenas https para host conhecido
function assertAllowedTarget(href: string, allowedHosts: Set<string>): URL {
  const parsed = new URL(href);
  if (parsed.protocol !== 'https:') throw new Error('https required');
  if (!allowedHosts.has(parsed.hostname)) throw new Error('host not allowed');
  return parsed;
}

O que isso demonstra:

• path.resolve e join evitam bugs de barra manual
• O construtor URL resolve caminhos relativos contra a URL base
• searchParams codifica strings de consulta corretamente
• Verificações SSRF inspecionam protocol e hostname antes de fetch

Mergulho Profundo

Como Funciona

• path é ciente da plataforma (internos win32 vs posix) - path.join escolhe os separadores.
• URL segue a especificação WHATWG - igual ao URL do navegador.
• fileURLToPath / pathToFileURL conectam URLs de arquivo e caminhos de sistema de arquivos.
• import.meta.resolve (experimental/estável por versão) resolve especificadores como importações.

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;
}

Armadilhas

• Usando path para URLs HTTP - perde semânticas de consulta/fragmento. Correção: URL para HTTP, path para disco.
• Travessia de caminho em path.join(base, userInput) - ../etc/passwd. Correção: resolver e verificar o prefixo sob a base.
• Assumindo que url.pathname é um caminho de sistema de arquivos no Windows - barra inicial semelhante a POSIX. Correção: fileURLToPath apenas para URLs file:.
• Barras duplas em concatenação manual de strings - redirecionamentos quebrados. Correção: new URL(relative, base).
• URLs IPv6 sem colchetes - falhas de análise. Correção: new URL lida com host entre colchetes http://[::1]:8080.

Alternativas

FAQs

Relacionado

• fs e fs/promises - abrir caminhos resolvidos
• Importação de Módulos ES - import.meta.url
• Proteções SSRF - validação de URL
• Noções Básicas de APIs Embutidas - visão geral

Versões do Stack: Esta página foi escrita para Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 e NestJS 11.