README 徽章生成器

如何使用README 徽章生成器

关于README 徽章生成器的常见问题

README 徽章生成器会上传我的仓库信息吗？

不会。标签、仓库名、包名与跳转链接都只在浏览器本地拼成链接，预览徽章也是本地画出来的，页面本身不向 shields.io 发请求。本工具只在本地存储里记住输出格式、连接方式这类展示偏好，徽章列表与仓库名都不保存。把代码贴进 README 之后，读者打开仓库时由他们的浏览器去请求 shields.io，这是徽章正常工作的方式。

手机浏览器里怎么用 README 徽章生成器？

手机上直接打开本页即可：每枚徽章是一张可展开的卡片，按钮命中区按 44px 设计，代码区的长链接只在框内折行。复制后可以粘到 GitHub App 或网页版的 README 编辑框里。窄屏下字段改为单列排列。

shields.io 徽章链接的横杠为什么要写两遍？

shields 的静态徽章用横杠分隔「标签-内容-颜色」，所以文字里本来的横杠要写成两个，下划线同理，空格则写成一个下划线。比如 a-b_c d 转义后是 a--b__c_d。括号也必须百分号编码，否则右括号会提前截断 Markdown 的链接。本工具按这套规则自动转义，你只管填原文。

README 徽章里能写中文和 emoji 吗？

能。中文与 emoji 会按 UTF-8 百分号编码写进链接，比如「文档 | 中文」生成的链接是 https://img.shields.io/badge/%E6%96%87%E6%A1%A3-%E4%B8%AD%E6%96%87-red，GitHub 上显示正常。标签与内容各最多 64 个字符，按字素计数，组合 emoji 不会被拆开。徽章字体是 Verdana，中文会回落到系统字体，宽度由 shields 估算，偶尔会略松或略紧。

怎么让 GitHub 徽章点击后跳转到仓库？

