GitHub Pages部署后图片无法正常显示问题排查求助

两个核心问题直接答复 #

• 路径不需要放到特殊配置文件里，直接写在index.html内对应<img>标签的src属性位置即可。
• 优先修改本地项目文件，本地验证图片加载正常后再推送到仓库，不建议直接在线修改仓库内的index.html——在线修改无法本地预览校验，会浪费大量时间在反复部署、刷缓存上。

你当前../相对路径失效的原因 #

你的仓库根目录直接存放index.html文件，图片存放在根目录下的图片文件夹内。路径开头写../代表从当前文件所在位置向上一级目录寻址，会直接跳出GitHub Pages可访问的站点根目录范围，自然找不到图片资源。

分步操作流程 #

1. 先在本地核对项目文件结构，确保和下述结构完全匹配：

本地项目根文件夹/
├─ index.html
└─ images/ （你存放图片的文件夹，注意文件夹名大小写）
   └─ qr-code.png （你的图片文件，严格核对文件名、后缀大小写）

操作位置说明：直接打开你本地存项目的文件夹就能核对层级，不要把图片存在桌面、我的文档等和index.html不在同一个根文件夹的位置。

2. 用编辑器打开本地的index.html文件，找到图片对应的<img>标签，把src属性替换为以下两种写法任意一种即可：
   • 根路径写法（最稳定，不受页面层级影响）：<img src="/images/qr-code.png" alt="qr code">
   • 同级相对路径写法：<img src="./images/qr-code.png" alt="qr code">

   注意：路径开头不要加多余的..，开头的/直接对应GitHub Pages站点的根目录，也就是你仓库的根目录。

操作位置说明：<img>标签就是你编写图片插入逻辑的代码行，src就是专门用来填写图片地址的属性，不需要额外找其他配置文件填写路径。

3. 本地双击打开index.html文件，确认浏览器里图片可以正常显示，再把修改后的本地文件推送到GitHub仓库。

操作位置说明：本地验证是最关键的一步，本地能显示说明路径写法完全正确，不需要再反复调整路径参数。

4. 推送完成后等待1-2分钟让GitHub Pages完成部署，打开站点时按Ctrl+F5强制刷新清除浏览器缓存，避免加载到旧版本页面。

操作位置说明：你可以打开仓库的Settings-Pages页面，看到部署状态显示绿色对勾就代表部署完成，不需要反复刷新页面。

额外排查点 #

• 不要写Windows本地绝对路径，比如C:/Users/xxx/Desktop/project/images/qr-code.png这类路径上传到仓库后完全失效
• 文件夹、文件名不要用中文、特殊字符、空格，GitHub Pages运行在Linux环境下，文件名大小写敏感
• 确认GitHub Pages的部署分支设置正确，读取的是你存放index.html和图片文件夹的对应分支

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