github pages 部署后背景图片不显示，通常是因相对路径解析错误或资源路径未适配 jekyll/github pages 的构建规则；本文详解路径修正方法、调试技巧及最佳实践。
github pages 部署后背景图片不显示，通常是因相对路径解析错误或资源路径未适配 jekyll/github pages 的构建规则；本文详解路径修正方法、调试技巧及最佳实践。
在 GitHub Pages 上部署静态网站时，CSS 中的 background-image 路径失效是高频问题。尽管本地（如 VS Code Live Server）能正常显示，但线上却空白——根本原因在于：GitHub Pages 默认以仓库根目录为站点根路径，而 CSS 文件中的相对路径是相对于该 CSS 文件自身位置解析的，而非 HTML 页面位置。
以你的项目 bautitobal/mi-portfolio 为例：
- 项目结构中，图片存于 ./img/fondo.jpg；
- CSS 文件（如 style.css）位于 ./css/style.css；
- 因此，在 style.css 中引用图片时，必须使用 相对于 CSS 文件的路径，即向上一级回到项目根，再进入 img/ 目录：
.inicio {
background: linear-gradient(to top, rgba(30, 35, 38, .8), rgba(30, 35, 38, 1)),
url('../img/fondo.jpg');
}✅ 正确写法说明：
- ../ 表示从 css/ 目录上跳一级至项目根目录；
- ../img/fondo.jpg → 解析为 https://bautitobal.github.io/mi-portfolio/img/fondo.jpg，与 GitHub Pages 实际资源 URL 一致。
⚠️ 常见错误与规避建议：
立即学习“前端免费学习笔记（深入）”；
- ❌ 错误：url('img/fondo.jpg')（CSS 文件在 css/ 下，该路径会尝试访问 css/img/fondo.jpg，不存在）；
- ❌ 错误：url('/img/fondo.jpg')（以 / 开头表示站点根路径，但 GitHub Pages 仓库级站点的根是 https://username.github.io/repo-name/，因此 /img/... 会错误指向 https://username.github.io/img/...，而非你的仓库子路径）；
- ✅ 推荐：始终使用相对路径（如 ../img/xxx），并确认文件层级关系；
- ✅ 进阶保障：在浏览器开发者工具（Network 标签页）中检查 fondo.jpg 是否返回 404，点击请求链接可直观验证实际请求 URL 是否正确。
? 补充技巧：
若项目未来可能托管到自定义域名或不同路径，可考虑使用 CSS 自定义属性 + JavaScript 动态注入基础路径，但对纯静态 Portfolio，精简可靠的相对路径仍是首选方案。
总结：解决 GitHub Pages 背景图不显示问题，核心在于 理解“CSS 中的 url() 是相对于 CSS 文件位置解析”这一关键机制，并据此精确计算 ../ 层数。一次路径校准，即可让渐变叠加背景图稳定呈现于线上环境。
