使用Contentful+Gatsby博客模板+AWS Amplify时Hero图片加载失败

以下是针对性的调试步骤：

• 检查图片请求URL与响应类型
  打开线上站点DevTools的网络面板，找到Hero图片的请求：

  1. 对比本地开发环境的图片URL，确认线上URL是否为Contentful的合法图片地址（格式应为https://images.ctfassets.net/[空间ID]/[图片ID]/[文件名]）。
  2. 如果线上请求返回text/html，说明请求被路由规则拦截，返回了页面而非图片——这是核心问题点。

• 验证Amplify重写/重定向规则
  登录AWS Amplify控制台，进入站点的「重写和重定向」设置：

  • 检查是否存在/* /index.html 200这类兜底规则，这类规则会把所有未匹配的请求都导向首页HTML，包括Contentful图片的请求。
  • 添加例外规则，比如允许https://images.ctfassets.net/**直接通过，或者调整规则优先级，让图片请求不被拦截。

• 确认Gatsby生产构建配置

  1. 检查gatsby-config.js中Contentful的配置项，确保生产环境使用的空间ID、API密钥正确（优先用Amplify环境变量注入，避免硬编码）。
  2. 对比本地与线上的依赖版本：确认gatsby-plugin-image、gatsby-source-contentful的版本在package-lock.json/yarn.lock中一致，Amplify构建时会严格按照锁文件安装依赖，版本不兼容可能导致图片URL生成错误。
  3. 确认Amplify的构建命令为npm run build，而非开发环境的npm run dev——生产构建会生成优化后的图片资源路径，开发环境逻辑不同。

• 对比GraphQL查询结果

  1. 本地启动gatsby develop，访问http://localhost:8000/___graphql执行HomeQuery，查看heroImage.gatsbyImage中的URL、宽度、高度等字段值。
  2. 线上构建时，查看Amplify的构建日志，确认GraphQL查询是否成功返回图片数据，有没有权限或字段缺失的报错。

• 检查Contentful媒体库权限
  确认Contentful中使用的API密钥拥有「媒体库:读取」权限，且目标图片未设置私有访问限制——权限不足会导致图片请求返回错误页面（即text/html响应）。

• 调试组件渲染细节
  线上DevTools中查看Hero组件的DOM结构：

  • 检查gatsby-image生成的<img>或<picture>标签的src/srcset属性，确认是否为合法的图片地址，而非未解析的占位符或错误路径。

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