问题现象
在 GitHub README 中展示透明 Logo 时,有时会遇到一个不太直观的问题:图片文件本身没有丢失透明通道,在普通网页和编辑器预览中也显示正常,到了 GitHub 页面却出现了灰色背景。
我是在整理 README 中的组织 Logo 时碰到这个现象的。最初我怀疑是图片代理缓存或资源格式问题,但对比原图、网页和 README 的渲染结果后,才把排查重点转向 GitHub 最终处理的 HTML 属性。
定位到 README 的图片属性
README 由脚本从网站内容自动生成。检查生成的 HTML,发现每张 Logo 都同时指定了宽度和高度:
<img src="logo.svg" alt="" width="32" height="32" align="middle">
在 GitHub Community 的相关讨论 中,也有人报告了相同的表现:README 的 <img> 同时设置 width 和 height 时,GitHub 渲染页面会出现额外的灰色背景,并提出移除其中一个尺寸属性作为规避方式。
这并不意味着 HTML 不应该同时声明图片宽高。在一般网页中,明确宽高有助于预留布局空间;这里遇到的是 GitHub Markdown 渲染环境下的具体表现。
最小修复
我只修改了 README 生成脚本,保留宽度,移除高度:
- <img src="logo.svg" alt="" width="32" height="32" align="middle">
+ <img src="logo.svg" alt="" width="32" align="middle">
图片高度因此由自身的宽高比决定,不需要修改 SVG、PNG、图片 URL 或网站的 CSS。更重要的是,修复写在同步脚本中,后续自动生成网站仓库 README 和个人 Profile README 时都会沿用同一规则。
验证与总结
重新同步两个 README 后,GitHub 页面上的灰色背景都消失了。网站原有的 Logo 布局没有变化,图片也仍然由同一套资源提供。
这次问题的关键不在于图片是否透明,而在于同一段 HTML 在普通网页、编辑器预览和 GitHub README 中可能有不同的渲染结果。遇到类似现象时,除了检查图片本身,也值得检查最终生成的标签和属性。
参考:GitHub Community — GitHub adds grey background color to img in markdown。