核心用法
brave-headless 是一款面向开发者的无头网页搜索与内容提取工具，通过 Brave Search API 实现无需浏览器的自动化网络研究。主要包含两大功能模块：
- 搜索模块 (
search.js): 支持基础搜索、结果数量控制（1-20条）、页面内容自动抓取，输出格式可选纯文本或 JSON Lines - 内容提取模块 (
content.js): 直接提取指定URL的网页内容，转换为 Markdown 格式，支持长度限制与 JSON 输出
显著优点
1. 企业级可靠性设计: 内置指数退避重试机制（指数退避+全抖动）、熔断器模式（CLOSED→OPEN→HALF_OPEN状态机）、边界并发控制（默认3并行），有效应对网络抖动和服务降级
2. 零浏览器依赖: 基于 Node.js + Readability + JSDOM 实现服务端渲染提取，资源占用远低于 Puppeteer/Playwright
3. 结构化可观测性: 支持五级日志级别（debug/info/warn/error/silent）及 JSON 格式结构化输出，便于接入日志系统
4. 配置即代码: 12 个环境变量全覆盖运行时行为，启动时 Schema 校验确保配置错误立即暴露而非运行时崩溃
5. 输出管道友好: JSON Lines 格式天然支持 Unix 管道处理，便于下游数据处理
潜在局限
- 依赖单一搜索源: 仅支持 Brave Search API，无多源聚合能力；API 配额或稳定性直接影响功能
- 内容提取覆盖率: 基于 Mozilla Readability 算法，对单页应用(SPA)、重度 JavaScript 渲染的现代站点提取效果有限
- Node.js 版本限制: 要求 >=20 版本，旧环境兼容性受限
- 无身份认证支持: 无法处理需要登录态或 Cookie 的站点内容
适合人群
- 需要批量网页数据采集的数据工程师与研究员
- 构建 AI Agent/RAG 系统的开发者（知识库自动扩充场景）
- 注重资源效率、追求 CI/CD 友好的自动化流水线用户
常规风险
- API 密钥泄露:
BRAVE_API_KEY为唯一凭证，需妥善管理；工具本身无密钥轮转机制 - 目标站点反爬: 高频请求可能触发 Brave 速率限制或目标站点封禁，需配合
CONCURRENCY_LIMIT与重试参数调优 - 内容版权合规: 自动提取网页内容需遵守目标站点 robots.txt 及版权声明
- 依赖供应链: 依赖
@mozilla/readability、jsdom、turndown等 npm 包，需关注供应链安全更新