GitHub Pages部署后无法加载本地图片、Tailwind背景图及@fontface字体

核心根因：GitHub Pages 部署仓库类项目（非个人根主页）时，站点访问前缀为https://<用户名>.github.io/<仓库名>/，所有以/开头的绝对路径资源会被解析到https://<用户名>.github.io/根目录，而非项目子目录，直接触发404。

任意值背景类路径加载失败修复 #

针对bg-[url('/dist/img/bg.jpg')]这类任意值语法定义的背景图，按以下优先级处理：

• 优先用构建工具统一配置前缀（最省事，零路径错误）：如果使用Vite等现代构建工具，直接在配置文件中设置项目base路径为仓库名，以Vite为例，在vite.config.js中添加：

export default defineConfig({
  base: '/portfolio-tailwind-css/', // 替换为实际仓库名
  // 保留原有其他配置
})

配置后构建环节会自动给所有资源路径（类名内路径、CSS字体路径、JS引用资源等）补全项目子路径前缀，不需要手动调整任何相对路径，从根源避免路径解析错误。

• 手动修正路径方案：如果不使用构建工具自动前缀，注意Tailwind任意值语法完全支持写相对路径，之前加./无效是路径参考层级写错了：路径要以编译后最终输出的CSS文件位置为参考，而非源码目录结构。比如最终编译的CSS存放在dist/css/style.css，背景图存放在dist/img/bg.jpg，类名要写成bg-[url('../img/bg.jpg')]，不要带开头的/dist——编译后的CSS已经在dist目录的css子文件夹内，向上跳一级即可访问img目录，之前写./dist/img/bg.jpg相当于在css目录下找dist文件夹，路径不存在自然加载失败。
• 兜底方案：把背景图定义从HTML类名挪到Tailwind配置中预定义，避免在类名里写长路径，在tailwind.config.js中添加：

/** @type {import('tailwindcss').Config} */
module.exports = {
  theme: {
    extend: {
      backgroundImage: {
        'page-bg': "url('../img/bg.jpg')" // 路径同样按编译后CSS位置写相对路径
      }
    }
  }
}

后续HTML中直接使用bg-page-bg类即可，Tailwind编译阶段会自动处理路径。

@font-face本地字体不显示修复 #

加./前缀仍加载失败，按以下点逐一排查修复：

• 修正相对路径层级：和背景图逻辑完全一致，路径参考对象是编译后输出的CSS文件，不是源码里的input.css。比如字体文件最终输出到dist/fonts/目录，CSS输出到dist/css/目录，@font-face中的路径要写成../fonts/字体文件名.woff2，不能写./fonts/——./指向CSS所在的css目录，该目录下没有fonts文件夹，必然加载失败。
• 确认字体文件被正常输出到部署目录：检查构建脚本是否配置了静态资源复制规则，保证字体文件被同步输出到dist目录的对应路径下，不少项目会漏配字体、图片等非CSS/JS资源的复制规则，导致部署产物里根本没有对应字体文件。
• 校验@font-face语法：确认font-family自定义名称、font-weight、font-style值和实际样式中引用的参数完全匹配，字体格式（woff2/ttf等）和路径中的文件后缀一致，不要出现文件名拼写、大小写错误。

部署前校验 #

本地构建完成后，直接打开dist目录下的index.html文件，确认所有图片、字体都能正常加载，再推送到GitHub Pages部署。本地静态打开能正常加载的话，只要GitHub Pages的部署分支、部署目录配置正确，就不会出现资源加载异常。

内容的提问来源于stack exchange，提问作者Nurul Arul Roji