为你的Repo添加自定义GitHub徽章教程

前端小工
635 阅读5分钟

如果你花时间看GitHub上的开源软件库，你可能已经注意到它们中的大多数都在README文件中使用了徽章。 以React官方软件库为例，README文件中到处都有GitHub的徽章，传达重要的动态信息，比如最新发布的版本和当前构建是否通过。

Showing the header of React's repo displaying GitHub badges.

像这样的徽章提供了一种很好的方式来突出仓库的关键信息。你甚至可以使用你自己的自定义资产作为徽章，就像Next.js在其 repo中做的那样。

Showing the Next.js repo header with GitHub badges.

但到目前为止，GitHub 徽章最有用的地方是它们会自动更新。GitHub上的徽章可以自动从远程服务器上获取变化，而不是在你的README中硬编码数值。

让我们讨论一下如何在自己项目的README文件中添加动态的GitHub徽章。我们先用一个叫badgen.net的在线生成器来创建一些基本的徽章。然后，我们将通过Napkin将徽章与我们自己的无服务器功能挂钩，使其成为动态徽章。最后，我们将通过使用我们自己的自定义SVG文件，使事情更进一步。

Showing three examples of custom GitHub badges including Apprentice, Intermediate, and wizard skill levels.

首先：徽章是如何工作的？

在我们开始在GitHub中建立一些徽章之前，让我们先快速浏览一下它们是如何实现的。这其实很简单：徽章就是图片。README文件是用Markdown写的，而Markdown支持图片，就像这样。

!\[alt text\](path or URL to image)

我们可以包含一个图片的URL，这意味着一个Markdown页面在渲染时将从服务器上请求图片数据。所以，如果我们控制了拥有图像的服务器，我们就可以用我们想要的任何逻辑来改变发送回来的图像！ 我们有几个选项可以选择。

值得庆幸的是，我们有几个选择来部署我们自己的服务器逻辑，而不需要整个 "设置服务器 "部分。对于基本用例，我们可以用badgen.net的预定义模板来创建我们的GitHub徽章图片。同样，Napkin可以让我们在浏览器中快速编写无服务器函数，然后将其部署为GitHub徽章可以对话的端点。

用Badgen制作徽章

让我们从最简单的徽章解决方案开始：通过badgen.net制作静态的徽章。Badgen API使用URL模式来即时创建模板化的徽章。该URL模式如下：

https://badgen.net/badge/:subject/:status/:color?icon=github

在badgen.net上有一个关于颜色、图标等选项的完整列表。在这个例子中，让我们使用这些值：

  • :subject: 你好
  • :status:: 世界
  • :color:: 红色
  • :icon:: twitter

我们最终的URL看起来是这样的：

https://badgen.net/badge/hello/world/red?icon=twitter

在 README 文件中添加 GitHub 徽章

现在我们需要把这个徽章嵌入到GitHub repo的README文件中。我们可以用我们之前看过的语法在Markdown中完成。

