86 lines
3.2 KiB
Markdown
86 lines
3.2 KiB
Markdown
# Favicon 代理 API（Cloudflare Pages）
|
||
|
||
通过 HTTP API **代理**获取任意网站的 favicon，解决国内无法直连部分站点的问题。
|
||
使用 **Google**、**DuckDuckGo** 与 **直连目标站** 三路同时请求，**谁先成功返回就用谁**。
|
||
|
||
> 说明：Bing 没有公开的 favicon 接口，因此第二源使用 DuckDuckGo；直连目标站（如 `https://域名/favicon.ico`）作为第三路，真正起到“代理访问被墙站”的作用。
|
||
|
||
## 接口说明
|
||
|
||
- **方法**: `GET`
|
||
- **路径**: `/api/favicon`
|
||
- **参数**:
|
||
- `url` / `domain` / `u`（必填）：目标网站完整 URL 或域名，如 `https://twitter.com` 或 `github.com`
|
||
- `size`（可选）：图标尺寸 16–256，默认 128（仅对 Google 源生效）
|
||
|
||
## 示例
|
||
|
||
```bash
|
||
# 使用 url 参数
|
||
curl -o favicon.ico "https://你的 Pages 域名/api/favicon?url=https://twitter.com"
|
||
|
||
# 使用 domain 参数
|
||
curl -o favicon.ico "https://你的 Pages 域名/api/favicon?domain=github.com&size=64"
|
||
```
|
||
|
||
前端使用：
|
||
|
||
```html
|
||
<img src="https://你的 Pages 域名/api/favicon?url=https://example.com" alt="favicon" width="32" height="32" />
|
||
```
|
||
|
||
## 部署到 Cloudflare Pages
|
||
|
||
### 方式一：通过 Wrangler CLI
|
||
|
||
1. 安装 [Wrangler](https://developers.cloudflare.com/workers/wrangler/install-and-update/)：
|
||
```bash
|
||
npm install -g wrangler
|
||
```
|
||
|
||
2. 登录 Cloudflare：
|
||
```bash
|
||
wrangler login
|
||
```
|
||
|
||
3. 在项目根目录部署：
|
||
```bash
|
||
wrangler pages deploy . --project-name=cf-favicon
|
||
```
|
||
首次会提示创建项目，之后会得到 `https://cf-favicon.pages.dev` 这类地址。
|
||
|
||
### 方式二：通过 Git 连接（推荐）
|
||
|
||
1. 将本仓库推送到 GitHub/GitLab。
|
||
2. 在 [Cloudflare Dashboard](https://dash.cloudflare.com) → **Workers & Pages** → **Create** → **Pages** → **Connect to Git**。
|
||
3. 选择仓库，构建配置：
|
||
- **Build command**: 留空（无构建步骤）
|
||
- **Build output directory**: `/` 或 `.`（根目录即为静态资源）
|
||
4. 保存并部署。
|
||
部署完成后 API 地址为：`https://你的项目名.pages.dev/api/favicon?...`
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
cf-favicon/
|
||
├── functions/
|
||
│ └── api/
|
||
│ └── favicon.js # Favicon 代理 API 实现
|
||
├── public/
|
||
│ └── favicon.ico # 可选：默认图标，当所有外部源都失败时返回此文件
|
||
├── index.html # 简单说明页（可选）
|
||
├── wrangler.toml # 可选，用于 wrangler 部署
|
||
└── README.md
|
||
```
|
||
|
||
## 行为说明
|
||
|
||
- 请求会同时发往 **Google**、**DuckDuckGo**、**目标站 /favicon.ico** 以及 **目标站首页 HTML 中的 \<link rel="icon">**（支持 ico/png/jpg/webp/svg 等），采用“先成功先返回”，减少单点失败。
|
||
- **回退**：若三路均失败，会尝试返回 `public/favicon.ico`；若该文件存在则返回 200 并带响应头 `X-Favicon-Fallback: true`，否则返回 502。
|
||
- 运行在 Cloudflare 边缘，请求从 CF 出去，相当于代理访问，适合在国内环境调用以获取国外站点的 favicon。
|
||
- 成功时返回图片二进制和 `Cache-Control: public, max-age=86400`；失败时返回 400/502 及 JSON 错误信息。
|
||
|
||
## License
|
||
|
||
MIT
|