Shields.io 徽章生成器快速上手指南


在前端开发过程中，我们常常需要为项目添加各种标识和徽章来展示项目的状态、版本信息、依赖情况等。Shields.io提供了一个非常便捷的方式来生成各种漂亮且实用的徽章。

Shields.io（ https://github.com/badges/shields/ ）是一个为开源项目、GitHub README或博客提供统一风格徽章（badge）生成的在线服务，支持SVG和栅格图像，覆盖构建状态、版本号、许可证、下载量、依赖健康程度等信息。其美观一致、调用简洁，成为数百万开源项目展示状态的首选。

基本徽生成方式

进入Shields.io官网：https://shields.io/ ；点击Get started进入生成徽章页面，或者直接使用URL参数代码生成。

1、通过URL参数生成

标签、消息和颜色组合（最常用方式）
格式为：标签(label)-消息(message)-颜色(color)
例如，如果要生成一个表示项目构建状态为 通过，颜色为 绿色 的徽章，URL应为:

1
https://img.shields.io/badge/build-passing-brightgreen

在这个URL中，build是标签(label)，passing是消息(message)，brightgreen是颜色(color)。

[!caution]
标签(label)、消息(message) 和 颜色(color) 之间必须用-分隔，标签(label)是可选的，如果没有标签(label)，则直接从消息(message)开始，例如：

1
https://img.shields.io/badge/passing-brightgreen

2、特殊字符处理

  1. 空格
    在URL中，空格可以用_（下划线）或%20来表示。例如：
    1
    2
    3
    https://img.shields.io/badge/any_text-you_like-blue
    或者
    https://img.shields.io/badge/any%20text-you%20like-blue
  2. 下划线和破折号
    如果要在徽章文本中显示下划线_，需要在URL中使用__（双下划线）。例如：
    1
    https://img.shields.io/badge/with__underscore-blue
    要显示破折号-，在URL中使用--（双破折号）。例如：
    1
    https://img.shields.io/badge/with--underscore-blue

3、颜色支持

Shields.io支持多种颜色格式，包括十六进制（如#ABCDEF）、RGB（如rgb(100, 100, 100)）、RGBA（如rgba(100, 100, 100, 0.5)）、HSL（如hsl(120, 50%, 50%)）、HSLA（如hsla(120, 50%, 50%, 0.5)）以及CSS命名颜色（如red、blue等）。例如：

1
https://img.shields.io/badge/label-message-red

徽章样式定制

1、样式参数

通过style查询参数可以选择徽章的样式。可选值有flat（默认）、flat-square、plastic、for-the-badge、social。
例如，生成一个扁平方形样式的徽章：

1
https://img.shields.io/badge/build-passing-brightgreen?style=flat-square

2、添加图标

  1. 简单图标库使用
    使用logo查询参数可以添加来自简单图标库(Simple Icons) https://simpleicons.org 的图标。你可以在简单图标库中点击需要的图标标题以复制别名，或者找到图标对应的slug，然后添加到URL中。例如，要添加一个Appveyor图标，URL应为：
    1
    https://img.shields.io/badge/build-passing-brightgreen?logo=appveyor
  2. 图标颜色和大小设置（仅适用于简单图标库图标）
    logoColor参数可以设置图标的颜色，支持上述提到的各种颜色格式。例如，使Appveyor图标显示为紫色，URL应为：
    1
    https://img.shields.io/badge/build-passing-brightgreen?logo=appveyor&logoColor=violet
    logoSize参数可以设置图标大小，设置为auto可以让图标自适应大小，对于一些较宽的图标很有用，如amd和amg图标。例如：
    1
    https://img.shields.io/badge/build-passing-brightgreen?logo=amd&logoSize=auto

文本覆盖和背景颜色定制

1、左侧文本覆盖（标签）

使用label查询参数可以覆盖徽章左侧的默认文本（如果有标签的话）。例如，如果默认徽章是：

1
https://img.shields.io/badge/build-passing-brightgreen

想要将左侧文本改为健康状态，则URL变为：

1
https://img.shields.io/badge/build-passing-brightgreen?label=healthiness

[!caution]
需要注意的是，如果标签(label)中有 空格 或 特殊字符 ，需要进行URL编码。

2、左侧文本背景颜色定制

通过labelColor参数可以设置徽章左侧文本的背景颜色。例如：

1
https://img.shields.io/badge/build-passing-brightgreen?label=healthiness&labelColor=abcdef

这里abcdef是十六进制颜色代码，会将健康状态文本的背景颜色设置为指定颜色。

3、右侧背景颜色定制

使用color参数可以设置徽章右侧（消息部分）的背景颜色。例如：

1
https://img.shields.io/badge/build-passing-brightgreen?color=fedcba

会将passing文本的背景颜色改为fedcba（假设这是一个合适的颜色代码）。

徽章缓存设置

通过cacheSeconds查询参数可以设置徽章的HTTP缓存生命周期，当响应可复用时，源服务器不需要处理请求——因为它不需要解析和路由请求、根据 cookie 恢复会话、查询数据库以获取结果或渲染模板引擎。这减少了服务器上的负载，加快响应速度。例如，该徽章将被缓存3600秒（1小时）：

1
https://img.shields.io/badge/build-passing-brightgreen?cacheSeconds=3600

[!caution]
需要注意的是，网站会根据一些规则推断默认的缓存值，如果指定的值低于默认值，可能会被忽略。

徽章链接设置

使用link参数可以指定点击徽章左右两侧时的跳转链接。

[!important]
此功能仅在将徽章集成到<object> HTML标签中时有效，在<img>标签或其他标记语言中无效。

例如，当在合适的<object>标签中使用该徽章时，点击徽章会跳转到https://example.com ：

1
https://img.shields.io/badge/build-passing-brightgreen?link=https://example.com

如果要分别设置左右两侧的链接，可以使用数组形式（具体的左右侧分配可能需要根据实际使用场景进一步确定和调整），例如：

1
https://img.shields.io/badge/build-passing-brightgreen?link[]=https://left.com&link[]=https://right.com

在项目中的使用

1、Markdown中的使用

在Markdown文件中，可以直接使用生成的徽章URL。例如：

1
![Build Status](https://img.shields.io/badge/build-passing-brightgreen)

这将在Markdown文档中显示一个带有Build Status标题（如果支持的话）和绿色passing字样的徽章。
Build Status

2、HTML中的使用

  1. <img>标签使用（无链接功能）
    在HTML中，可以使用<img>标签来显示徽章，这种方式简单直接，但不支持点击链接功能。例如：

    1
    <img src="https://img.shields.io/badge/build-passing-brightgreen" alt="Build Status">

  2. <object>标签使用（支持链接功能）
    如果需要添加点击链接功能，可以使用<object>标签，这里同时设置了徽章的链接和缓存时间（如果需要的话）。例如：

    1
    <object type="image/svg+xml" data="https://img.shields.io/badge/build-passing-brightgreen?link=https://example.com"><param name="cacheSeconds" value="3600"></object>

3.其他标记语言或文档中的使用

对于其他标记语言或文档，也可以将Shields.io生成的徽章保存为SVG图片格式，再根据其支持的图像嵌入方式来，通常也是通过引用徽章的URL来实现显示。

Shields.io是一款稳定、轻量的统一化徽章生成服务。通过灵活的 URL 配置，开发者可以将其轻松嵌入 Markdown 或 HTML 中，以直观、美观的视觉语言实时展示项目状态，从而显著提升文档的专业度与可信度。如果想了解更多进阶定制玩法，请参考官方说明文档：https://shieldsio.npmjs.net.cn/