徽章制作 | 牧之小岛

如何制作Github项目徽章？实现徽章自由。

不知道你有没有同感，刷 GitHub 的时候，总会被某些项目 README 顶部那排花花绿绿的徽章吸引。那些写着“build passing”、“v1.2.3”、“MIT license”的小标签，看着就特别“极客”和专业。每次看到都觉得很酷，也想给自己的项目整一套，但心里又犯嘀咕：“这玩意儿是自动生成的还是手动画的？代码里也没见着啊？”一开始我也以为很复杂我甚至使用Inkscape自己手动画svg文件，直到后来发现有很多工具可以直接在线制作例如badgen和这次说到的shields。

一、什么是 Shields？

Shields 是一个用于生成简洁、统一、易读的徽章（Badge）的在线服务。这些徽章通常被开发者用于 GitHub、GitLab 等平台的 README 文件中，用来展示项目状态、版本信息、代码覆盖率、构建状态等各种指标。

从原理上来说，我们向 Shields.io 服务器提供一些数据，服务器会返回一个 SVG 格式的图片。我们只需要将这个图片的 URL 嵌入 Markdown 文档中，即可渲染出定制的徽章。Shields.io 已被世界上一些最流行的开源项目所使用。

二、准备工作

在使用 Shields.io 之前，你需要了解两个基础概念：

2.1 基础 URL

Shields.io 的徽章服务主要通过 https://img.shields.io/ 这个域名提供。我们所有的工作就是在这个基础 URL 后面拼接不同的参数，以生成不同样式和内容的徽章。

2.2 URL 编码

当徽章文本中包含空格或特殊字符时，需要进行 URL 编码。常见编码对照：

空格 → %20
百分号 % → %25
斜杠 / → %2F

三、静态徽章（Static Badges）

静态徽章是最基础也最常用的类型，徽章内容是固定不变的。

3.1 基础写法

Shields.io 提供了两种 URL 格式来创建静态徽章。

格式一：简洁写法（推荐入门）

https://img.shields.io/badge/<左半部分>-<右半部分>-<颜色>

各部分说明：

左半部分：徽章左侧显示的标签文字
右半部分：徽章右侧显示的信息文字
颜色：右侧部分的背景色，支持颜色名称（如 blue）或十六进制码（去掉 #，如 007ec6）

示例：

https://img.shields.io/badge/牧之小岛-矩州凝一齋-blue

格式二：带参数的完整写法

https://img.shields.io/static/v1?label=<标签>&message=<信息>&color=<颜色>

标签-信息
这种写法更加清晰易读，参数含义一目了然，推荐在复杂场景下使用。

3.2 双色徽章

如果想实现左右两部分不同颜色的双色效果，可以使用 labelColor 参数：

https://img.shields.io/badge/html-49.99%25-gray?labelColor=orange

其中 labelColor 设置左侧标签的背景色，而 URL 路径中的颜色参数（如 gray）设置右侧值部分的背景色。

颜色支持多种指定方式：

预定义颜色名称：orange、gray、blue 等
十六进制颜色码：FF5733（注意去掉 #）
RGB 值：rgb(255,87,51)

3.3 整体徽章

如果不需要左右分区，可以将整个徽章作为一个整体：

https://img.shields.io/badge/<标签>-<颜色>

示例：

https://img.shields.io/badge/矩州凝一齋-black

以下以此类比

3.4 特殊情况说明

⚠️ 需要注意的是：如果指定了左半部分的颜色（即使用整体徽章格式），整个徽章将作为一个整体渲染，不再存在左右分区。左右两部分不能同时分别指定颜色，否则 Shields.io 会解析异常。

四、添加 Logo 图标

Shields.io 支持在徽章中添加图标，让徽章更加生动和专业。

4.1 使用 Simple Icons 官方库

Shields.io 支持 Simple Icons 网站中的所有 logo。你可以在该网站上搜索想要的图标，点击图标标题即可复制其 slug（短名）。

基础结构：

https://img.shields.io/badge/{左}-{右}-{颜色}?logo={图标名称}&logoColor={图标颜色}

示例（使用 etcd 图标）：

https://img.shields.io/badge/Etcd-熟练-green?logo=etcd&logoColor=white

4.2 使用自定义 Logo

如果你的 Logo 不在 Simple Icons 库中，可以通过 Base64 编码的方式传入自定义 SVG 图片。

