Tutoriales de VPS
404 al recargar Vue o React en Nginx: rutas, recursos y try_files
Si funciona la página principal pero falla una ruta profunda, separa páginas SPA, recursos y API. Configura el fallback y diagnostica JS que recibe HTML o bases de subdirectorio incorrectas.

La página principal de Vue o React carga y navegar desde el menú a /dashboard funciona, pero recargar esa URL devuelve un 404 de Nginx. Normalmente el navegador y el servidor están interpretando la ruta de forma distinta. Otro fallo frecuente es recibir HTML con estado 200 donde se esperaba JavaScript, dejando la página en blanco.
Esta guía se aplica a una SPA estática ya compilada y servida por Nginx. Revisa peticiones, archivos y reglas antes de añadir un fallback para páginas. Separa APIs y recursos estáticos. Una aplicación Next.js o Nuxt con renderizado de servidor necesita otra configuración.
Abre Network en las herramientas del navegador, recarga la página y revisa por separado documento, JS/CSS y API. El texto del error visible no basta para decidir qué cambiar.
| Resultado | Primera comprobación | Tratamiento correcto |
|---|---|---|
El documento /dashboard devuelve 404, pero navegar dentro funciona | Fallback de History | Entregar el HTML de entrada para que el frontend resuelva la ruta |
/assets/app-xxx.js devuelve 404 | Compilación, ruta de recursos y caché antigua | Servir el archivo real, no la página principal como JS |
| JS responde 200 con HTML | El fallback captura recursos | Devolver un 404 real si falta el archivo |
/api/users devuelve la página principal | La regla de páginas captura la API | Restaurar su ruta o proxy independiente |
La guía de History de Vue Router explica la diferencia: la navegación interna la maneja el navegador, mientras una visita directa a una URL profunda necesita el documento de entrada. Entregarlo no demuestra que exista la ruta en el frontend.
Con la salida predeterminada de Vite, ejecuta la compilación del proyecto y confirma que se subieron dist/index.html y todos los recursos referenciados. La documentación de despliegue de Vite establece dist como directorio predeterminado; vite preview sirve para previsualización local, no para producción.
Supongamos los archivos en /srv/www/app/dist y el dominio app.example.com. Inspecciona archivos y configuración efectiva:
sudo nginx -T
ls -l /srv/www/app/dist/index.html
ls -l /srv/www/app/dist/assets/
Comprueba el server_name coincidente, el sitio HTTP/HTTPS y root. Un panel como Baota o 1Panel puede generar la configuración y sobrescribir cambios manuales. La salida de nginx -T puede contener direcciones internas; elimínalas antes de compartirla.
Revisa mayúsculas y minúsculas: que Logo.png funcione localmente no significa que Linux lo sirva como logo.png. Si Nginx está en un contenedor, inspecciona los archivos que ve dentro; su existencia en el host no confirma el montaje. Consulta datos y montajes de Compose.
Este ejemplo HTTP corresponde a un dominio independiente en la raíz, sin API backend. En HTTPS, integra las reglas en el server existente y conserva certificados. Si ya hay API, mantén sus reglas reales; no las sustituyas por el 404 de ejemplo.
server {
listen 80;
server_name app.example.com;
root /srv/www/app/dist;
index index.html;
location = /index.html {
try_files $uri =404;
add_header Cache-Control "no-cache" always;
}
location ^~ /assets/ {
try_files $uri =404;
}
location ^~ /static/ {
try_files $uri =404;
}
location = /api {
return 404;
}
location ^~ /api/ {
return 404;
}
location / {
try_files $uri $uri/ /index.html;
}
}
Cuando /dashboard no encuentra un archivo, redirige internamente a /index.html. La regla separada del archivo de entrada devuelve 404 si también falta, evitando redirecciones internas repetidas. no-cache permite almacenar caché, pero exige revalidar antes de reutilizar; no prohíbe totalmente la caché.
/assets/ y /static/ son directorios habituales de recursos. Añade reglas propias para cualquier otro que utilice tu compilación; de lo contrario un JS ausente puede caer en el fallback. Un error_page 404 /index.html global puede ocultar archivos ausentes, errores de API y rutas incorrectas.
try_files comprueba archivos según su mapeo; la URI final es el fallback. root concatena la URI al directorio, como explica la referencia de Nginx. Por ejemplo, /assets/app.js bajo root /srv/www/app/dist corresponde a /srv/www/app/dist/assets/app.js.
alias sustituye el prefijo coincidente y calcula otra ruta. No intercambies root y alias para eliminar un 404 sin comprobar qué archivo intenta abrir Nginx. Permission denied señala un problema de permisos de lectura; otro fallback no lo soluciona.
Ante “Expected a JavaScript module … MIME type text/html” o Unexpected token '<', abre Response en la petición fallida. Si empieza por <!doctype html>, normalmente es la página principal o un error HTML.
Una vez comprobados ruta, archivo y estado, verifica que el contexto http carga el mime.types de esa instalación. No fuerces JavaScript como tipo predeterminado de todo el sitio: HTML, CSS y otros archivos quedarían mal tipados.
Después de publicar, un HTML antiguo puede referenciar recursos con hash ya eliminados. Cambia los archivos como una versión completa, conserva los antiguos el tiempo necesario y revisa cachés del navegador, Service Worker y CDN. Cambiar cabeceras no recrea un archivo inexistente.
Con CDN, compara primero estado, Content-Type y cuerpo entre origen y borde. Limpia las URLs afectadas cuando el origen sea correcto y el borde conserve resultados antiguos. No atribuyas todos los 404 al CDN ni desactives la verificación de certificados para esconder errores HTTPS.
Si la URL es https://example.com/app/, no basta cambiar la location de Nginx a /app/. El base de recursos de Vite, la base del router, los directorios y el fallback deben coincidir con ese prefijo.
Una página en /app/ que pide /assets/app.js puede llevar al servidor a buscar en la raíz del sitio principal. Configura las bases según las herramientas, recompila y comprueba las URLs del HTML generado. El ejemplo de despliegue en raíz no sirve sin adaptación para un subdirectorio.
Una página SPA desconocida puede recibir HTTP 200. El frontend debe mostrar su propia página de no encontrado. Si necesitas un HTTP 404 exacto para buscadores, usa una solución que determine las rutas en el servidor en lugar de tratar todas las URLs como válidas.
Respalda la configuración, valida la sintaxis y recarga. Si falla, conserva la versión que está funcionando; consulta fallos de configuración y reload de Nginx.
sudo nginx -t && sudo systemctl reload nginx
curl -i https://app.example.com/dashboard
curl -i https://app.example.com/assets/not-a-real-file.js
curl -i https://app.example.com/api/not-a-real-endpoint
Las páginas profundas deben recibir el HTML de entrada y los JS ausentes un 404. Una API real debe devolver JSON, un error de autenticación o su propio 404 según sus reglas, nunca la página del frontend. Recarga también en el navegador y verifica scripts, login y carga de datos.
El artículo original registra 10 comprobaciones aisladas con Nginx 1.19.6 en loopback: 200 en páginas profundas, tipos JS/CSS correctos, 404 para recursos ausentes y API de ejemplo, y 404 sin bucle al eliminar el HTML de entrada. Esa versión local no se recomienda para instalar en producción. Las pruebas no cubren ejecución real del frontend, TLS, CDN, Service Worker ni autenticación de la aplicación.