跳到主要内容

GitHub 徽章实战:用 README badge 把项目主页做得更专业

讲清楚 README badge 怎么选怎么放:构建状态、版本号、license、下载量这些 shields.io 徽章如何生成,Markdown 图片语法怎么插,以及怎么把一排徽章排得不打架。

发布于 作者 李雷
#github #readme #shields.io #markdown #开源

GitHub 徽章实战:用 README badge 把项目主页做得更专业

打开一个有人气的开源仓库,README 顶部那一排彩色小方块,几乎是默认配置:绿色的 build passing、蓝色的 version v1.2.0、灰绿相间的 license MIT、还有 downloads 12k/month。这些就是 README 徽章 (badge)。它们不只是装饰,而是访客在读你三百字介绍之前,第一眼判断"这个项目活不活、能不能放心用"的信号。

我自己接手过一个内部组件库,README 干干净净一段文字没有徽章,新同事第一句话是"这库还在维护吗"。加上 build passing 和最近一次发版的版本号之后,同样的问题再没人问过。徽章传递的是确定性,这是纯文字给不了的。

一个徽章长什么样:shields.io 的视觉规范

绝大多数 README 徽章出自 shields.io,它定义了一套现在已经是事实标准的视觉语言:左边是灰底的 label (类别名),右边是带颜色的 message (值),整体高度 20 像素,字体是 Verdana 系。颜色也有约定俗成的语义:通过用哑光绿 #4c1,失败用红 #e05d44,中性信息用蓝。这套配色不是随便挑的,它让不同项目的徽章看起来像同一个体系里出来的。

常见的几类徽章:

  • 构建状态:build | passing / build | failing,接 CI 的结果
  • 版本号:version | v1.2.0 或 npm | v1.2.0
  • 许可证:license | MIT
  • 测试覆盖率:coverage | 95%
  • 下载量:downloads | 12k/month
  • 品牌图标:Made with React,左边嵌一个 React 的 logo

Markdown 图片语法:徽章是怎么插进 README 的

徽章本质就是一张图片加一个跳转链接。README 是 Markdown 文件,所以用的是 Markdown 图片语法,外面再套一层链接语法。一个可点击的 license 徽章,完整代码长这样:

[![license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/you/repo/blob/main/LICENSE)

拆开看:![license](...) 是图片,license 是 alt 文本,括号里是徽章 SVG 的地址;最外层 [ ... ](链接) 让点击徽章跳到对应页面 (比如点 license 跳到 LICENSE 文件)。这一串贴到 README 顶部,GitHub 渲染出来就是那个熟悉的小方块。

这里有个容易踩的点:message 里的空格要编码成下划线 _,而原本就是下划线的字符要写成双下划线 __,这是 shields.io 的 URL 约定。比如想显示 "Apache License 2.0",直接写空格 URL 会断,要么编码,要么干脆缩写成 Apache-2.0,顶部那排徽章本来就不该太宽。

自己生成徽章:本地渲染 vs 依赖 shields.io

shields.io 是在线服务,每个徽章都是一个实时请求它服务器的 URL。对"值会变"的徽章 (实时构建状态、当前版本) 这很合理,每次访问都拉最新数据。但对"值永远不变"的徽章 (license 就是 MIT、用的就是 TypeScript),每个访客每次打开 README 都要为它多走一次 DNS + HTTPS 往返,而且 shields.io 一旦 503,你这些徽章在 README 里全变破图。

GitHub README 徽章生成器 解决的就是这个场景:它在浏览器本地按 shields.io 同一套视觉规格 (5 种风格、字符宽度估算、配色) 把 SVG 渲染出来,给你裸 SVG 字节和现成的 Markdown / HTML / AsciiDoc / RST 代码。把生成的 SVG 存进 assets/ 跟 README 一起 commit,徽章就和仓库里其他静态资源一样同源加载,没有外部依赖,shields.io 挂了也跟你无关。50+ 预设覆盖了 README 里真实会见到的那些徽章,还内嵌了 20 个 Simple Icons 品牌图标,改 label、message、颜色之后 SVG 实时重渲。

把一排徽章排得专业:几个细节

徽章好不好看,关键在一致性。几条我反复确认有效的规则:

  • 一排只用一种风格。for-the-badge 高 28px,flat 高 20px,混在一起一排参差不齐,一眼就显得是东拼西凑的。
  • 颜色守哑光色板。右边块别用霓虹色,鲜亮色会让那个徽章看起来"明显是临时塞进来的",跟旁边的格格不入。
  • 别塞太多。8 个是软上限,再多徽章那一排会把项目介绍挤到首屏外,访客还没看清你这库是干嘛的就划走了。
  • 静态徽章本地化。license、技术栈这类不变的徽章存成本地 SVG,既快又稳。

徽章排好之后,README 的内容本身也值得花点功夫。如果你要在文档里放参数对照、配置项说明这类结构化内容,用 Markdown 表格生成器 直接把表格代码生成好,比手对竖线省事得多,和徽章一样,都是让项目主页读起来更顺的小动作。

输出格式:不只是 GitHub

徽章的底层都是同一张 SVG,区别只在外层语法。GitHub / GitLab / npm 包页用 Markdown;博客、MDX 用 HTML 的 <img>;Java 项目的 Antora / Asciidoctor 文档用 AsciiDoc 的 image:badge.svg[alt,link=...];Python 项目发 PyPI 要用 reStructuredText 的三行 .. image:: 写法,markdown 徽章在 PyPI 上会静默不渲染。按徽章最终嵌在哪里选格式就行,SVG 本身一字不差。

徽章是项目门面的一部分,花十分钟把这一排做对,换来的是访客对项目第一印象的确定性,这笔账很划算。

Made by Toolora · Updated 2026-06-13