Debug Astro: Arregla "Campos de Schema Ocultos" en 5 Min

¿Por qué no se actualizan los campos de mi schema en Astro?

Si has añadido campos a tu schema de Astro Content Collections y no aparecen, la causa más común es la ubicación o el nombre del archivo de configuración. A partir de Astro 6, la ruta antigua src/content/config.ts desaparece; Astro lee solo src/content.config.ts. (En Astro 5 la ruta antigua todavía funcionaba, por eso esta trampa pilla a la gente a mitad de la migración.)

Antes de quemarte una tarde con esto (yo lo hice), repasa esta checklist:

1. Ubicación. El archivo de configuración vive en la raíz de src/, no dentro de src/content/. Correcto: src/content.config.ts. Incorrecto: src/content/config.ts.
2. Nombre. Debe llamarse content.config.ts, exactamente. Cualquier otra variación será ignorada.
3. Sin duplicados. Busca en tu proyecto otro archivo de configuración que Astro pueda estar leyendo en su lugar.
4. Caché. Elimina el directorio .astro y reinicia el servidor de desarrollo para forzar a Astro a regenerar los tipos desde el archivo correcto.

¿Alguna vez has definido un campo en tu schema solo para verlo desvanecerse en tiempo de ejecución? No estás solo. Hace poco pasé horas depurando campos de schema que desaparecían inexplicablemente, a pesar de estar definidos correctamente.

TL;DR. Mis nuevos campos de schema desaparecían porque estaba editando src/content/config.ts. Astro solo reconoce src/content.config.ts. Moví mis cambios al archivo con el nombre y la ubicación correctos y eliminé el duplicado.

Lo que sigue es el rastro completo de la depuración: los síntomas, los callejones sin salida y el arreglo.

El misterio de los campos del schema que desaparecen

Mientras añadía un campo relatedSlug al schema de mi blog para soporte multiidioma, me topé con un muro. El campo estaba definido en el schema y presente en el frontmatter del Markdown, pero completamente ausente en el objeto post.data.

Los síntomas

Mi configuración parecía correcta. El campo relatedSlug no estaba en ningún lado: ni en los tipos de TypeScript ni en tiempo de ejecución.

// src/content/config.ts
import { z, defineCollection } from "astro:content";

const blogCollection = defineCollection({
  schema: z.object({
    title: z.string(),
    // ... otros campos
    relatedSlug: z.string().optional(), // MAL: ¡este campo desaparecía!
  }),
});

export const collections = { blog: blogCollection };

• Definido en el schema: relatedSlug era claramente parte del objeto de Zod.
• Presente en el frontmatter: mis archivos .md incluían relatedSlug: "un-slug-cualquiera".
• Ausente en runtime: 'relatedSlug' in post.data devolvía false.

Dos de tres. Justo los dos que no servían.

Qué no funcionó (todo lo que probé antes)

Sospeché de un bug en Astro o Zod, así que empecé a tirar workarounds. Ninguno movió la aguja:

1. Cambiar .optional() por .default(""), esperando forzar la existencia del campo. Seguía ausente.
2. Hacerlo requerido. Astro debería haber lanzado un error por el campo faltante. No lo hizo. El campo seguía sin aparecer.
3. Renombrarlo. relatedSlug pasó a ser translation para descartar un conflicto de nombres. El campo nuevo también desapareció.

Ese tercer resultado era la pista de verdad. Cuando hasta los campos requeridos se ignoran en silencio, Astro no está leyendo tu configuración en absoluto.

La causa raíz: estaba editando el archivo equivocado

Después de horas de depuración, la respuesta fue vergonzosamente simple.

La documentación de Astro impone requisitos estrictos de nombre y ubicación al archivo de configuración de las colecciones de contenido.

• Archivo correcto: src/content.config.ts
• Mi archivo: src/content/config.ts

Había creado accidentalmente un archivo de configuración dentro del directorio content. A partir de Astro 6, esa ruta antigua src/content/config.ts desaparece, así que Astro lo ignoraba por completo y seguía leyendo una versión más antigua de content.config.ts ubicada en la raíz de src.

Una barra. Horas de mi vida.

El arreglo, en cuatro pasos

Una vez identificada la causa raíz, el arreglo fue mecánico.

Paso 1: confirma qué archivo está usando Astro de verdad

Los tipos generados en .astro/ te dan la respuesta.

// .astro/content.d.ts
// Esta línea revela la fuente de la verdad:
export type ContentConfig = typeof import("../src/content.config.js");

Paso 2: consolida y elimina

Copié mis últimas definiciones de schema del archivo incorrecto (src/content/config.ts) al correcto (src/content.config.ts) y luego eliminé el duplicado.

# Elimina el archivo de configuración incorrecto
rm src/content/config.ts

Paso 3: haz del archivo correcto la única verdad

Con el duplicado eliminado, me aseguré de que src/content.config.ts tuviera el schema final.

// src/content.config.ts  BIEN
import { z, defineCollection } from "astro:content";

const blogCollection = defineCollection({
  schema: z.object({
    // ... todos mis campos
    relatedSlug: z.string(), // BIEN: ¡ahora funciona!
  }),
});

export const collections = { blog: blogCollection };

Paso 4: limpia la caché

Para asegurarte de que Astro recoge los cambios, limpia la caché y reinicia el servidor de desarrollo.

# Limpia el directorio de caché .astro
rm -rf .astro
# Reinicia el servidor de desarrollo
npm run dev

Después de estos pasos, relatedSlug apareció en mis tipos y en tiempo de ejecución. Como si hubiera estado ahí todo el tiempo. Porque lo había estado.

La checklist que repasar antes de culpar al framework

La próxima vez que se te pierdan campos, comprueba esto antes de intentar nada ingenioso:

• ¿Está tu archivo de configuración en src/content.config.ts?
• ¿Se llama content.config.ts exactamente?
• ¿Hay solo un content.config.ts en todo el proyecto?
• ¿Has probado a eliminar el directorio .astro?
• ¿El archivo realmente hace export const collections?

Domina las convenciones antes de sospechar de la herramienta

Aquí va la parte incómoda. Pasé esas horas asumiendo que el bug estaba en Astro o en Zod, porque culpar a la herramienta sienta mejor que comprobar una ruta de archivo. La herramienta estaba bien. Mi árbol de directorios no.

Lo que parecía un bug profundo del framework era una configuración errónea con arreglo de cinco minutos. Cuando un framework te ignora en silencio, ese silencio suele significar que nunca te oyó. Revisa sus convenciones antes de abrir un issue.

Lectura relacionada: este renombrado exacto, src/content/config.ts a src/content.config.ts, es uno de los breaking changes de mi guía de migración de Astro 5 a 6, junto con el resto de trampas que vinieron con él.

P.D. ¿Cuál es el bug de ubicación de archivo más tonto que te ha comido una tarde? Las penas compartidas duelen menos. Cuéntamelo en Twitter/X.