GitHub.io网页图片嵌入失败但README可正常显示问题咨询

常见成因 #

这个问题的核心差异是GitHub仓库内README渲染和GitHub Pages部署的资源解析规则、运行环境不一致，具体高频触发原因如下：

• 路径解析规则不匹配：仓库内渲染Markdown时，所有路径默认以当前仓库的根目录为基准解析；但GitHub Pages如果部署在非根路径的项目仓库下（即仓库名不是<你的用户名>.github.io），以/开头的绝对路径会被解析到Pages域名的根目录，而非项目子目录，直接导致资源寻址失败。
• 文件大小写兼容逻辑差异：GitHub仓库端渲染README时对文件路径大小写做了模糊兼容，哪怕文件名和引用路径大小写有偏差也可能正常显示；但GitHub Pages托管在Linux环境下，文件路径严格区分大小写，任何大小写不匹配都会直接返回404。
• 构建环节资源被过滤：如果使用Jekyll等默认构建工具，以下划线开头的文件夹会被判定为系统资源目录，默认不会被打包到发布产物中；如果图片文件夹被.gitignore规则忽略、没有被提交到部署分支，也会出现仓库能看到、部署后找不到的情况。
• 引用了非原始资源地址：如果复制图片链接时误复制了仓库内图片预览的网页地址（带blob/tree路径段的网页链接，而非直链），仓库内渲染时会自动做地址转换，但Pages部署时不会做这类转换，直接导致资源加载失败。

对应解决方案 #

• 统一使用相对路径引用同仓库内的图片：非根主页类的项目Pages，所有本地图片不要用/开头的绝对根路径，直接写相对于当前Markdown文件的相对路径即可，比如当前md文件在仓库根目录，图片存在assets/pic/demo.png，直接写![示例描述](assets/pic/demo.png)即可。
• 逐字核对路径大小写：逐一核对引用路径里的文件夹名、文件名的大小写，确保和仓库内实际存储的文件命名完全一致，包括文件后缀的大小写（比如.PNG和.png不能混用）。
• 排查构建过滤规则：不要把静态图片存在以下划线开头的文件夹中；检查.gitignore配置，确认图片所在目录、对应图片格式没有被加入忽略列表，确保所有图片文件都被正常提交到部署分支。
• 替换非直链地址：不要使用带blob/tree路径的仓库预览网页地址作为图片链接，统一使用可直接访问的资源直链或者正确的相对路径。

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