Vercel上正确显示静态图片资源的方法

在 Vercel 上部署项目时，图片加载失败是常见问题。解决办法很简单：将图片统一放入项目根目录下的 public 文件夹，然后在 HTML 中使用根路径（例如 /image.png）引用即可。

Vercel 静态资源部署的核心规则

部署 Flutter Web 时，图片加载问题尤为突出。本地运行一切正常，上线后图片却全部无法显示，排查也较为麻烦。实际上，Vercel 对静态资源有清晰的目录规范：所有前端静态文件——包括图片、CSS、JavaScript、字体等——必须放置于项目根目录下的 public 文件夹中。Vercel 会自动将该文件夹映射到站点根路径 /。这意味着，不应将图片放入 static/、assets/ 或其他自定义目录。即使本地 Flask 开发服务器可以正常访问这些路径，Vercel 也无法识别。

正确操作步骤

只需两步即可解决问题。

1. 将所有图片（例如 logo.png、banner.jpg）移至 public/ 目录下，如 public/logo.png。
2. 在 HTML 中使用绝对路径引用，并省略 public 前缀。这一点至关重要。

常见错误写法及避免清单

以下错误写法应尽量避免：

关键细节提醒

• Vercel 默认以静态站点模式（Static Site Generation）部署纯 HTML/JS/CSS 项目。若使用 Flask，需改用 Serverless Functions，或切换到支持 SSR 的框架（如 Vercel + Next.js/Remix）。否则，Flask 的路由和 static/ 目录在 Vercel 上无法生效。
• 文件名区分大小写。Logo.png 与 logo.png 视为不同文件，路径拼写必须与实际完全一致。
• 首次部署后，可直接访问 https://your-domain.vercel.app/logo.png 测试图片 URL 是否正常。此方法可快速排查路径问题。
• 清除浏览器缓存或使用无痕窗口验证，避免旧缓存导致误判。

总结

Vercel 的静态资源服务机制与本地开发服务器（如 Flask 的 static）完全不同。public 是唯一被自动托管的静态资源入口目录。将图片统一放入该目录，并使用根路径引用，是解决图片不显示问题最彻底、最可靠的方式。