Tailwind CSS背景图在GitHub Pages无法显示的问题求助

核心原因与解决步骤 #

GitHub Pages部署在仓库名对应的子路径下，Tailwind配置或HTML中的背景图路径必须匹配这个子路径，以下是具体方案：

1. 配置Tailwind自定义主题时指定正确路径

在tailwind.config.js的theme.extend.backgroundImage中，使用带仓库名的绝对路径：

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: ["./*.html"],
  theme: {
    extend: {
      backgroundImage: {
        'custom-bg': "url('/Tailwind-bgImg/images/bg.jpg')",
      },
    },
  },
  plugins: [],
}

然后在HTML中使用自定义类：

<div class="h-screen bg-custom-bg bg-cover bg-center"></div>

2. 使用Tailwind任意值直接定义背景图

若不想修改配置文件，可在HTML中直接用任意值语法，同样带仓库名绝对路径：

<div class="h-screen bg-[url('/Tailwind-bgImg/images/bg.jpg')] bg-cover bg-center"></div>

3. 关键排查点

• 大小写一致性：GitHub对文件名/路径区分大小写，确保代码中的路径和实际文件完全匹配
• 编译验证：运行npx tailwindcss -i ./input.css -o ./output.css编译后，打开output.css检查背景图路径是否正确生成
• 避免相对路径：不要使用../images/bg.jpg这类相对路径，部署后相对层级会变化，绝对路径更可靠

符合要求的项目结构示例 #

Tailwind-bgImg/
├── index.html
├── tailwind.config.js
├── input.css
├── output.css
└── images/
    └── bg.jpg

按上述配置编写代码，部署到GitHub Pages即可正常显示背景图。

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