Puerto 5173 de Vite ocupado: por qué normalmente se cambia solo, y qué hacer cuando no debería

Vite se comporta distinto a la mayoría de los servidores de desarrollo cuando su puerto está tomado, y esa diferencia es la fuente de un tipo de confusión muy específico.

Vite no falla, se mueve

Levanta Vite mientras otra cosa ocupa el 5173 y obtienes un aviso en vez de un error:

Port 5173 is in use, trying another one...
➜  Local:   http://localhost:5174/

Eso es a propósito y normalmente es cómodo. También es la razón por la que la gente termina con una pestaña del navegador en el 5173 mostrando un build viejo mientras el servidor que acaba de levantar responde en el 5174, editando archivos que nunca aparecen.

Si estás mirando cambios que no se reflejan, revisa el puerto en tu terminal antes que cualquier otra cosa. Es la causa más común por lejos.

Haz que falle, con strictPort

Cuando el puerto importa, un callback de OAuth, una lista de CORS, una configuración de proxy, un marcador de un compañero, moverse en silencio es peor que fallar. Dile a Vite que insista:

// vite.config.js
export default {
  server: {
    port: 5173,
    strictPort: true,
  },
}

Con strictPort: true, Vite sale con error en vez de andar buscando otro puerto. Eso convierte un síntoma confuso en uno claro, que casi siempre es el mejor intercambio en un proyecto con URLs fijas.

Encontrar qué ocupa realmente el 5173

Ahora necesitas al culpable. Pregúntale directo al puerto:

lsof -i :5173

Y después termínalo:

lsof -ti :5173 | xargs kill

-t imprime solo los IDs de proceso, y xargs se los pasa todos a un solo kill. Un kill sin argumentos manda SIGTERM, que le permite al proceso cerrar bien. Agrega -9 solo si se niega a salir.

Por qué casi siempre es tu propio Vite

Nueve de cada diez veces el proceso que ocupa el 5173 es otro Vite del mismo proyecto. Los caminos habituales para llegar ahí:

Cerraste la terminal en vez de detener el servidor. Ctrl+C manda SIGTERM y Vite suelta el puerto. Cerrar la ventana puede dejarlo huérfano.

Tu editor lo está corriendo. La terminal integrada de VS Code, o una configuración de ejecución, puede mantener vivo un servidor en un panel que no estás mirando. En algunas configuraciones incluso sobrevive a cerrar la carpeta.

Dos proyectos, el mismo default. Vite usa el 5173 por defecto en todos los proyectos, así que un segundo clon choca con el primero por diseño.

Cuando el 5174 también está ocupado

Si Vite sigue subiendo, 5174, 5175, 5176, probablemente tienes varios servidores huérfanos apilados y no uno solo. Mira todo el vecindario de una vez:

lsof -i -P -n -sTCP:LISTEN | grep -E ':517[0-9]'

Si eso devuelve cuatro procesos node, casi con certeza son todos tuyos. Limpiarlos es el mismo comando aplicado al rango, o puerto por puerto.

Evitar que se repita

Dale a cada proyecto su propio puerto en vite.config.js en vez de confiar en el default. Un proyecto en 5173, otro en 5273, otro en 5373, y los choques dejan de ser algo diario. Combínalo con strictPort: true y un conflicto se convierte en un error claro al arrancar en vez de un cambio silencioso.

Lectura relacionada: qué significa realmente EADDRINUSE, que explica el caso donde un puerto está ocupado sin que haya proceso que matar.

Bosun muestra cada puerto escuchando en tu barra de menú con el proceso detrás, así un servidor perdido es visible antes de que te cueste veinte minutos. macOS 14 o posterior, prueba de 14 días.