Elixir SDK | Firecrawl

可在你的 Elixir 应用中抓取单个页面、爬取整个站点，并映射 URL。该 SDK 在运行时通过 NimbleOptions 验证所有参数，并使用 Req 进行 HTTP 请求，因此在真正发出请求之前，你就能清楚发现拼写错误和无效选项。每个函数都有一个 bang (!) 变体，出错时会直接抛出异常，而不是返回 {:error, ...} 元组。

安装

在 mix.exs 的依赖项列表中添加 firecrawl，并配置你的 API 密钥：

Elixir

# 添加到 mix.exs
{:firecrawl, "~> 1.0"}

# 然后在 config.exs 中配置您的 API 密钥
config :firecrawl, api_key: "fc-YOUR-API-KEY"

或者在每次请求中传入 API 密钥：

Elixir

Firecrawl.scrape_and_extract_from_url([url: "https://example.com"], api_key: "fc-YOUR-API-KEY")

使用方式

前往 firecrawl.dev 获取 API 密钥
在应用配置中设置 API 密钥，或将其作为选项传给任意函数。

Elixir

# 抓取网页：
{:ok, scrape_result} = Firecrawl.scrape_and_extract_from_url(
  url: "https://firecrawl.dev",
  formats: ["markdown", "html"]
)
IO.inspect(scrape_result.body)

# 爬取网页：
{:ok, crawl_result} = Firecrawl.crawl_urls(
  url: "https://firecrawl.dev",
  limit: 100,
  scrape_options: [
    formats: ["markdown", "html"]
  ]
)
IO.inspect(crawl_result.body)

抓取 URL

使用 scrape_and_extract_from_url 抓取单个 URL。它会以结构化数据的形式返回页面内容，包括 markdown、元数据以及你指定的其他 formats。

Elixir

# 抓取网站：
{:ok, result} = Firecrawl.scrape_and_extract_from_url(url: "https://firecrawl.dev", formats: ["markdown", "html"])
IO.inspect(result.body)

爬取网站

要爬取网站，请使用 crawl_urls。它接收起始 URL 和可选参数，例如页面上限、允许的域名以及输出格式。

Elixir

{:ok, result} = Firecrawl.crawl_urls(url: "https://docs.firecrawl.dev", limit: 5)
IO.inspect(result.body)

开始爬取

启动一个爬取任务，并立即返回任务 ID，无需阻塞：

Elixir

{:ok, job} = Firecrawl.crawl_urls(url: "https://docs.firecrawl.dev", limit: 10)
crawl_id = job.body["id"]
IO.puts(crawl_id)

查看爬取状态

使用 get_crawl_status 查看爬取任务的状态：

Elixir

{:ok, status} = Firecrawl.get_crawl_status("<crawl-id>")
IO.inspect(status.body)

取消爬取任务

使用 cancel_crawl 取消爬取任务：

Elixir

{:ok, result} = Firecrawl.cancel_crawl("<crawl-id>")
IO.puts("Cancelled: #{inspect(result.body)}")

为网站映射 URL 列表

使用 map_urls 生成网站的 URL 列表：

Elixir

{:ok, result} = Firecrawl.map_urls(url: "https://firecrawl.dev", limit: 10)
IO.inspect(result.body)

搜索

进行网页搜索，并可按需抓取结果：

Elixir

{:ok, result} = Firecrawl.search_and_scrape(query: "firecrawl web scraping", limit: 5)
IO.inspect(result.body["data"]["web"])

批量抓取

在单个批量任务中抓取多个 URL：

Elixir

{:ok, result} = Firecrawl.scrape_and_extract_from_urls(
  urls: ["https://firecrawl.dev", "https://docs.firecrawl.dev"],
  formats: ["markdown"]
)
IO.inspect(result.body)

代理

启动一个代理式数据提取任务：

Elixir

{:ok, job} = Firecrawl.start_agent(
  prompt: "Extract all product names and prices",
  urls: ["https://example.com/products"]
)
job_id = job.body["id"]

# 轮询状态
{:ok, status} = Firecrawl.get_agent_status(job_id)
IO.inspect(status.body)

浏览器

启动云端浏览器会话并远程执行代码。

