Cloudflare Search

基于 Cloudflare Workers 的聚合搜索 API 服务

特性

• 🔍 多引擎聚合 - 同时使用多个搜索引擎（Google、Brave、DuckDuckGo、Bing）
• ⚡ 并行搜索 - 所有搜索引擎同时请求，快速返回结果
• 🛡️ 容错机制 - 单个引擎失败不影响其他引擎，自动标记无响应引擎
• ⏱️ 超时控制 - 可配置请求超时时间，避免长时间等待
• 🌍 CORS 支持 - 完整的跨域资源共享支持
• 🎨 Web 界面 - 提供简洁的搜索界面，方便测试
• ⚡ 零成本运行 - Cloudflare Workers 免费版每天 10 万次请求

页面展示

安装方式

方式一：一键部署（推荐）

点击上方 "Deploy to Cloudflare Workers" 按钮，按照提示完成部署。

方式二：使用 Wrangler CLI

# 1. 安装 Wrangler
npm install -g wrangler

# 2. 登录 Cloudflare
wrangler login

# 3. 克隆仓库
git clone https://github.com/Yrobot/cloudflare-search.git
cd cloudflare-search

# 4. 部署
wrangler deploy

方式三：使用 Cloudflare Dashboard

1. 登录 Cloudflare Dashboard
2. 进入 Workers & Pages
3. 点击 Create Application > Create Worker
4. 点击 Upload 上传本地代码文件夹
   • 选择克隆的 cloudflare-search 文件夹
   • 或者手动复制 worker.js、envs.js、utils/ 等文件
5. 点击 Save and Deploy

获取访问地址

部署成功后，你会获得一个 Worker URL：

https://your-worker-name.your-subdomain.workers.dev

注意：这个自带的域名在某些区域可能无法直接访问，建议绑定自己的域名使用。

使用方式

方式 1: Web 界面

直接访问你的 Worker URL，在网页界面输入搜索关键词：

https://$YOUR-DOMAIN/

方式 2: API 请求（GET）

使用查询参数进行搜索：

# 基本搜索
curl "https://$YOUR-DOMAIN/search?q=cloudflare"

# 指定搜索引擎
curl "https://$YOUR-DOMAIN/search?q=cloudflare&engines=google,brave"

方式 3: API 请求（POST）

通过 POST 表单提交搜索：

curl -X POST "https://$YOUR-DOMAIN/search" \
  -d "q=cloudflare" \
  -d "engines=google,brave"

API 接口说明

/search 接口

用于执行搜索查询并返回聚合结果。

请求参数

参数	类型	必填	说明	示例
q / query	string	yes	搜索关键词	cloudflare
engines	string	no	指定搜索引擎，多个用逗号分隔	google,brave

支持的搜索引擎：

• google - Google 搜索（需要配置 API Key）
• brave - Brave 搜索
• duckduckgo - DuckDuckGo 搜索
• bing - Bing 搜索

返回值

{
  query: string;                    // 搜索关键词
  number_of_results: number;        // 结果总数
  enabled_engines: string[];        // 启用的搜索引擎列表
  unresponsive_engines: string[];   // 无响应的搜索引擎列表
  results: Array<{
    title: string;                  // 结果标题
    description: string;            // 结果描述
    url: string;                    // 结果链接
    engine: string;                 // 来源引擎
  }>;
}

请求示例

# GET 请求
curl "https://$YOUR-DOMAIN/search?q=cloudflare&engines=google,brave"

# POST 请求
curl -X POST "https://$YOUR-DOMAIN/search" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "q=cloudflare&engines=google,brave"

响应示例

{
  "query": "cloudflare",
  "number_of_results": 15,
  "enabled_engines": ["google", "brave", "duckduckgo"],
  "unresponsive_engines": [],
  "results": [
    {
      "title": "Cloudflare - The Web Performance & Security Company",
      "description": "Cloudflare is on a mission to help build a better Internet...",
      "url": "https://www.cloudflare.com/",
      "engine": "google"
    },
    {
      "title": "Cloudflare Workers",
      "description": "Deploy serverless code instantly across the globe...",
      "url": "https://workers.cloudflare.com/",
      "engine": "brave"
    }
  ]
}

搜索引擎说明

支持的搜索引擎

引擎	说明	是否需要配置	默认启用
Google	Google Custom Search API	需要 GOOGLE_API_KEY GOOGLE_CX	yes
Brave	Brave Search API	-	yes
DuckDuckGo	DuckDuckGo 即时答案 API	-	yes
Bing	Bing 搜索	-	no (结果不稳定)

基本工作方案

