网站 Favicon 获取 API 技术实现指南

接口概述本文档介绍一个通过 URL 参数获取任意网站 Favicon 图标的技术方案包括接口设计、调用方法、错误处理及调试技巧。接口规范基础信息项目说明接口地址https://api.afmax.cn/so/ico/index.php请求方式GET响应格式图片二进制数据ICO/PNG/JPG/GIF/SVG字符编码UTF-8请求参数参数名类型必填说明rstring是目标网站 URL支持带/不带协议头调用方式详解方式一标准 Query 参数GET /so/ico/index.php?r{target_url} HTTP/1.1 Host: api.afmax.cn示例# 带协议头curlhttps://api.afmax.cn/so/ico/index.php?rhttps://www.taobao.com/# 不带协议头自动补全curlhttps://api.afmax.cn/so/ico/index.php?rwww.taobao.com方式二强制 PNG 后缀兼容部分前端框架或 CMS 系统要求图片 URL 必须以.png结尾可通过添加?.png或/?.png实现兼容# 方式 Acurlhttps://api.afmax.cn/so/ico/index.php?rhttps://www.taobao.com?.png# 方式 Bcurlhttps://api.afmax.cn/so/ico/index.php?rwww.taobao.com/?.png技术说明?后的内容作为查询字符串被忽略不影响实际请求。方式三RESTful 路径风格curlhttps://api.afmax.cn/so/ico/index.php/7k7k.com/ico.png方式四Base64 编码防采集场景适用于需要隐藏真实目标域名的场景# 域名 so.com 的 base64 编码为 c28uY29tcurlhttps://api.afmax.cn/so/ico/base64.php/c28uY29t编码示例Pythonimportbase64 domainexample.comencodedbase64.b64encode(domain.encode()).decode()print(fhttps://api.afmax.cn/so/ico/base64.php/{encoded})图标抓取逻辑分析抓取优先级1. 首先请求 /favicon.ico ↓ 不存在或无法访问 2. 解析 HTML 中的 link relicon 或 link relshortcut icon ↓ 未找到 3. 查找 PWA manifest.json 中的 icons 配置 ↓ 未找到 4. 返回 404支持的图标格式格式MIME 类型说明ICOimage/x-icon传统 Windows 图标格式PNGimage/png推荐格式支持透明JPG/JPEGimage/jpeg无透明通道GIFimage/gif支持动画SVGimage/svgxml矢量格式2026.4.7 优化支持动态HTTP 状态码与错误处理状态码详解状态码场景排查建议200 OK成功获取图标正常响应可直接使用404 Not Found目标网站无可用图标检查目标 URL 是否正确确认网站是否设置了 favicon400 Bad Request请求参数错误检查r参数是否为空或格式错误444触发流量防护请求频率过高24 小时后重试检查是否开启懒加载500 Internal Server Error服务器繁忙未缓存资源排队中2 小时后重试或先进行预热错误处理代码示例JavaScript (Fetch)asyncfunctiongetFavicon(url){constapiUrlhttps://api.afmax.cn/so/ico/index.php?r${encodeURIComponent(url)};try{constresponseawaitfetch(apiUrl);if(!response.ok){switch(response.status){case404:console.warn([Favicon API] 未找到${url}的图标);return/default-favicon.png;// 使用默认图标case444:console.error([Favicon API] 触发流量限制请降低请求频率);returnnull;case500:console.warn([Favicon API] 服务器繁忙稍后重试);// 可加入重试逻辑returnnull;default:thrownewError(HTTP${response.status});}}constblobawaitresponse.blob();returnURL.createObjectURL(blob);}catch(error){console.error([Favicon API] 请求失败:,error);return/default-favicon.png;}}Python (Requests)importrequestsfromurllib.parseimportquotedefget_favicon(url,timeout10): 获取网站 favicon Args: url: 目标网站 URL timeout: 请求超时时间秒 Returns: bytes: 图标二进制数据失败返回 None api_urlfhttps://api.afmax.cn/so/ico/index.php?r{quote(url,safe)}?try:responserequests.get(api_url,timeouttimeout)ifresponse.status_code200:returnresponse.contentelifresponse.status_code404:print(f[WARN] 未找到{url}的图标)elifresponse.status_code444:print(f[ERROR] 触发流量限制请降低请求频率)elifresponse.status_code500:print(f[WARN] 服务器繁忙建议 2 小时后重试)else:print(f[ERROR] 未知错误: HTTP{response.status_code})exceptrequests.Timeout:print(f[ERROR] 请求超时 ({timeout}s))exceptrequests.RequestExceptionase:print(f[ERROR] 请求异常:{e})returnNone# 使用示例favicon_dataget_favicon(https://github.com)iffavicon_data:withopen(github.ico,wb)asf:f.write(favicon_data)PHP (cURL)?php/** * 获取网站 Favicon * * param string $url 目标网站 URL * param string $savePath 保存路径可选 * return string|bool 成功返回文件路径或二进制数据失败返回 false */functiongetFavicon($url,$savePathnull){$apiUrlhttps://api.afmax.cn/so/ico/index.php?r.urlencode($url);$chcurl_init();curl_setopt_array($ch,[CURLOPT_URL$apiUrl,CURLOPT_RETURNTRANSFERtrue,CURLOPT_FOLLOWLOCATIONtrue,CURLOPT_TIMEOUT10,CURLOPT_SSL_VERIFYPEERtrue,// 必须传递的 HeaderCURLOPT_HTTPHEADER[User-Agent: Mozilla/5.0 (compatible; FaviconFetcher/1.0),X-Forwarded-For: .$_SERVER[REMOTE_ADDR]??127.0.0.1,Referer: .($_SERVER[HTTP_HOST]??localhost)]]);$responsecurl_exec($ch);$httpCodecurl_getinfo($ch,CURLINFO_HTTP_CODE);$errorcurl_error($ch);curl_close($ch);if($error){error_log([Favicon API] cURL 错误:$error);returnfalse;}// 状态码处理switch($httpCode){case200:if($savePath){file_put_contents($savePath,$response);return$savePath;}return$response;case404:error_log([Favicon API] 未找到$url的图标);returnfalse;case444:error_log([Favicon API] 触发流量限制);returnfalse;case500:error_log([Favicon API] 服务器繁忙 (HTTP 500));returnfalse;default:error_log([Favicon API] 未知错误: HTTP$httpCode);returnfalse;}}?调试技巧1. 使用浏览器开发者工具打开 Network 面板观察请求请求 URL: https://api.afmax.cn/so/ico/index.php?rhttps://example.com 请求方法: GET 状态码: 200 OK 远程地址: [CDN IP] 响应头: Content-Type: image/x-icon 或 image/png X-Cache: HIT / MISS (缓存状态)2. 命令行调试# 查看完整响应头curl-Ihttps://api.afmax.cn/so/ico/index.php?rgithub.com# 查看请求耗时排查慢请求curl-wcurl-format.txt-o/dev/null-shttps://api.afmax.cn/so/ico/index.php?rgithub.com# curl-format.txt 内容# time_namelookup: %{time_namelookup}\n# time_connect: %{time_connect}\n# time_appconnect: %{time_appconnect}\n# time_pretransfer: %{time_pretransfer}\n# time_redirect: %{time_redirect}\n# time_starttransfer: %{time_starttransfer}\n# time_total: %{time_total}\n3. 缓存状态检测# 检测服务状态和缓存命中率curlhttps://api.afmax.cn/so/ico/look.php4. 常见问题排查问题现象可能原因解决方案图标显示为破损图URL 编码问题使用encodeURIComponent()编码目标 URL请求超时目标网站响应慢增加超时时间使用已缓存的域名测试返回 404 但实际有图标非标准图标路径检查网站是否使用link relicon自定义路径图标模糊原图质量低无解决方案取决于源网站提供的图标SVG 图标无法显示浏览器兼容性或 API 处理2026.4.7 后已优化检查 API 版本性能优化建议1. 客户端缓存!-- 使用浏览器缓存 --imgsrchttps://api.afmax.cn/so/ico/index.php?rexample.comloadinglazydecodingasync2. 懒加载实现// Intersection Observer 实现懒加载constimgObservernewIntersectionObserver((entries,observer){entries.forEach(entry{if(entry.isIntersecting){constimgentry.target;img.srcimg.dataset.src;observer.unobserve(img);}});});document.querySelectorAll(img[data-src]).forEach(img{imgObserver.observe(img);});3. 服务端缓存PHP 示例?php/** * 带本地缓存的 Favicon 获取 */functiongetFaviconWithCache($url,$cacheDir./favicon_cache/,$cacheTime86400){$cacheKeymd5($url);$cacheFile$cacheDir.$cacheKey..ico;// 检查本地缓存if(file_exists($cacheFile)(time()-filemtime($cacheFile))$cacheTime){returnfile_get_contents($cacheFile);}// 从 API 获取$favicongetFavicon($url,$cacheFile);return$favicon;}?安全注意事项1. 输入验证// 验证 URL 格式functionisValidUrl(string){try{newURL(string.startsWith(http)?string:https://string);returntrue;}catch(_){returnfalse;}}// 使用consttargetUrluserInput;if(!isValidUrl(targetUrl)){console.error(无效的 URL);return;}2. 防止 SSRF如果服务端代理请求需限制目标地址importipaddressdefis_private_ip(hostname):检查是否为内网 IPtry:ipipaddress.ip_address(hostname)returnip.is_privateexceptValueError:returnFalse# 禁止访问内网地址ifis_private_ip(parsed_url.hostname):raiseValueError(禁止访问内网地址)3. 请求头要求镜像/代理场景如果通过服务端代理调用 API必须传递以下 HeaderUser-Agent: {你的应用标识} X-Forwarded-For: {真实用户 IP} Referer: {来源页面}技术实现原理图标抓取流程┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ 接收请求 │────▶│ 解析目标URL │────▶│ 检查缓存 │ └─────────────┘ └─────────────┘ └──────┬──────┘ │ ┌────────────────────────┘ │ 命中 ▼ ┌─────────────┐ │ 返回缓存 │ └─────────────┘ │ 未命中 ▼ ┌─────────────┐ │ 请求favicon │────▶ 成功 ──▶ 缓存并返回 │ .ico │ └──────┬──────┘ │ 失败 ▼ ┌─────────────┐ │ 解析HTML │────▶ 找到 icon 标签 ──▶ 抓取 │ 查找link │ │ │ 标签 │◀──────────────────────────┘ └──────┬──────┘ │ 未找到 ▼ ┌─────────────┐ │ 检查PWA │────▶ 找到 manifest ──▶ 抓取 │ manifest │ │ └──────┬──────┘◀──────────────────────────┘ │ 未找到 ▼ ┌─────────────┐ │ 返回404 │ └─────────────┘参考资源CSDN 技术博客 - Favicon API 使用详解MDN - Link types: iconW3C - HTML Living Standard: Icon文档版本: 1.0 | 最后更新: 2026-04-07