URL 结构：

https://img.shields.io/badge/{左}-{右}-{颜色}?logo=data:image/svg+xml;base64,<Base64编码>

操作步骤：

将你的图标准备为 SVG 格式
将 SVG 代码进行 Base64 编码
将编码后的字符串拼接到 URL 中

关于自定义 Logo 的更多细节，可参考 Shields.io 官方 Logo 文档。

4.3 Logo 颜色与自适应

logoColor：设置图标颜色，支持十六进制、RGB、RGBA、HSL、HSLA 以及 CSS 命名颜色。注意：此参数仅对 Simple Icons 的官方图标有效，不支持自定义 Logo。
logoSize：设置为 auto 可使图标自适应调整大小，对于较宽的图标（如 amd、amg）尤其有用。

五、动态徽章（Dynamic Badges）

动态徽章可以从远程 JSON 接口获取数据并实时显示。这是 Shields.io 最强大的功能之一。

5.1 Dynamic JSON Badge

可以从任何 JSON 文档中使用 JSONPath 选择器提取任意值并显示在徽章上。

URL 结构：

https://img.shields.io/badge/dynamic/json?url=<JSON地址>&label=<标签>&query=<JSONPath表达式>&color=<颜色>

参数说明：

url：JSON 文档的地址（必需）
query：JSONPath 表达式，用于查询文档中的特定值（必需）
prefix / suffix：在显示值前后添加文本
label：覆盖默认的左侧文本
color：右侧背景色
labelColor：左侧背景色

示例：从 package.json 中获取许可证信息

https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Fbadges%2Fshields%2Fmaster%2Fpackage.json&query=%24.license&label=License

5.2 Endpoint Badge

Endpoint Badge 允许你通过自己的 JSON 接口来提供徽章内容。这种方式更加灵活，内容可以预渲染或动态生成。

你的 JSON 接口需要返回如下格式的数据：

{
  "schemaVersion": 1,
  "label": "hello",
  "message": "sweet world",
  "color": "orange"
}

URL 结构：

https://img.shields.io/endpoint?url=<你的JSON接口地址>

Endpoint Badge 支持通过查询参数覆盖 JSON 中的字段，如 label、color、labelColor 等。

六、样式定制

Shields.io 提供了多种样式选项，让徽章适应不同的展示场景。

6.1 style 参数

通过 style 参数可以改变徽章的整体外观：

样式值	说明
`flat`	扁平样式（默认）
`flat-square`	带圆角的扁平样式
`plastic`	立体塑料质感
`for-the-badge`	更宽、更醒目的样式
`social`	社交网络风格

示例：

https://img.shields.io/badge/框架-Vue.js-brightgreen?style=for-the-badge&logo=vuedotjs

6.2 缓存控制

通过 cacheSeconds 参数可以控制 HTTP 缓存生命周期。系统会根据每个徽章的类型推断默认值，任何低于默认值的设置将被忽略。

6.3 链接功能

link 参数可以指定点击徽章左右两侧时的跳转行为。注意：此功能仅在将徽章嵌入 HTML 的 <object> 标签时有效，在 <img> 标签或 Markdown 中无效。

七、常见问题与技巧

7.1 徽章不显示

如果徽章无法正常显示，可能的原因包括：

URL 长度限制：GitHub 平台对 URL 长度有限制，过长的自定义 Logo Base64 编码可能导致徽章无法显示。解决方案是尽量使用 Simple Icons 官方图标，或缩短自定义 SVG 代码。
缓存问题：错误的徽章图像可能已被缓存，通常会随着缓存过期自动恢复，一般在几小时内恢复正常。
API 令牌过期：某些服务（如 GitLab）的徽章依赖 API 访问令牌，令牌过期会导致徽章生成失败。

7.2 图标不显示

如果添加的图标无法显示，可能是 Simple Icons 库发生了变更。建议检查图标名称是否正确，或查阅 slugs.md 文件确认准确的图标 slug。

7.3 特殊字符处理

当文本中包含特殊字符时，务必进行 URL 编码：

% → %25（例如显示 "49.99%" 需写成 "49.99%25"）
空格 → %20
/ → %2F

7.4 使用第三方服务简化操作