1. 并行请求：所有启用的搜索引擎同时发起请求，提高响应速度
2. 超时控制：单个引擎超时不影响其他引擎，默认 3 秒超时
3. 结果聚合：将所有成功返回的结果合并，标记来源引擎
4. 容错处理：记录无响应的引擎，返回部分结果而不是完全失败

搜索引擎选择建议

• 无需配置快速部署：使用 brave + duckduckgo
• 高质量结果：配置 Google API 并使用 google + brave
• 最大覆盖：启用所有引擎 google,brave,duckduckgo,bing

环境变量配置

环境变量说明

变量名	类型	默认值	说明
DEFAULT_TIMEOUT	string	"3000"	单个搜索引擎的超时时间（毫秒）
GOOGLE_API_KEY	string	null	https://console.cloud.google.com/apis/credentials
GOOGLE_CX	string	null	https://programmablesearchengine.google.com/

注意：Google Custom Search API 免费版每天限制 100 次请求。

配置方式

方式 1: wrangler.toml 文件

编辑 wrangler.toml 文件中的 [vars] 部分：

[vars]
GOOGLE_API_KEY = "your-google-api-key"
GOOGLE_CX = "your-google-custom-search-cx"
DEFAULT_TIMEOUT = "5000"

方式 2: Cloudflare Dashboard

1. 进入 Worker 设置页面
2. 找到 Environment Variables 部分
3. 添加变量并保存

使用场景

1. 聚合搜索服务

构建自己的搜索聚合 API，整合多个搜索引擎结果：

const response = await fetch(
  "https://$YOUR-DOMAIN/search?q=javascript&engines=google,brave"
);
const data = await response.json();
console.log(`找到 ${data.number_of_results} 个结果`);

2. 前端搜索功能

为网站或应用添加搜索功能：

async function search(query) {
  const response = await fetch(
    `https://$YOUR-DOMAIN/search?q=${encodeURIComponent(query)}`
  );
  const data = await response.json();
  return data.results;
}

3. 数据采集与分析

收集多个搜索引擎的结果进行对比分析：

const engines = ["google", "brave", "duckduckgo"];
const results = await fetch(
  `https://$YOUR-DOMAIN/search?q=AI&engines=${engines.join(",")}`
);
const data = await results.json();

// 按引擎分组
const byEngine = data.results.reduce((acc, result) => {
  acc[result.engine] = acc[result.engine] || [];
  acc[result.engine].push(result);
  return acc;
}, {});

注意与提醒

🚨 重要提示

1. 使用自定义域名

   • Cloudflare 默认的 *.workers.dev 域名在某些地区可能无法访问
   • 强烈建议绑定自己的域名以获得更好的访问体验
   • 在 Worker 设置中点击 Triggers > Add Custom Domain 添加自定义域名

2. 搜索引擎限制

   • Google API 免费版每天限制 100 次请求
   • 其他搜索引擎一般没有严格限制，但请合理使用
   • 频繁请求可能导致被临时限制访问

3. 超时设置

   • 默认单个引擎超时 3 秒
   • 可通过环境变量 DEFAULT_TIMEOUT 调整
   • 建议不要设置过长，避免整体响应时间过长

常见问题

Q: 为什么有些搜索引擎返回结果为空？

A: 可能原因：

• 搜索引擎 API 临时不可用或响应超时
• 搜索关键词没有相关结果
• 搜索引擎限制了访问频率
• Google 需要配置 API Key 才能使用

可以查看返回的 unresponsive_engines 字段了解哪些引擎没有响应。

Q: 如何提高搜索速度？

A: 建议：

• 减少启用的搜索引擎数量，只使用需要的引擎
• 适当调整超时时间（DEFAULT_TIMEOUT）

Q: Bing 搜索为什么默认禁用？

A: Bing 搜索结果目前不够稳定，经常返回空结果或格式不一致。如需使用，可以在请求时手动指定：engines=bing 或修改 envs.js 中的 DEFAULT_ENGINES。

免责声明

本项目仅供学习和研究使用，使用者需遵守以下规定：

1. 合法使用 - 仅用于合法搜索需求，不得用于违法或侵权用途
2. 服务条款 - 使用时需遵守 Cloudflare Workers 和各搜索引擎的服务条款
3. API 限制 - 遵守各搜索引擎 API 的使用限制和配额
4. 责任自负 - 使用本服务产生的任何后果由使用者自行承担
5. 商业用途 - 如需商业使用，请确保符合相关法律法规和服务条款

贡献

欢迎提交 Issue 和 Pull Request！

许可证

GPL-3 License

相关链接

• 项目 GitHub
• Cloudflare Workers 文档
• Google Custom Search API

---

如果这个项目对你有帮助，请在 GitHub 上给我们一个 ⭐️