github pages 部署后背景图片不显示，通常是因相对路径解析错误导致；本地（vs code live server）正常而线上失效，关键在于项目根路径与 github pages 发布路径不一致，需统一使用相对于 css 文件的相对路径并确保资源路径正确。
github pages 部署后背景图片不显示，通常是因相对路径解析错误导致；本地（vs code live server）正常而线上失效，关键在于项目根路径与 github pages 发布路径不一致，需统一使用相对于 css 文件的相对路径并确保资源路径正确。
在使用 GitHub Pages 托管静态网站（如个人作品集）时，一个高频问题就是：本地预览一切正常，但部署到 https://<username>.github.io/<repo> 后，CSS 中设置的 background-image 完全不加载。以 bautitobal/mi-portfolio 为例，其 inicio 类设置了背景图，但在 线上页面 中该背景始终为空——这并非代码语法或图片损坏问题，而是典型的 路径解析上下文差异 导致。
根本原因：GitHub Pages 的子路径部署机制
GitHub Pages 默认将仓库内容发布在子路径下（如 https://www.php.cn/link/430a7e19cd27b66c8a4a756b85dbfd85），而非根域名 /。此时浏览器解析 CSS 中的 url("img/fondo.jpg") 时，会以当前 HTML 页面 URL 为基准拼接路径，即尝试请求：
https://bautitobal.github.io/img/fondo.jpg（错误：跳过了 /mi-portfolio/ 子路径）
而 VS Code Live Server 默认以 / 为根运行（如 http://localhost:5500/），所以 url("img/fondo.jpg") 正确解析为 http://localhost:5500/img/fondo.jpg —— 这解释了“本地能用、线上失效”的现象。
正确解决方案：使用相对于 CSS 文件的路径
CSS 中的 url() 始终相对于该 CSS 文件所在位置解析，而非 HTML。因此应确保路径基于 CSS 文件的物理位置书写。例如：
-
项目结构典型如下：
mi-portfolio/ ├── index.html ├── css/ │ └── style.css ← CSS 文件在此 └── img/ └── fondo.jpg -
若 style.css 在 css/ 目录下，则要引用上层 img/ 中的图片，必须写成：
.inicio { background: linear-gradient(to top, rgba(30, 35, 38, .8), rgba(30, 35, 38, 1)), url('../img/fondo.jpg'); /* ✅ 正确：向上一级进入根目录，再进 img/ */ }注意：../ 表示“返回上级目录”，从 css/ 返回到项目根，再进入 img/。
关键注意事项
- ❌ 避免绝对路径 url("/img/fondo.jpg")：它强制从站点根 / 开始，但 GitHub Pages 仓库站点位于子路径，会导致 404。
- ❌ 避免硬编码完整 URL（如 url("https://.../mi-portfolio/img/fondo.jpg")）：破坏可移植性，且易因协议/域名变更失效。
- ✅ 推荐使用 ../ 相对路径，并通过浏览器开发者工具（Network 标签页）检查实际请求的图片 URL 是否返回 200 状态码。
- ✅ 确保图片文件已提交到 Git 并推送到 GitHub（常见疏漏：.gitignore 误删了 img/ 或图片未 git add）。
- ✅ 若使用 Jekyll，还需确认图片路径未被 Jekyll 的 _site 构建逻辑意外过滤（本例为纯静态，无需此步）。
验证步骤（快速排查）
- 打开线上页面 → 右键 → “检查” → 切换到 Network 标签；
- 刷新页面 → 在筛选栏输入 fondo → 查看 fondo.jpg 请求的 Status 和 Initiator（应为 style.css）；
- 点击该请求 → 查看 Headers 中的 Request URL 是否指向正确路径（如 https://www.php.cn/link/430a7e19cd27b66c8a4a756b85dbfd85img/fondo.jpg）；
- 若路径错误，立即修正 CSS 中的 url() 路径并重新推送。
遵循“CSS 中路径 = 相对于 CSS 文件位置”的原则，即可一劳永逸解决 GitHub Pages 背景图（及所有 url() 引用资源）的加载问题。这不是 Bug，而是 Web 资源定位机制的必然体现——理解它，才能稳健交付。