如果觉得手动拼接 URL 和编码 Logo 太麻烦，可以使用 custom-icon-badges.demolab.com 这个服务。它允许你更轻松地使用自定义图标和 Logo 来生成 Shields.io 徽章。

操作步骤：

从 Shields.io 获取一个徽章 URL
将 img.shields.io 替换为 custom-icon-badges.demolab.com
使用任何可用的 slug 作为 logo 参数，或上传自己的图标

7.5 在 Markdown 中使用

在 Markdown 文件中使用徽章的标准语法是：

![徽章描述](徽章URL)

你可以将多个徽章排列在一起，使用表格布局可以让页面更整洁。

八、总结

Shields.io 的核心工作流程可以概括为：

确定需求：想清楚徽章要展示什么信息——是固定的标签文字，还是从 API 动态获取的数据？
选择类型：
- 固定内容 → 使用静态徽章（/badge/ 或 /static/v1）
- 从 JSON 取数 → 使用 Dynamic JSON Badge（/badge/dynamic/json）
- 自有数据接口 → 使用 Endpoint Badge（/endpoint）
添加图标：
- 优先从 Simple Icons 查找官方图标
- 找不到则准备 SVG 并转为 Base64 编码传入
美化样式：通过 style、labelColor、color、logoColor 等参数调整外观
嵌入文档：将生成的 URL 放入 Markdown 的 ![alt](url) 语法中

建议刚开始使用时，先访问 Shields.io 官网的 Badge Builder 进行可视化操作，熟悉各种参数的效果后再尝试手动拼接 URL。随着熟练度的提升，你会发现 Shields.io 是提升项目文档专业度和可读性的绝佳工具。要实现“徽章自由”，关键就在于用好 Simple Icons 这个图标宝库。它为 Shields.io 提供了海量、统一、高质量的品牌图标，免去了我们自己找图、转换的麻烦。

🏷️ 什么是 Simple Icons？

你可以把它理解为一个超级全面的品牌 Logo 库。它收集了超过 3400 个流行品牌的 SVG 矢量图标，每个图标都经过优化，风格统一。并且，这个项目在 GitHub 上开源，持续更新。

🔗 如何与 Shields.io 配合使用？

在 Shields.io 的 URL 中，只需使用 ?logo= 参数，并跟上该品牌在 Simple Icons 中的 Slug（短名称） 即可。

例如，要使用 Vue.js 的图标，其 Slug 是 vuedotjs，URL 如下：

https://img.shields.io/badge/Vue.js-4FC08D?logo=vuedotjs&logoColor=white

几个关键点：

找到 Slug：访问 Simple Icons 官网，搜索品牌，点击图标标题即可复制 Slug。或查阅其 GitHub 仓库中的 slugs.md 文件。
注意大小写：Slug 通常是全小写，且多个单词会连在一起（如 visualstudiocode）。
关于更新：Simple Icons 新增的图标可能需要一些时间才会同步到 Shields.io。

🎨 进阶技巧

自定义图标颜色：通过 &logoColor= 参数，可以覆盖图标的默认颜色。支持 Hex、RGB、颜色名称等多种格式。
自适应图标大小：对于像 amd、amg 这样比较宽的 Logo，可以添加 &logoSize=auto 参数，让图标自适应大小，避免变形。

💎 实现“徽章自由”的方案

方案一：直接使用（最推荐）
直接在 Shields.io 的 URL 中使用 ?logo=<slug>，这是最简单、最标准的方法。
方案二：使用可视化工具（无需编码）
访问一些社区提供的工具网站，它们将 Simple Icons 和 Shields.io 结合，可以直接搜索、预览并复制徽章代码。
- Simple Badges
- Markdown Profile Badges
方案三：借助第三方服务（支持更多图标）
- Custom Icon Badges：将 img.shields.io 替换为 custom-icon-badges.demolab.com。它除了支持 Simple Icons 外，还内置了 GitHub 的 Octicons 和 Feather Icons，并允许你上传自定义 SVG 图标。

⚠️ 注意事项

不要使用 Base64：使用 Simple Icons 时，无需进行任何 Base64 编码，直接使用 Slug 即可。
注意特殊字符：徽章文本中的空格需替换为 %20。

总的来说，Simple Icons 就是实现“徽章自由”的钥匙。从现在开始，忘掉繁琐的图片处理，直接在 Shields.io 的链接里填入对应的图标名称，就能轻松生成专业又美观的徽章了。