!\[my badge\](https://badgen.net/badge/hello/world/red?icon=twitter)

Badgen提供了大量不同的选项，所以我鼓励你去看看他们的网站，玩一玩例如，其中一个模板可以让你显示某个GitHub repo被加星的次数。以Next.js repo为例，这里有一个GitHub星级徽章。

https://badgen.net/github/stars/vercel/next.js

太酷了但如果您想让您的徽章显示一些Badgen不支持的信息，怎么办？幸运的是，Badgen有一个URL模板，可以使用您自己的HTTPS端点来获取数据。

https://badgen.net/https/url/to/your/endpoint

例如，假设我们想让我们的徽章显示以美元计的比特币的当前价格。我们所需要的是一个自定义的端点，像这样以JSON格式返回数据。

{
  "color": "blue",
  "status": "$39,333.7",
  "subject": "Bitcoin Price USD"
}

假设我们的端点在https://some-endpoint.example.com/bitcoin ，我们可以用下面的URL方案将其数据传递给Badgen。

https://badgen.net/https/some-endpoint.example.com/bitcoin

GitHub badge. On the left is a gray label with white text. On the right is a blue label with white text showing the price of Bitcoin.

比特币的成本数据被直接提供给GitHub的徽章。

现在更酷了!但我们仍然需要创建一个端点，为GitHub徽章提供数据。

Badgen + Napkin

有很多方法可以获得自己的HTTPS端点。你可以用DigitalOcean或AWS EC2来创建一个服务器，也可以使用Google Cloud Functions或AWS Lambda这样的无服务器选项；但是，对于我们的简单用例来说，这些都会变得有点复杂和乏味。这就是为什么我建议使用Napkin的浏览器内函数编辑器来编码和部署一个端点，而无需任何安装或配置。

到Napkin的比特币徽章例子中去看一个端点例子。你可以在编辑器中看到检索当前比特币价格并以JSON格式返回的代码。你可以自己从编辑器中运行代码，或者直接使用端点。

要使用Badgen的端点，请使用上述相同的URL方案，只是这次使用Napkin端点。

https://badgen.net/https/napkin-examples.npkn.net/bitcoin-badge

定制 GitHub 徽章的更多方法

接下来，让我们分叉这个函数，这样我们就可以在其中加入我们自己的自定义代码。点击右上角的 "Fork "按钮即可。如果你还没有登录，你会被提示在Napkin上建立一个账户。

一旦我们成功地分叉了这个功能，我们就可以使用任何我们想要的npm模块添加任何代码。让我们添加Moment.js npm包，并更新端点响应，直接在我们的GitHub徽章中显示比特币的价格最后更新的时间。

import fetch from 'node-fetch'
import moment from 'moment'

const bitcoinPrice = async () => {
  const res = await fetch("<https://blockchain.info/ticker>")
  const json = await res.json()
  const lastPrice = json.USD.last+""

  const [ints, decimals] = lastPrice.split(".")

  return ints.slice(0, -3) + "," + ints.slice(-3) + "." + decimals
}

export default async (req, res) => {
  const btc = await bitcoinPrice()

  res.json({
    icon: 'bitcoin',
    subject: `Bitcoin Price USD (${moment().format('h:mma')})`,
    color: 'blue',
    status: `\\$${btc}`
  })
}

部署该函数，更新你的URL，现在我们得到了这个。

你可能会注意到，当你下次在GitHub上加载README文件时，徽章需要一些时间来刷新。这是因为GitHub使用了一个代理机制来提供徽章图片。

GitHub这样提供徽章图片是为了防止滥用，比如高请求量或JavaScript代码注入。我们无法控制GitHub的代理，但幸运的是，它不会太积极地进行缓存（否则就失去了徽章的意义）。根据我的经验，TTL大约是5-10分钟。

好了，最后是老板时间。

用Napkin定制SVG徽章

对于我们的最后一招，让我们用Napkin送回一个全新的SVG，这样我们就可以像我们在Next.js repo上看到的那样使用自定义图片。

GitHub 徽章的一个常见用例是显示网站的当前状态。让我们来做这个。下面是我们的徽章将支持的两种状态。

Badgen不支持自定义SVG，所以我们要让我们的徽章直接与Napkin端点对话。让我们为此创建一个新的Napkin函数，名为site-status-badge 。

这个函数中的代码向example.com 。如果请求状态是200，它将返回绿色徽章的SVG文件；否则，它将返回红色徽章。你可以查看这个函数，但我也会把代码放在这里供参考。

import fetch from 'node-fetch'

const site_url = "<https://example.com>"

// full SVGs at <https://napkin.io/examples/site-status-badge>
const customUpBadge = ''
const customDownBadge = ''

const isSiteUp = async () => {
  const res = await fetch(site_url)
  return res.ok
}

export default async (req, res) => {
  const forceFail = req.path?.endsWith('/400')

  const healthy = await isSiteUp()
  res.set('content-type', 'image/svg+xml')
  if (healthy && !forceFail) {
    res.send(Buffer.from(customUpBadge).toString('base64'))
  } else {
    res.send(Buffer.from(customDownBadge).toString('base64'))
  }
}

example.com 网站瘫痪的几率很低，所以我添加了forceFail 的情况来模拟这种情况。现在我们可以在Napkin端点的URL后面添加一个/400 ，来进行尝试。

!\[status up\](https://napkin-examples.npkn.net/site-status-badge/)
!\[status down\](https://napkin-examples.npkn.net/site-status-badge/400)

查看状态上升徽章

查看状态下降的徽章

非常好 😎

就这样，我们拥有了它!你的 GitHub 徽章培训已经完成。但这一旅程还远未结束。像这样的徽章在很多方面都有很大的帮助。祝你实验愉快，让 README 熠熠生辉！✨

avatar
文章
阅读
粉丝