theSVG API参考静态站点架构下如何用两个JSON清单完成搜索、筛选与取图【免费下载链接】thesvg7,400 brand SVG icons for developers. Tree-shakeable, typed, open source. npm i thesvg项目地址: https://gitcode.com/gh_mirrors/th/thesvg想要在自己的产品里接入 7,400 品牌 SVG 图标theSVG 的 API 设计出乎意料地简单它没有后端服务、没有动态搜索接口而是靠两个预生成的 JSON 清单registry.json和categories.json加上一个固定的 SVG 文件路径就完成了搜索、筛选与取图的全部工作。本文将带你从零理解这套静态 API 参考并给出新手可直接套用的接入步骤。为什么说没有 API 就是最好的 API传统做法是每次搜索都请求一次后端接口比如/api/search?qgithub。theSVG 反其道而行——整个站点是一个纯静态站点部署在 CDN 上。所谓API不过是三个可以无限缓存的静态地址地址作用说明GET /api/registry.json全量图标清单每个图标的 slug、名称、别名、分类、品牌色、变体GET /api/categories.json分类清单115 个分类及各自图标数量GET /icons/{slug}/{variant}.svg取图直接返回 SVG 文件核心思路一句话清单只拉一次搜索和筛选全部在浏览器里做。因为文件是静态且被 CDN 缓存的官方 FAQ 明确表示实际上没有速率限制见 src/lib/docs-content.ts 中 Is there a rate limit on the API? 的回答。端点一registry.json——图标搜索的数据底座registry.json由脚本 src/scripts/generate-api.ts 在构建时从源数据 src/data/icons.json 生成见 src/scripts/generate-api.ts#L51-L65结构如下{ total: 7400, icons: [ { slug: github, title: GitHub, aliases: [git hub], categories: [Software, Platform], hex: 181717, url: https://github.com/, license: MIT, variants: [default, mono] } ] }每个字段都有明确用途slug图标的唯一标识kebab-case如openai是取图 URL 的关键titlealiases搜索匹配的两个字段别名让 git 也能命中 GitHubcategories分类筛选的依据一个图标可属于多个分类hex品牌主色不含#可做配色或图标底色variants该图标拥有的变体列表。default永远存在mono单色、light/dark、wordmark文字商标等最多 7 种 新手提示URL 路径用的是精确的slug而不是品牌显示名。空格、点号和大小写都被规范化了所以不要凭品牌名猜 URL先查清单再取图这也是官方 FAQ 里 404 问题的第一原因。端点二categories.json——分类筛选器categories.json同样由 src/scripts/generate-api.ts#L68-L83 生成是遍历每个图标的categories字段聚合出的计数结果{ categories: [ { name: AI, count: 320 }, { name: Cloud, count: 540 }, { name: Payment, count: 180 } ] }拿到这份数据后你只需在页面上渲染一排分类胶囊按钮theSVG 官网自己就是这么做的参考 src/components/filters/category-pills.tsx点击某个分类时用registry.json里的categories字段做一次filter即可。三步完成搜索、筛选与取图把两个清单串起来整个接入流程只有三步第 1 步一次性拉取清单const res await fetch(https://thesvg.org/api/registry.json); const { icons } await res.json();官方文档里的 Search the catalog client-side 技巧src/lib/docs-content.ts#L278-L285正是这个思路清单在内存里每次按键都不发网络请求。第 2 步客户端过滤搜索 匹配title或aliases筛选 匹配categories排序 用hex或dateAdded。这些都是纯内存操作万级数据量毫无压力。第 3 步用 slug 拼出图片 URL找到目标图标后取图地址就是一个固定模板https://thesvg.org/icons/{slug}/{variant}.svg例如https://thesvg.org/icons/openai/default.svg。在页面里就是一个普通img标签官方最佳实践还提醒务必写上 width 和 height避免图标加载时页面抖动src/lib/docs-content.ts#L200-L218。⚠️ 如果你需要动态图标图标名来自用户输入或 CMS直接按 slug 拼 URL 比引入全部组件更好——零打包成本任意 7,400 图标都能渲染。高流量场景用镜像而不是硬怼主站清单和 SVG 都在 CDN 上但对超大规模生产应用官方建议走 jsDelivr 镜像或自建托管清单镜像https://cdn.jsdelivr.net/gh/glincker/thesvgmain/src/data/icons.json—— 这是权威源数据比registry.json多license、dateAdded等完整字段图片镜像https://cdn.jsdelivr.net/gh/glincker/thesvgmain/public/icons/{slug}/{variant}.svg两条生产建议来自官方最佳实践src/lib/docs-content.ts#L212-L222把main钉到具体 release 标签避免上游改名悄悄改变你的渲染结果仓库约 30 MB可以 clone 下来完全自托管代码是 MIT 许可常见疑问速查FAQ 精选以下问题整理自官网文档src/lib/docs-content.ts#L293-L364问题简短答案API 有速率限制吗两个 JSON 是静态 CDN 文件实际上没有限制图标 404 了怎么办十有八九是 slug 猜错了查清单里的精确 slug为什么某些图标没有 dark 变体不是每个品牌都有全部 7 种变体只有default保证存在有实时搜索 API 吗规划中的api.thesvg.org会提供 token 制接口相关搜索、webhook目前静态清单是唯一官方路径小结静态架构的三个好处快全链路 CDN 缓存首字节时间极低浏览器还能长效缓存清单稳没有后端故障面镜像与自托管随时可用简单新人 10 分钟就能读懂 src/scripts/generate-api.ts 的完整生成逻辑并据此在自己的项目里复刻同样的模式相关代码与资料清单生成脚本src/scripts/generate-api.ts源数据清单src/data/icons.json官网文档内容API 片段、技巧、FAQsrc/lib/docs-content.ts面向 AI 的完整 LLM 说明public/llms.txt、public/llms-full.txt客户端清单加载实现src/lib/icons-manifest.ts【免费下载链接】thesvg7,400 brand SVG icons for developers. Tree-shakeable, typed, open source. npm i thesvg项目地址: https://gitcode.com/gh_mirrors/th/thesvg创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考