Next.js部署Github Pages：开发环境图片正常生产环境无法加载

使用Next.js搭配Tailwind CSS开发时，为div设置背景图片，开发环境可正常加载，但部署到Github Pages生产环境后无法显示。同一public/images/projects目录下的原有图片在两种环境都正常，仅新增图片出现此问题。

当前尝试的两种实现方式及问题：

1. 内联样式使用相对路径：

<div style={{ background: `url('./images/projects/bouncy-bouncy-proj.png')`, ...}}></div>

该写法在开发环境生效，生产环境失效。

2. 尝试导入图片：

import img from './images/projects/bouncy-bouncy-proj.png'

执行时出现「模块未找到」的错误。

当前tailwind.config.js配置：

/** @type {import('tailwindcss').Config} */
const plugin = require('tailwindcss/plugin');

module.exports = {
  darkMode: 'class',
  content: [
    './pages/**/*.{js,ts,jsx,tsx,mdx}',
    './components/**/*.{js,ts,jsx,tsx,mdx}',
    './app/**/*.{js,ts,jsx,tsx,mdx}',
  ],
  theme: {
    extend: {
      fontFamily: {
        burtons: "burtons",
      },
      backgroundImage: {
        'gradient-radial': 'radial-gradient(var(--tw-gradient-stops))',
        'gradient-conic':
          'conic-gradient(from 180deg at 50% 50%, var(--tw-gradient-stops))',
      },
      backgroundSize: {
        'size-200': '200% 200%',
      },
      backgroundPosition: {
          'pos-0': '0% 0%',
          'pos-100': '100% 100%',
      },
    },
  },
  plugins: [],
}

1. 修正public目录资源的引用路径 #

Next.js的public目录资源需用根路径开头的绝对路径引用，而非相对路径。开发环境相对路径能生效是因为本地服务器的路径解析逻辑，但Github Pages部署后，站点可能存在子路径，相对路径会解析错误。

修改内联样式路径：

<div style={{ background: `url('/images/projects/bouncy-bouncy-proj.png')`, ...}}></div>

去掉路径开头的./，直接从根目录/开始。

2. 解决图片导入错误问题 #

public目录下的资源无法通过相对路径导入（./开头），若要使用导入方式，需将图片移至src目录下（如src/images/）；若坚持用public目录，直接用根路径URL引用即可，无需导入。

3. 检查Git追踪与部署资源完整性 #

新增图片可能未被Git追踪，导致部署时未上传至Github。执行以下命令确认并修复：

# 查看未追踪文件
git status
# 追踪新增图片
git add public/images/projects/bouncy-bouncy-proj.png
# 提交并推送
git commit -m "Add new project image"
git push

重新部署Github Pages，确保资源已上传。

4. 核对文件名大小写 #

Github区分文件名大小写，而本地开发环境（如Windows）不区分。若本地文件名与代码中的写法大小写不一致，部署后会找不到文件，需确保两者完全匹配。

5. 配置basePath（针对子路径部署） #

若站点部署在Github Pages的仓库子路径（如https://username.github.io/your-repo/），需在next.config.js中配置basePath：

module.exports = {
  basePath: '/your-repo',
}

此时图片路径需拼接basePath：

<div style={{ background: `url('/your-repo/images/projects/bouncy-bouncy-proj.png')`, ...}}></div>

也可使用环境变量动态拼接，避免硬编码。

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