Astro v3中Frontmatter引用图片无法加载问题排查

核心问题在于你没有在集合Schema的image()助手内启用相对路径解析，导致Astro无法将Frontmatter里的相对路径图片转换为ImageMetadata对象，而是保留为字符串，进而被Image组件当作外部资源处理。

以下是具体修复步骤：

1. 更新集合Schema的image配置 #

在image()方法中添加resolve: 'relative'参数，明确告知Astro解析相对路径的本地图片文件：

const projectsCollection = defineCollection({
    schema: ({image}) => z.object({
        name: z.string(),
        icon: image({ resolve: 'relative' }) // 启用相对路径解析
    })
})

2. 确认Image组件的导入与使用 #

确保你使用的是Astro官方的Image组件，且正确从集合项的data属性获取Frontmatter：

---
import { Image } from 'astro:assets';
const { frontmatter } = Astro.props;
---
<main class="content">
    <h1>{frontmatter.name}</h1>
    <Image 
      src={frontmatter.icon} 
      alt={frontmatter.name}
    />
    <article><slot /></article>
</main>

3. 验证集合注册的完整性 #

检查src/content/config.ts中是否正确注册了集合，确保没有配置冲突：

import { defineCollection, z } from 'astro:content';

const projectsCollection = defineCollection({
    schema: ({image}) => z.object({
        name: z.string(),
        icon: image({ resolve: 'relative' })
    })
});

export const collections = {
    projects: projectsCollection
};

补充说明 #

MDX内容中的图片能正常加载，是因为Astro会自动处理Markdown语法内的图片路径，将其解析为本地资源；而Frontmatter字段不属于MDX内容解析范畴，必须通过Schema的image({ resolve: 'relative' })显式触发资源解析逻辑。

内容的提问来源于stack exchange，提问作者Drago96