¿Qué hace Diagnóstico de Navegación en SwiftUI?
Resumen
Principio fundamental El 85 % de los problemas de navegación provienen de errores en la gestión del estado de la ruta, problemas de identidad de vistas o errores de colocación, no de defectos de SwiftUI.
El sistema de navegación de SwiftUI es utilizado por millones de aplicaciones y maneja patrones de navegación complejos de manera confiable. Si tu navegación falla, no responde o se comporta inesperadamente, el problema casi siempre está en cómo gestionas el estado de navegación, no en el framework en sí.
Esta habilidad proporciona diagnósticos sistemáticos para identificar las causas raíz en minutos, no en horas.
Señales de Alerta — Sospecha de Problema de Navegación
Si ves CUALQUIERA de estos signos, sospecha un problema de código, no una falla del framework:
-
Tocar un enlace de navegación no hace nada (el enlace está presente pero no empuja)
-
El botón de retroceso vuelve a la pantalla o raíz incorrecta
-
Un deep link abre la aplicación pero muestra la pantalla incorrecta
-
El estado de navegación se pierde al cambiar de pestaña
-
El estado de navegación se pierde cuando la aplicación va al fondo
-
El mismo NavigationLink empuja dos veces
-
La animación de navegación se atasca o se entrecorta
-
Crash con
navigationDestinationen el stack trace -
❌ PROHIBIDO "La navegación de SwiftUI está rota, vamos a envolverla con UINavigationController"
- NavigationStack es utilizado por las propias aplicaciones de Apple
- Envolver UIKit añade complejidad y pierde los beneficios de la gestión de estado de SwiftUI
- La interoperabilidad con UIKit tiene sus propios casos extremos en los que pasarás semanas descubriéndolos
- Tu problema es casi con certeza de gestión de rutas, no un defecto del framework
Distinción crítica El comportamiento de NavigationStack es determinista. Si no funciona, estás modificando el estado incorrectamente, tienes problemas de identidad de vistas, o navigationDestination está mal ubicado.
Pasos Obligatorios Iniciales
SIEMPRE ejecuta estas comprobaciones PRIMERO (antes de cambiar código):
// 1. Añade registro de NavigationPath
NavigationStack(path: $path) {
RootView()
.onChange(of: path.count) { oldCount, newCount in
print("📍 Ruta cambiada: \(oldCount) → \(newCount)")
// Si esto nunca se dispara, el enlace no está modificando la ruta
// Si se dispara inesperadamente, algo más está modificando la ruta
}
}
// 2. Verifica que navigationDestination sea visible
// Pon un print temporal en el cierre de destino
.navigationDestination(for: Recipe.self) { recipe in
let _ = print("🔗 Destino para Recipe: \(recipe.name)")
RecipeDetail(recipe: recipe)
}
// Si esto nunca imprime, el destino no se está evaluando
// 3. Verifica que NavigationLink esté dentro de NavigationStack
// Inspección visual: Rastrea desde NavigationLink hacia arriba en la jerarquía de vistas
// Debe topar con NavigationStack, no con otro contenedor primero
// 4. Verifica la ubicación del estado de ruta
// @State debe estar en una vista estable (no recreada en cada renderizado)
// Debe ser @State, @StateObject o @Observable — no una variable local
// 5. Prueba el caso básico de forma aislada
// Crea una reproducción mínima
NavigationStack {
NavigationLink("Prueba", value: "test")
.navigationDestination(for: String.self) { str in
Text("Empujado: \(str)")
}
}
// Si esto funciona, el problema está en tu configuración específica
Qué te dice esto
| Observación | Diagnóstico | Siguiente Paso |
|---|---|---|
| onChange nunca se dispara al tocar | NavigationLink no está en la jerarquía de NavigationStack | Patrón 1a |
| onChange se dispara pero la vista no se empuja | navigationDestination no encontrado/cargado | Patrón 1b |
| onChange se dispara, la vista se empuja, luego retroceso inmediato | Problema de identidad de vista o modificación de ruta | Patrón 2a |
| La ruta cambia inesperadamente (no por toque) | Código externo modificando la ruta | Patrón 2b |
| path.append() de deep link no navega | Problema de sincronización o hilo incorrecto | Patrón 3b |
| Estado perdido al cambiar de pestaña | NavigationStack compartido entre pestañas | Patrón 4a |
| Funciona la primera vez, falla al regresar | Problema de recreación de vista | Patrón 5a |
INTERPRETACIÓN OBLIGATORIA
Antes de cambiar CUALQUIER código, identifica UNO de estos:
- Si tocar el enlace no hace nada Y no hay onChange → Enlace fuera de NavigationStack (verifica jerarquía)
- Si onChange se dispara pero nada se empuja → navigationDestination no está en alcance (verifica ubicación)
- Si se empuja y luego retrocede inmediatamente → Cambio de identidad de vista o reinicio de ruta (verifica ubicación de @State)
- Si el deep link falla → Problema de sincronización o MainActor (verifica hilo)
- Si hay crash → Force unwrap en decodificación de ruta o registro de tipo faltante
Si los diagnósticos son contradictorios o poco claros
- DETENTE. No procedas a los patrones todavía
- Añade sentencias print en cada punto de modificación de ruta
- Crea un caso de reproducción mínima
- Prueba primero con valores String (el caso más simple)
Árbol de Decisión
Usa esto para llegar al patrón de diagnóstico correcto en 2 minutos:
¿Problema de navegación?
├─ ¿Tocar el enlace de navegación no hace nada?
│ ├─ ¿NavigationLink dentro de NavigationStack?
│ │ ├─ No → Patrón 1a (Enlace fuera del Stack)
│ │ └─ Sí → Verificar navigationDestination
│ │
│ ├─ ¿navigationDestination registrado?
│ │ ├─ ¿Dentro de contenedor perezoso? → Patrón 1b (Carga Perezosa)
│ │ ├─ ¿Discrepancia de tipos? → Patrón 1c (Registro de Tipo)
│ │ └─ ¿Bloqueado por sheet/popover? → Patrón 1d (Bloqueo Modal)
│ │
│ └─ ¿Usando enlace basado en vista?
│ └─ → Patrón 1e (API Obsoleta)
│
├─ ¿Retroceso inesperado?
│ ├─ ¿Retroceso inmediato después de empujar?
│ │ ├─ ¿El body de la vista recrea la ruta? → Patrón 2a (Recreación de Ruta)
│ │ ├─ ¿@State en vista incorrecta? → Patrón 2a (Ubicación de Estado)
│ │ └─ ¿Cambia el id de ForEach? → Patrón 2c (Cambio de Identidad)
│ │
│ ├─ ¿Retroceso cuando no debería?
│ │ ├─ ¿Código externo llamando a removeLast? → Patrón 2b (Modificación Inesperada)
│ │ ├─ ¿Tarea cancelada? → Patrón 2b (Cancelación Asíncrona)
│ │ └─ ¿Problema de MainActor? → Patrón 2d (Hilos)
│ │
│ └─ ¿Comportamiento incorrecto del botón de retroceso?
│ └─ → Patrón 2e (Corrupción del Stack)
│
├─ ¿Deep link no funciona?
│ ├─ ¿URL no recibida?
│ │ ├─ ¿onOpenURL no llamado? → Verificar esquema de URL en Info.plist
│ │ └─ ¿Problema de Universal Links? → Verificar apple-app-site-association
│ │
│ ├─ ¿URL recibida, ruta no actualizada?
│ │ ├─ ¿path.append no está en MainActor? → Patrón 3a (Hilos)
│ │ ├─ ¿Problema de sincronización (app no lista)? → Patrón 3b (Inicialización)
│ │ └─ ¿NavigationStack aún no creado? → Patrón 3b (Ciclo de Vida)
│ │
│ └─ ¿Ruta actualizada, pantalla incorrecta mostrada?
│ ├─ ¿Orden de ruta incorrecto? → Patrón 3c (Construcción de Ruta)
│ ├─ ¿Tipo incorrecto añadido? → Patrón 3c (Discrepancia de Tipo)
│ └─ ¿Elemento no encontrado? → Patrón 3d (Resolución de Datos)
│
├─ ¿Estado perdido?
│ ├─ ¿Perdido al cambiar de pestaña?
│ │ ├─ ¿NavigationStack compartido? → Patrón 4a (Estado Compartido)
│ │ └─ ¿Recreación de pestaña? → Patrón 4a (Identidad de Pestaña)
│ │
│ ├─ ¿Perdido al ir al fondo/volver al primer plano?
│ │ ├─ ¿Sin SceneStorage? → Patrón 4b (Sin Persistencia)
│ │ └─ ¿Fallo de decodificación? → Patrón 4c (Error de Decodificación)
│ │
│ └─ ¿Perdido al rotar/cambiar tamaño?
│ └─ → Patrón 4d (Recreación de Layout)
│
├─ ¿Problema con NavigationSplitView?
│ ├─ ¿Barra lateral no visible en iPad?
│ │ ├─ ¿columnVisibility no configurado? → Patrón 6a (Visibilidad de Columna)
│ │ └─ ¿Clase de tamaño compacta? → Patrón 6a (Adaptación Automática)
│ │
│ ├─ ¿Detalle muestra en blanco en iPad?
│ │ ├─ ¿Sin vista de detalle predeterminada? → Patrón 6b (Detalle Faltante)
│ │ └─ ¿Enlace de selección nil? → Patrón 6b (Estado de Selección)
│ │
│ └─ ¿Funciona en iPhone, roto en iPad?
│ └─ → Patrón 6c (Adaptación de Plataforma)
│
└─ ¿Crash?
├─ ¿EXC_BAD_ACCESS en código de navegación?
│ └─ → Patrón 5a (Problema de Memoria)
│
├─ ¿Error fatal: tipo no registrado?
│ └─ → Patrón 5b (Destino Faltante)
│
└─ ¿Fallo de decodificación al restaurar?
└─ → Patrón 5c (Crash de Restauración)
Reglas de Selección de Patrones (OBLIGATORIO)
Antes de proceder a un patrón:
- Tocar el enlace de navegación no hace nada → Añade registro onChange PRIMERO, luego Patrón 1
- Retroceso inesperado → Encuentra QUÉ está modificando la ruta (registro), luego Patrón 2
- Falla el deep link → Verifica que la URL fue recibida (print en onOpenURL), luego Patrón 3
- Estado perdido → Identifica CUÁNDO se pierde (cambio de pestaña vs. fondo), luego Patrón 4
- Crash → Obtén el stack trace completo, luego Patrón 5
Aplica UN patrón a la vez
- Implementa la corrección de un patrón
- Prueba a fondo
- Solo si el problema persiste, prueba el siguiente patrón
- NO apliques múltiples patrones simultáneamente (no se puede aislar la causa)
PROHIBIDO
- Adivinar soluciones sin diagnóstico
- Cambiar varias cosas a la vez
- Envolver con UINavigationController "porque SwiftUI está roto"
- Añadir retrasos/DispatchQueue.main.async sin entender por qué
- Cambiar a NavigationLink basado en vista "para evitar problemas de ruta"
Patrones de Diagnóstico
Patrón 1a: NavigationLink Fuera de NavigationStack
Costo de tiempo 5-10 minutos
Síntoma
- Tocar NavigationLink no hace nada
- No ocurre navegación, no hay errores
- onChange(of: path) nunca se dispara
Diagnóstico
// Verificar jerarquía de vistas — NavigationLink debe estar DENTRO de NavigationStack
// ❌ INCORRECTO — Enlace fuera del stack
struct ContentView: View {
var body: some View {
VStack {
NavigationLink("Ir", value: "test") // ¡Fuera del stack!
NavigationStack {
Text("Raíz")
}
}
}
}
// Verificar: Añade color de fondo a NavigationStack
NavigationStack {
Color.red // Si el enlace está sobre rojo, está dentro
}
Corrección
// ✅ CORRECTO — Enlace dentro del stack
struct ContentView: View {
var body: some View {
NavigationStack {
VStack {
NavigationLink("Ir", value: "test") // Dentro del stack
Text("Raíz")
}
.navigationDestination(for: String.self) { str in
Text("Empujado: \(str)")
}
}
}
}
Verificación
- Toca el enlace, la navegación ocurre
- onChange(of: path) se dispara al tocar
Patrón 1b: navigationDestination en Contenedor Perezoso
Costo de tiempo 10-15 minutos
Síntoma
- Tocar NavigationLink no hace nada O funciona de forma intermitente
- onChange se dispara (ruta actualizada) pero la vista no se empuja
- La consola puede mostrar: "A navigationDestination for [Type] was not found"
Diagnóstico
// ❌ INCORRECTO — Destino dentro de contenedor perezoso (puede no cargarse)
ScrollView {
LazyVStack {
ForEach(items) { item in
NavigationLink(item.name, value: item)
.navigationDestination(for: Item.self) { item in
ItemDetail(item: item) // ¡Puede no evaluarse!
}
}
}
}
Corrección
// ✅ CORRECTO — Destino fuera del contenedor perezoso
ScrollView {
LazyVStack {
ForEach(items) { item in
NavigationLink(item.name, value: item)
}
}
}
.navigationDestination(for: Item.self) { item in
ItemDetail(item: item) // Siempre disponible
}
Verificación
- Añade print en el cierre de destino — debería imprimir siempre al navegar
- Funciona independientemente de la posición de desplazamiento
Patrón 1c: Discrepancia en el Registro de Tipo
Costo de tiempo 10 minutos
Síntoma
- Tocar navegación no hace nada
- No hay navigationDestination que coincida con el tipo del valor
- Puede funcionar para algunos enlaces, pero no para otros
Diagnóstico
// Verificar: El tipo del valor debe coincidir EXACTAMENTE con el tipo del destino
// El enlace usa Recipe
NavigationLink(recipe.name, value: recipe) // el valor es Recipe
// El destino está registrado para... ¿Recipe.ID?
.navigationDestination(for: Recipe.ID.self) { id in // ❌ Tipo incorrecto!
RecipeDetail(id: id)
}
Corrección
// Coincide exactamente los tipos
NavigationLink(recipe.name, value: recipe) // Recipe
.navigationDestination(for: Recipe.self) { recipe in // ✅ Recipe
RecipeDetail(recipe: recipe)
}
// O cambia el enlace para usar ID
NavigationLink(recipe.name, value: recipe.id) // Recipe.ID
.navigationDestination(for: Recipe.ID.self) { id in // ✅ Recipe.ID
RecipeDetail(id: id)
}
Verificación
- Imprime el tipo en el destino:
print(type(of: value)) - Los tipos deben coincidir exactamente (sin herencia)
Patrón 2a: NavigationPath Recreado en Cada Renderizado
Costo de tiempo 15-20 minutos
Síntoma
- La navegación empuja y luego retrocede inmediatamente
- Parece que la vista de destino "parpadea"
- Funciona una vez, luego falla, o falla inmediatamente
Diagnóstico
// ❌ INCORRECTO — Ruta creada en el body de la vista (se reinicia en cada renderizado)
struct ContentView: View {
var body: some View {
let path = NavigationPath() // ¡Recreado cada vez!
NavigationStack(path: .constant(path)) {
// ...
}
}
}
// ❌ INCORRECTO — @State en una vista hija que se recrea
struct ParentView: View {
@State var showChild = true
var body: some View {
if showChild {
ChildView() // Recreada cuando se alterna showChild
}
}
}
struct ChildView: View {
@State var path = NavigationPath() // Perdido cuando ChildView se recrea
// ...
}
Corrección
// ✅ CORRECTO — @State en un nivel estable
struct ContentView: View {
@State private var path = NavigationPath() // Persiste entre renderizados
var body: some View {
NavigationStack(path: $path) {
RootView()
}
}
}
// ✅ CORRECTO — @StateObject para ObservableObject
struct ContentView: View {
@StateObject private var navModel = NavigationModel()
var body: some View {
NavigationStack(path: $navModel.path) {
RootView()
}
}
}
Verificación
- Añade registro onChange — la ruta no debería reiniciarse inesperadamente
- Navega, espera, path.count se mantiene estable
Patrón 2d: Ruta Modificada Fuera de MainActor
Costo de tiempo 10-15 minutos
Síntoma
- La navegación funciona a veces, falla otras
- Advertencias de Swift 6 sobre aislamiento de MainActor
- Pops inesperados o corrupción de estado
Diagnóstico
// ❌ INCORRECTO — Modificando la ruta desde una tarea en segundo plano
func loadAndNavigate() async {
let recipe = await fetchRecipe()
path.append(recipe) // ⚠️ ¡No está en MainActor!
}
// Verificar: Busca path.append, path.removeLast fuera del contexto de @MainActor
Corrección
// ✅ CORRECTO — Asegúrate de MainActor
@MainActor
func loadAndNavigate() async {
let recipe = await fetchRecipe()
path.append(recipe) // ✅ Aislado en MainActor
}
// O despacha explícitamente
func loadAndNavigate() async {
let recipe = await fetchRecipe()
await MainActor.run {
path.append(recipe)
}
}
// ✅ MEJOR — Usa @Observable con @MainActor
Verificación
- Añade
MainActor.assumeIsolatedcheck en puntos de modificación de ruta - Prueba bajo carga pesada (muchas tareas async simultáneas)
- Sin pops inesperados ni advertencias de MainActor
Patrón 3a: Deep Link — Llamada a path.append Fuera de MainActor
Costo de tiempo 10 minutos
Síntoma
- Deep link abre la aplicación pero no navega
- Código de manejo de deep link se ejecuta pero la navegación no ocurre
- Sin errores en consola
Diagnóstico
// Verificar: ¿path.append se llama desde el hilo principal?
func handleURL(_ url: URL) {
let recipe = parseRecipe(from: url)
path.append(recipe) // ¿En qué hilo está esto?
}
// Añade verificación de hilo
func handleURL(_ url: URL) {
print("🔍 En hilo: \(Thread.isMainThread ? "Main" : "Background")")
let recipe = parseRecipe(from: url)
path.append(recipe)
}
Corrección
// ✅ CORRECTO — Asegura MainActor
func handleURL(_ url: URL) {
let recipe = parseRecipe(from: url)
DispatchQueue.main.async {
path.append(recipe)
}
}
// O mejor, marca la función como @MainActor
@MainActor
func handleURL(_ url: URL) {
let recipe = parseRecipe(from: url)
path.append(recipe)
}
Verificación
- Añade print del hilo justo antes de path.append
- Debe imprimir "Main"
Patrón 4a: NavigationStack Compartido Entre Pestañas
Costo de tiempo 20-30 minutos
Síntoma
- El estado de navegación se pierde al cambiar de pestaña
- La ruta de navegación se reinicia al volver a una pestaña
- Diferentes pestañas comparten el mismo estado de navegación
Diagnóstico
// ❌ INCORRECTO — NavigationStack compartido
struct TabViewContainer: View {
@State private var path = NavigationPath() // Estado compartido
var body: some View {
TabView {
NavigationStack(path: $path) {
TabARoot()
}
.tabItem { Label("A", systemImage: "a.circle") }
NavigationStack(path: $path) { // Misma ruta para pestaña B
TabBRoot()
}
.tabItem { Label("B", systemImage: "b.circle") }
}
}
}
Corrección
// ✅ CORRECTO — Estado independiente por pestaña
struct TabViewContainer: View {
@State private var pathA = NavigationPath()
@State private var pathB = NavigationPath()
var body: some View {
TabView {
NavigationStack(path: $pathA) {
TabARoot()
}
.tabItem { Label("A", systemImage: "a.circle") }
NavigationStack(path: $pathB) {
TabBRoot()
}
.tabItem { Label("B", systemImage: "b.circle") }
}
}
}
Verificación
- Navega en pestaña A, cambia a B, vuelve a A — el estado de navegación debe conservarse
- Cambia de pestaña, path.count debe mantenerse para cada pestaña
Patrón 5a: Crash — EXC_BAD_ACCESS en Código de Navegación
Costo de tiempo 30-45 minutos
Síntoma
- Crash con EXC_BAD_ACCESS en un punto de navegación
- El crash puede ser intermitente o reproducible
- El stack trace muestra NavigationStack o navigationDestination
Diagnóstico
// Síntomas comunes:
// 1. Enlace de navegación que usa un objeto que se desasigna
// 2. navigationDestination con closure que captura referencia débil
// 3. Path de navegación con tipos no conformes a Hashable/Codable
// ❌ POSIBLE CAUSA — Objeto liberado mientras se navega
class NavigationManager {
var path = NavigationPath()
}
struct ContentView: View {
var manager = NavigationManager() // Se libera al salir del body
var body: some View {
NavigationStack(path: $manager.path) {
// ...
}
}
}
Corrección
// ✅ CORRECTO — Asegura retención del objeto
struct ContentView: View {
@StateObject private var manager = NavigationManager() // Retenido
var body: some View {
NavigationStack(path: $manager.path) {
// ...
}
}
}
// O usa @State para tipos simples con NavigationPath
struct ContentView: View {
@State private var path = NavigationPath() // Simple y seguro
var body: some View {
NavigationStack(path: $path) {
// ...
}
}
}
Verificación
- El crash debe desaparecer
- Activa Zombie Objects en el esquema de Xcode para detectar referencias a objetos liberados
- Ejecuta con instrumentos de Thread Sanitizer
Glosario Rápido
| Término | Significado |
|---|---|
| Path State | El objeto NavigationPath o array que maneja la pila de navegación |
| View Identity | Cómo SwiftUI identifica y reutiliza vistas (usando id o identidad estructural) |
| Lazy Container | Contenedores como List, LazyVStack, LazyHStack que cargan vistas bajo demanda |
| MainActor | El hilo principal donde deben ocurrir las actualizaciones de UI |
| Deep Link | URL externa que abre la aplicación en una pantalla específica |
| NavigationStack | El contenedor moderno de navegación de SwiftUI (iOS 16+) |
| NavigationSplitView | El contenedor para navegación de dos o tres columnas (iPad/Mac) |