创建会话

Elixir

{:ok, session} = Firecrawl.create_browser_session(ttl: 600)
session_id = session.body["id"]
cdp_url = session.body["cdpUrl"]
live_view_url = session.body["liveViewUrl"]

执行代码

Elixir

{:ok, result} = Firecrawl.execute_browser_code(session_id,
  code: ~s(await page.goto("https://news.ycombinator.com")\ntitle = await page.title()\nprint(title)),
  language: "python"
)
IO.inspect(result.body)

配置档案

在不同会话间保存并复用浏览器状态 (cookies、localStorage 等) ：

Elixir

{:ok, session} = Firecrawl.create_browser_session(
  ttl: 600,
  profile: [
    name: "my-profile",
    save_changes: true
  ]
)

列出并关闭会话

Elixir

# 列出活跃会话
{:ok, sessions} = Firecrawl.list_browser_sessions(status: "active")
IO.inspect(sessions.body)

# 关闭会话
{:ok, _} = Firecrawl.delete_browser_session(session_id)

自托管实例

要使用自托管的 Firecrawl 实例，请传入 base_url 选项：

Elixir

{:ok, result} = Firecrawl.scrape_and_extract_from_url(
  [url: "https://example.com"],
  base_url: "https://your-instance.com/v2"
)

错误处理

非 bang 版本的函数会返回 {:ok, response} 或 {:error, exception}。Bang 版本在出错时会直接抛出异常。NimbleOptions 会在发送请求前验证所有参数，立即捕获拼写错误、缺少必填字段和类型错误。

Elixir

case Firecrawl.scrape_and_extract_from_url(url: "https://example.com") do
  {:ok, response} -> IO.inspect(response.body)
  {:error, error} -> IO.puts("Error: #{Exception.message(error)}")
end

# 或使用 bang 变体在出错时抛出异常：
response = Firecrawl.scrape_and_extract_from_url!(url: "https://example.com")
IO.inspect(response.body)

所有可用函数

函数	描述
`scrape_and_extract_from_url`	抓取单个 URL
`scrape_and_extract_from_urls`	批量抓取多个 URL
`crawl_urls`	爬取网站
`get_crawl_status`	检查爬取任务状态
`get_crawl_errors`	获取爬取任务错误
`get_active_crawls`	列出正在运行的爬取任务
`cancel_crawl`	取消爬取任务
`map_urls`	映射网站中的 URL
`search_and_scrape`	搜索并抓取结果
`start_agent`	启动代理提取任务
`get_agent_status`	检查代理任务状态
`cancel_agent`	取消代理任务
`create_browser_session`	创建浏览器会话
`execute_browser_code`	在浏览器会话中执行代码
`list_browser_sessions`	列出浏览器会话
`delete_browser_session`	删除浏览器会话
`get_batch_scrape_status`	检查批量抓取状态
`get_batch_scrape_errors`	获取批量抓取错误
`cancel_batch_scrape`	取消批量抓取
`get_credit_usage`	获取剩余额度

上述每个函数都有一个带 bang (!) 的变体 (例如 scrape_and_extract_from_url!) ，它会直接抛出错误，而不是返回错误元组。如需完整的 API 文档，请参见 hexdocs.pm/firecrawl。

概览

官方

Elixir

安装

使用方式

抓取 URL

爬取网站

开始爬取

查看爬取状态

取消爬取任务

为网站映射 URL 列表

搜索

批量抓取

代理

浏览器

创建会话

执行代码

配置档案

列出并关闭会话

自托管实例

错误处理

所有可用函数

​安装

​使用方式

​抓取 URL

​爬取网站

​开始爬取

​查看爬取状态

​取消爬取任务

​为网站映射 URL 列表

​搜索

​批量抓取

​代理

​浏览器

​创建会话

​执行代码

​配置档案

​列出并关闭会话

​自托管实例

​错误处理

​所有可用函数

安装

使用方式

抓取 URL

爬取网站

开始爬取

查看爬取状态

取消爬取任务

为网站映射 URL 列表

搜索

批量抓取

代理

浏览器

创建会话

执行代码

配置档案

列出并关闭会话

自托管实例

错误处理

所有可用函数