Next.js生产构建后静态站点Webp格式图片无法显示问题排查

1. 站点部署路径不匹配
   你代码中使用的是根绝对路径/images/architect/Header-Image.webp，默认从站点根目录查找资源。如果生产环境站点部署在子路径下（例如https://domain.com/project/），实际请求的资源路径会跳过子路径直接指向根目录，导致404，本地开发一般运行在根路径所以无异常。
2. 构建工具资源处理规则异常
   部分框架/构建工具的生产构建配置可能修改了public目录的输出规则，比如配置了仅特定后缀的资源会被拷贝到构建产物目录、或者静态资源会被自动添加hash后缀，导致你写死的路径和构建产物的实际路径不匹配。
3. 服务端未配置webp格式的MIME类型
   生产环境的静态资源服务器（Nginx、Apache等）如果没有配置webp对应的MIME类型，会返回错误的Content-Type响应头，浏览器无法识别为图片，导致加载失败。
4. 路径大小写不匹配
   本地开发常用的Windows、macOS系统文件系统默认大小写不敏感，即使代码里路径大小写和实际文件不一致也能正常加载，而生产环境多用Linux系统，文件系统大小写敏感，路径大小写不一致就会返回404。

• 子路径部署适配：
  先确认生产环境站点是否部署在子路径下，如果是，在构建工具配置中添加基础路径配置：
  • Vite项目：在vite.config.js中配置base: '/你的子路径/'，资源引用改为模块导入方式：

    import headerImg from '/images/architect/Header-Image.webp'
    // 模板中绑定headerImg到srcset属性即可
    

  • Next.js项目：在next.config.js中配置basePath: '/你的子路径/'
  • Nuxt项目：在nuxt.config.ts中配置app.baseURL: '/你的子路径/'
• 构建规则校验：
  构建完成后先检查dist目录下是否存在images/architect/Header-Image.webp文件：
  • 若文件不存在：检查构建配置是否排除了webp格式资源，是否修改了public目录的输出路径
  • 若文件名带hash后缀：将图片从public目录移动到src/assets目录，通过模块导入的方式引用，构建工具会自动匹配带hash的路径
• MIME类型配置：
  如果你使用Nginx部署，在nginx.conf的http配置块中添加以下规则后重启服务：

  types {
      image/webp webp;
  }
  

  如果是第三方静态托管平台，在平台的配置面板中添加webp格式的MIME类型映射，值为image/webp
• 路径大小写统一：
  核对代码中引用的路径、文件名和public目录下实际的文件路径、文件名大小写完全一致，建议统一使用小写避免差异。

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