Next.js站点部署至Vercel后无法正常显示背景图片

基于Next.js搭建的站点部署到Vercel后，本地localhost:3000环境可正常展示的Tailwind配置背景图，生产环境加载失败。

Next.js本地开发服务会直接映射根目录public文件夹下的静态资源，路径匹配容错高；Vercel生产构建阶段会对静态资源做哈希重命名、路径重写，直接在tailwind.config.js中硬编码不带url()包裹的资源路径、或者路径写法不规范时，构建后的CSS会指向不存在的资源地址，触发404。另外Linux生产环境对文件名大小写敏感、旧构建缓存残留也会触发同类问题。

• 第一步：修正Tailwind配置的背景图写法
  打开项目根目录的tailwind.config.js，找到自定义backgroundImage的配置项，所有路径必须用url()包裹，且路径前加根路径斜杠，示例：

  /** @type {import('tailwindcss').Config} */
  module.exports = {
    // 其余配置省略
    theme: {
      extend: {
        backgroundImage: {
          // 错误写法：本地可运行，生产构建路径解析失败
          // 'main-bg': '/cloud-background.jpg',
          // 正确写法
          'main-bg': "url('/cloud-background.jpg')",
        }
      }
    }
  }
  

  注意检查图片文件实际存放位置：必须放在项目根目录的public文件夹下，文件名大小写和代码里写的完全一致，Linux环境下Bg.jpg和bg.jpg是两个完全不同的文件。
• 第二步：配置修改后清缓存验证
  本地先执行npm run build && npm start验证本地生产构建版本的背景图是否正常显示，确认没问题后推代码触发Vercel部署。如果Vercel端部署后还是异常，在Vercel项目控制台选择重新部署，勾选「清除构建缓存」选项后再触发部署，避免旧的Tailwind构建缓存残留。
• 第三步：备选方案（配置写法改完仍异常时使用）
  把背景图定义从tailwind.config.js挪到全局CSS文件中，这种写法会经过Next.js内置的PostCSS和静态资源处理链路，完全适配生产环境路径规则：

  /* 打开项目全局样式文件，通常为app/globals.css或pages/globals.css */
  @tailwind base;
  @tailwind components;
  @tailwind utilities;
  
  .bg-main {
    background-image: url('/cloud-background.jpg');
    background-size: cover;
    background-position: center;
    background-repeat: no-repeat;
  }
  

  组件中直接使用className="bg-main"调用即可，不需要额外修改Tailwind配置。

部署后打开浏览器开发者工具，切到网络面板筛选图片请求，确认对应背景图的请求状态码为200：如果返回404就回到第一步检查路径和文件名，如果返回200仍不显示就检查对应DOM节点是否设置了有效高度、是否被其他高层级元素遮挡。

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