Astro博客项目本地正常，部署Vercel后图片及页面加载异常

一、src目录下图片加载失败的修复 #

Astro对src/content里的资源有专门处理逻辑，本地正常但部署后失效，多半是图片引用方式不对：

• 编写markdown（比如project-example.md）时，直接用标准markdown图片语法![示例图](./images/image-example.png)插入图片，然后在[slug].astro中通过getCollection拉取内容，Astro会自动将图片路径转换为构建后的正确地址。
• 检查astro.config.mjs里的site配置，必须填写Vercel部署后的域名，示例：

export default defineConfig({
  site: 'https://your-blog.vercel.app',
});

该配置会确保Astro生成正确的绝对路径，避免部署后路径错乱。

二、移到public目录后的问题修复 #

1. 页面跳转报错（404/资源加载失败） #

将图片放入public目录后，引用时必须使用根路径，不能用相对路径：

• 错误写法：./images/image-example.png（在project/xxx页面中会被解析为/project/images/xxx，但图片实际位于/images/目录下，直接导致404）
• 正确写法：/images/image-example.png（从根目录开始定位资源）

2. 图片加载速度慢 #

public目录下的资源不会被Astro自动压缩优化，需使用Astro的<Image>组件处理：
首先安装依赖：

npm install @astrojs/image

然后在astro.config.mjs中添加集成：

import { defineConfig } from 'astro/config';
import image from '@astrojs/image';

export default defineConfig({
  integrations: [image()],
});

之后在组件中这样使用：

---
import { Image } from '@astrojs/image';
---
<Image src="/images/image-example.png" alt="示例图" width={600} height={400} />

该组件会自动生成适配不同设备的图片格式和尺寸，大幅提升加载速度。

三、Favicon加载失败的修复 #

• 将favicon文件（如favicon.ico或favicon.svg）直接放入public根目录，不要放在src目录下。
• 在页面的<head>中正确引用：

<link rel="icon" type="image/x-icon" href="/favicon.ico" />
<!-- 使用SVG格式的话改为以下代码 -->
<link rel="icon" type="image/svg+xml" href="/favicon.svg" />

• 部署后若仍不显示，清空浏览器缓存，或到Vercel控制台手动触发重新部署，避免缓存旧的资源路径。

额外提醒 #

• 部署前先在本地执行npm run build，再通过npm run preview模拟生产环境，提前排查路径问题，避免部署到Vercel后才发现错误。
• 查看Vercel的部署日志，确认是否存在图片处理失败的报错（如权限问题）。

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