在「点击跳转链接」里填仓库地址，本工具会把图片包进链接，Markdown 写法是嵌套的：[](https://github.com/user/repo)。动态徽章不填时自动用模板的默认跳转，例如 GitHub stars 跳到仓库的 stargazers 页面。shields 自己的 link 参数只在把 SVG 直接打开时生效，放进 img 标签里点不动，所以本工具不用它。

徽章生成器里的动态徽章数字为什么不更新？

动态徽章的数字由 shields.io 在被请求时实时去查，本工具里看到的只是示意值。贴进 README 后，GitHub 会通过自己的图片代理缓存徽章，数字可能要过一段时间才刷新，本工具无法控制缓存时长。若长时间不变，先在浏览器里直接打开徽章链接看看 shields 返回的是不是新数字。

徽章图标填了 Node.js 为什么不显示？

shields 的 logo 参数吃的是 Simple Icons 的 slug，不是品牌原名：小写，加号写成 plus，点写成 dot，再去掉其它符号。例如 Node.js → nodedotjs，C++ → cplusplus，.NET → dotnet，Vue.js → vuedotjs。本工具会在你输入时自动转换并提示。部分品牌因商标原因已被 Simple Icons 移除，填了也不会显示，图标以 shields.io 实际渲染为准。

徽章生成器能把已有的徽章链接改一改吗？

能。点「粘贴已有链接识别」，贴入单条 shields 链接或整段 README，本工具会认出 Markdown 图片、HTML img 标签与裸链接里的 shields 徽章，连同原来的跳转链接与替代文本一起加进列表，改完再复制。不是 shields 的图片会被跳过并计数，认不出的参数会提示已忽略。

shields.io 打不开或加载慢，README 徽章怎么办？

静态徽章可以点「下载 SVG」，把徽章文件放进仓库，再在 README 里用相对路径引用，这样就不再依赖外部服务。自托管徽章只支持静态徽章：动态徽章的数字要由 shields 实时生成，本地画不出来。下载的 SVG 不含图标，外观与 shields 近似但不保证像素一致。

README 徽章生成器的徽章可以商用吗？

链接与 SVG 都是你在本地按自己填的文字生成的，本站对生成结果不主张任何权利。徽章里的图标来自 Simple Icons，品牌标识归各自所有者，使用时请遵守相应品牌的规范。本站不提供法律意见，团队有素材审查要求时以法务意见为准。

README 徽章生成器参数速查表

README 徽章就是 GitHub 项目首页标题下那一排小标签，也叫 GitHub README 徽章、Markdown 徽章、项目徽章或开源项目徽章；英文叫法是 badge generator、readme badge 或 shields badge。本工具一次最多排 20 枚，常用的许可证徽章（license MIT）、PRs welcome、版本号都有预设。下面三张表是样式、颜色与动态模板的速查。

同义写法：gray = grey；lightgray = lightgrey；success = brightgreen；important = orange；critical = red；informational = blue；inactive = lightgrey。命名色取值来自 shields 仓库，数据核对日期 2026-10-21。

shields.io 徽章链接的转义规则

静态徽章的链接形如 https://img.shields.io/badge/标签-内容-颜色，横杠是分隔符，所以文字本身要按 shields 自己的规则转义：横杠写两遍，下划线写两遍，空格写成一个下划线，顺序必须是先横杠、再下划线、最后空格，否则空格变出来的下划线会被再翻一倍。转义之后还要做百分号编码，下表是本工具现算的对照。

浏览器自带的 encodeURIComponent 不编码括号、感叹号、星号和单引号，但右括号留在链接里会提前结束 Markdown 的图片语法，所以本工具对这五个字符额外编码。比如 version 1.0 beta 那枚徽章的链接是 https://img.shields.io/badge/version-v1.0_%28beta%29-orange，可以放心放进 Markdown。斜杠必须写成 %2F，否则会被当成路径层级。这套转义只针对 shields 的路径，和通用的 URL 编码解码 不是一回事。

静态徽章与动态徽章有什么区别

静态徽章的文字和颜色完全由你决定，链接里写死，适合许可证徽章、PRs welcome、技术栈标签这类不会变的信息。动态徽章只告诉 shields 去查哪个仓库或哪个包，数字由 shields 在被请求时实时生成，例如 GitHub star 徽章的路径是 github/stars/{user}/{repo}，npm 徽章（版本、下载量）、PyPI 版本、Docker 拉取次数、Codecov 覆盖率也是同理。GitHub Actions 构建状态徽章需要多填一个 workflow 文件名。

填 GitHub 用户名时可以直接粘贴仓库地址，本工具会自动拆成用户名和仓库名。参数不合法时那枚徽章不生成链接，避免把一枚 404 徽章贴进 README。还有更冷门的 shields 路由可以用「自定义路径」直接填，本工具只校验字符，不验证路由是否存在。

徽章怎么放进 README：Markdown、HTML 与 reST 写法

Markdown 里给徽章加跳转是嵌套写法：图片语法外面再套一层链接语法，即 [![license: MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/user/repo)。想让一排徽章居中，Markdown 做不到，要改用 HTML：<a href="https://github.com/user/repo"><img alt="license: MIT" src="https://img.shields.io/badge/license-MIT-blue"></a>，外面包一个 align 为 center 的 p 标签，GitHub 会保留这个对齐。

Python 项目常用的 reStructuredText 写法是 image 指令加 alt 与 target 两个选项，每枚徽章各占一段，不能像 Markdown 那样排在同一行：

.. image:: https://img.shields.io/badge/license-MIT-blue
   :alt: license: MIT
   :target: https://github.com/user/repo

AsciiDoc 用 image 宏，把跳转写在方括号里的 link 属性中。四种格式之外还有纯链接，便于贴进别的系统。徽章贴好后，可以用 Markdown 编辑器 预览整份 README；表格部分交给 Markdown 表格生成器，新建仓库时再配一份 .gitignore 生成器 的产物。

自托管 SVG 徽章：为什么文字宽度要写死

徽章的外框宽度必须在生成时定死，可不同电脑上的 Verdana 或回退字体宽度并不一样。shields 的做法是先按字宽表估算文字宽度定框，再给每段文字写 textLength 与 lengthAdjust，让浏览器把文字强制排进这个宽度：任何字体下都不会溢出框，也不会留出大片空白。本工具照同样思路内置了一张在浏览器里实测的字宽表，默认示例 license | MIT 的左段文字宽 37 像素、右段 21 像素，整枚宽 78 像素，与 shields 实际输出一致。

自托管徽章只支持静态徽章：点「下载 SVG」得到的文件不依赖任何外部服务，放进仓库后用相对路径引用即可，适合 img.shields.io 在部分网络下加载慢的情况。下载的 SVG 不画图标占位，避免把假图标发出去；文字全部经过 XML 转义，链接不会进入 SVG。本工具不出 PNG，需要把 SVG 转成图片请到姊妹站在线图片处理。

徽章颜色怎么选：命名色、十六进制与对比度

颜色可以填 shields 命名色（brightgreen、blue 这类），也可以填任意 CSS 颜色：十六进制、rgb()、hsl() 或 CSS 具名色，本工具统一转成不带井号的六位十六进制，因为井号在链接里表示片段起点。带透明度的颜色会去掉透明度并提示。要在多种颜色格式之间互转，可以用 颜色格式转换。

shields 会按底色亮度自动选白字或深灰字，本工具用同一个阈值，并按 WCAG 公式现算对比度：蓝色底配白字约 4.38:1，而 yellow 底仍配白字，只有约 1.95:1，低于 3:1 时卡片会提醒文字可能看不清。网页 head 里的分享标签与徽章无关，那是 Meta 标签生成器 的事。

相关教程

遇到格式选择、乱码或校验问题，可以先看这些说明再动手处理。

• 文件知识Markdown 是什么？常用语法速查表与转 HTML 方法新手向 Markdown 语法速查：讲清 Markdown 是什么、标题列表加粗怎么写、表格和代码块怎么排、常见踩坑，以及怎么实时预览效果、把 Markdown 转成 HTML 网页，全程浏览器本地处理、内容不上传。
• 文件知识URL 编码是什么？%20、%E4%B8%AD 这类字符解释讲清 URL 编码（百分号编码）是什么：为什么网址里会出现 %20、%E4%B8%AD 这类字符、encodeURI 与 encodeURIComponent 该用哪个、和 Base64 编码有什么区别，以及什么时候需要手动做 URL 编码。