本文详解 github pages 图片路径失效的根源与解决方案，重点说明为何相对路径失效、何时需使用带仓库名的根相对路径，并提供可直接复用的路径规范与调试技巧。
本文详解 github pages 图片路径失效的根源与解决方案，重点说明为何相对路径失效、何时需使用带仓库名的根相对路径，并提供可直接复用的路径规范与调试技巧。
GitHub Pages 的图片无法显示，是初学者最常遇到却极易被误解的问题之一。根本原因在于：GitHub Pages 部署后运行在 https://
✅ 正确做法是使用 带仓库名前缀的根相对路径（也称“GitHub Pages-aware 路径”）：
<!-- ✅ 正确：路径以 '/' 开头，且包含仓库名 --> @@##@@ <a href="https://instagram.com/lauraperronigtr" class="header__link"> @@##@@ </a>
⚠️ 为什么你之前的方法都失败了？
- src="img/eu.jpeg" → 相对当前 HTML 文件位置解析，若 index.html 在仓库根目录，则解析为 https://lauraperroni.github.io/site-portfolio-curso/img/eu.jpeg ✅ —— 其实这个本应有效！ 但需确认文件实际存在且大小写完全匹配（GitHub 文件系统区分大小写）。
- src="/img/eu.jpeg" → 解析为 https://lauraperroni.github.io/img/eu.jpeg ❌（缺少仓库名）
- src="./img/eu.jpeg" → 同 img/eu.jpeg，通常可行，但易受服务器重定向或 Jekyll 干扰
- src="https://github.com/.../blob/main/..." → 指向 GitHub 源码页面 HTML，非原始文件，浏览器无法渲染为图片 ❌
- src="../icons/..." → index.html 位于根目录，无上级目录，路径越界 ❌
? 调试建议：
- 打开浏览器开发者工具（F12），切换到 Network 标签页，刷新页面，点击 404 图片请求，查看其 Failed Request URL —— 这直接暴露了 GitHub Pages 实际尝试加载的路径；
- 确认图片文件已提交并推送到 main 分支（检查 GitHub 仓库中 img/ 和 icons/ 目录是否可见）；
- 避免中文、空格或特殊字符命名文件，统一使用小写字母+短横线（如 eu.jpg 而非 eu.jpeg，但 .jpeg 本身合法）；
- 若启用 Jekyll（默认开启），确保图片文件不被 _config.yml 或 _includes 等规则忽略（静态资源建议放在 assets/ 或直接置于 img/、icons/ 等顶层目录）。
? 最佳实践路径规范（推荐统一采用）：
- 所有资源路径均以 / 开头 + 仓库名 + 子目录，例如：
src="/site-portfolio-curso/img/eu.jpeg" src="/site-portfolio-curso/icons/github.svg"
- 优点：语义清晰、部署路径变更时只需修改一处（如迁移到组织页）、兼容性最强；
- 补充：也可通过 _config.yml 设置 baseurl: "/site-portfolio-curso" 并在模板中使用 {{ site.baseurl }}/img/eu.jpeg，但纯静态 HTML 项目无需复杂配置，直接硬编码更简洁可靠。
总结：GitHub Pages 不是本地文件系统，而是托管在子路径下的网站服务。放弃“本地预览能跑就等于线上能跑”的直觉，始终以 https://
