Rust - Firecrawl Docs

安装#

官方 Rust SDK 维护在 Firecrawl 的 monorepo 中，位于 apps/rust-sdk。

要安装 Firecrawl Rust SDK，请从 crates.io 添加此依赖：

[dependencies]firecrawl = "2"tokio = { version = "1", features = ["full"] }serde_json = "1"

或通过 Cargo 安装：

cargo add firecrawlcargo add tokio --features fullcargo add serde_json

Note

需要 Rust 1.70 或更高版本。

使用方式#

从 firecrawl.dev 获取 API 密钥
将 API 密钥设置为名为 FIRECRAWL_API_KEY 的环境变量，或直接传给 Client::new(...)

抓取网页并打印其 markdown：

use firecrawl::{Client, ScrapeOptions, Format};#[tokio::main]async fn main() -> Result<(), Box<dyn std::error::Error>> {    let client = Client::new("fc-YOUR-API-KEY")?;    let doc = client.scrape(        "https://firecrawl.dev",        ScrapeOptions {            formats: Some(vec![Format::Markdown]),            ..Default::default()        },    ).await?;    println!("{}", doc.markdown.unwrap_or_default());    Ok(())}

以下各节介绍了爬取、映射、搜索及其他 SDK 方法。

抓取 URL#

要抓取单个 URL，请使用 scrape 方法。

use firecrawl::{Client, ScrapeOptions, Format};let doc = client.scrape(    "https://firecrawl.dev",    ScrapeOptions {        formats: Some(vec![Format::Markdown, Format::Html]),        only_main_content: Some(true),        wait_for: Some(5000),        ..Default::default()    },).await?;println!("{}", doc.markdown.unwrap_or_default());if let Some(meta) = &doc.metadata {    println!("{:?}", meta.title);}

JSON 提取#

使用 scrape_with_schema 提取结构化 JSON：

use firecrawl::Client;use serde_json::json;let schema = json!({    "type": "object",    "properties": {        "name": { "type": "string" },        "price": { "type": "number" }    }});let data = client.scrape_with_schema(    "https://example.com/product",    schema,    Some("Extract the product name and price"),).await?;println!("{}", serde_json::to_string_pretty(&data)?);

也可以直接通过 ScrapeOptions 配置 JSON 提取：

use firecrawl::{Client, ScrapeOptions, Format, JsonOptions};use serde_json::json;let doc = client.scrape(    "https://example.com/product",    ScrapeOptions {        formats: Some(vec![Format::Json]),        json_options: Some(JsonOptions {            schema: Some(json!({                "type": "object",                "properties": {                    "name": { "type": "string" },                    "price": { "type": "number" }                }            })),            prompt: Some("Extract the product name and price".to_string()),            ..Default::default()        }),        ..Default::default()    },).await?;println!("{:?}", doc.json);

解析上传的文件#

使用 parse 将本地文件 (.html、.htm、.pdf、.docx、.doc、.odt、.rtf、.xlsx、.xls) 以 multipart form data 的形式上传到 /v2/parse。该 endpoint 会返回一个包含所请求 formats 的 Document。

ParseOptions 刻意省略了仅适用于抓取、且会被 /v2/parse 拒绝的字段 (例如 actions、waitFor、location、mobile、screenshot、branding 和 changeTracking) 。

可以通过内存中的字节数据或直接通过路径构建 ParseFile：

use firecrawl::{Client, ParseFile, ParseFormat, ParseOptions};#[tokio::main]async fn main() -> Result<(), Box<dyn std::error::Error>> {    let client = Client::new("fc-YOUR-API-KEY")?;    let file = ParseFile::from_bytes(        "upload.html",        b"<!DOCTYPE html><html><body><h1>Rust Parse</h1></body></html>".to_vec(),    )    .with_content_type("text/html");    let options = ParseOptions {        formats: Some(vec![ParseFormat::Markdown, ParseFormat::Html]),        only_main_content: Some(true),        ..Default::default()    };    let doc = client.parse(file, Some(options)).await?;    println!("{}", doc.markdown.unwrap_or_default());    Ok(())}

或者直接从磁盘读取文件，不传入选项：

use firecrawl::{Client, ParseFile};let client = Client::new("fc-YOUR-API-KEY")?;let file = ParseFile::from_path("./report.pdf")?;let doc = client.parse(file, None).await?;println!("{}", doc.markdown.unwrap_or_default());

`ParseFile`#

构造函数	描述
`ParseFile::from_bytes(filename, bytes)`	通过文件名和内存中的字节数据构建
`ParseFile::from_path(path)`	从磁盘读取字节数据，并从路径中提取文件名
`.with_content_type(content_type)`	附加 MIME 类型提示 (例如 `text/html`、`application/pdf`)

`ParseOptions`#

支持的字段 (均为可选，请求传输时使用 camelCase) ：

formats: Vec<ParseFormat> — 可为以下任意值：Markdown、Html、RawHtml、Links、Images、Summary、Json、Attributes
only_main_content: bool
include_tags: Vec<String> / exclude_tags: Vec<String>
headers: HashMap<String, String>
timeout: u32 (毫秒)
parsers: Vec<ParserConfig> (例如 PDF 解析器配置)
skip_tls_verification: bool
remove_base64_images: bool
fast_mode: bool
block_ads: bool
proxy: ParseProxyType (Basic 或 Auto)
json_options: JsonOptions
attribute_selectors: Vec<AttributeSelector>
zero_data_retention: bool
integration: String, origin: String, use_mock: String

爬取网站#

如需爬取网站并等待完成，请使用 crawl。

use firecrawl::{Client, CrawlOptions, ScrapeOptions, Format};let job = client.crawl(    "https://firecrawl.dev",    CrawlOptions {        limit: Some(50),        max_discovery_depth: Some(3),        scrape_options: Some(ScrapeOptions {            formats: Some(vec![Format::Markdown]),            ..Default::default()        }),        ..Default::default()    },).await?;println!("Status: {:?}", job.status);println!("Progress: {}/{}", job.completed, job.total);for page in &job.data {    if let Some(meta) = &page.metadata {        println!("{:?}", meta.source_url);    }}

开始爬取#

使用 start_crawl 启动任务，无需等待。

use firecrawl::{Client, CrawlOptions};let start = client.start_crawl(    "https://firecrawl.dev",    CrawlOptions {        limit: Some(100),        ..Default::default()    },).await?;println!("Job ID: {}", start.id);

查看爬取状态#

使用 get_crawl_status 查看爬取进度。

let status = client.get_crawl_status(&start.id).await?;println!("Status: {:?}", status.status);println!("Progress: {}/{}", status.completed, status.total);

取消爬取#

使用 cancel_crawl 取消正在进行的爬取。

let result = client.cancel_crawl(&start.id).await?;println!("{:?}", result);

检查爬取错误#

使用 get_crawl_errors 获取爬取任务中的错误。

let errors = client.get_crawl_errors(&start.id).await?;println!("{:?}", errors);

网站映射#

使用 map 发现网站中的链接。

use firecrawl::{Client, MapOptions};let response = client.map(    "https://firecrawl.dev",    MapOptions {        limit: Some(100),        search: Some("blog".to_string()),        ..Default::default()    },).await?;for link in &response.links {    println!("{} - {}", link.url, link.title.as_deref().unwrap_or(""));}

若只需返回 URL 的简化结果，请使用 map_urls：

let urls = client.map_urls("https://firecrawl.dev", None).await?;for url in &urls {    println!("{}", url);}

搜索网页#

使用 search 并结合可选设置进行搜索。

use firecrawl::{Client, SearchOptions};let results = client.search(    "firecrawl web scraping",    SearchOptions {        limit: Some(10),        ..Default::default()    },).await?;if let Some(web) = results.data.web {    for item in web {        match item {            firecrawl::SearchResultOrDocument::WebResult(r) => {                println!("{} - {}", r.url, r.title.unwrap_or_default());            }            firecrawl::SearchResultOrDocument::Document(d) => {                println!("{}", d.markdown.unwrap_or_default());            }        }    }}

如需使用可直接返回抓取到的文档的便捷方法：

let docs = client.search_and_scrape("firecrawl web scraping", 5).await?;for doc in &docs {    println!("{}", doc.markdown.as_deref().unwrap_or(""));}

批量抓取#

通过 batch_scrape 并行抓取多个 URL。

use firecrawl::{Client, BatchScrapeOptions, ScrapeOptions, Format};let urls = vec![    "https://firecrawl.dev".to_string(),    "https://firecrawl.dev/blog".to_string(),];let job = client.batch_scrape(    urls,    BatchScrapeOptions {        options: Some(ScrapeOptions {            formats: Some(vec![Format::Markdown]),            ..Default::default()        }),        ..Default::default()    },).await?;for doc in &job.data {    println!("{}", doc.markdown.as_deref().unwrap_or(""));}

代理#

使用 agent 运行 AI 代理。

use firecrawl::{Client, AgentOptions};let result = client.agent(    AgentOptions {        prompt: "Find the pricing plans for Firecrawl and compare them".to_string(),        ..Default::default()    },).await?;println!("{:?}", result.data);

使用 JSON schema 实现结构化输出：

use firecrawl::{Client, AgentOptions, AgentModel};use serde::Deserialize;use serde_json::json;#[derive(Debug, Deserialize)]struct PricingPlan {    name: String,    price: String,}#[derive(Debug, Deserialize)]struct PricingData {    plans: Vec<PricingPlan>,}let schema = json!({    "type": "object",    "properties": {        "plans": {            "type": "array",            "items": {                "type": "object",                "properties": {                    "name": { "type": "string" },                    "price": { "type": "string" }                }            }        }    }});let result: Option<PricingData> = client.agent_with_schema(    vec!["https://firecrawl.dev".to_string()],    "Extract pricing plan details",    schema,).await?;if let Some(data) = result {    for plan in &data.plans {        println!("{}: {}", plan.name, plan.price);    }}

与抓取任务绑定的交互式会话#

使用抓取任务 ID，可在同一上下文中运行后续浏览器代码：

interact(...) 会在与抓取任务绑定的浏览器会话中运行代码或 prompt。
stop_interaction(...) 会在你完成后停止交互式会话。

use firecrawl::{Client, ScrapeExecuteOptions, ScrapeExecuteLanguage};let scrape_job_id = "550e8400-e29b-41d4-a716-446655440000";// 在浏览器会话中运行代码let run = client.interact(    scrape_job_id,    ScrapeExecuteOptions {        code: Some("console.log(await page.title())".to_string()),        language: Some(ScrapeExecuteLanguage::Node),        timeout: Some(60),        ..Default::default()    },).await?;println!("{:?}", run.stdout);// 或使用自然语言 promptlet run = client.interact(    scrape_job_id,    ScrapeExecuteOptions {        prompt: Some("Click the pricing tab and summarize the plans".to_string()),        ..Default::default()    },).await?;// 完成后停止会话client.stop_interaction(scrape_job_id).await?;

配置#

Client::new(...) 和 Client::new_selfhosted(...) 用于创建客户端。

选项	描述
`Client::new(api_key)`	为 Firecrawl 云服务 (`https://api.firecrawl.dev`) 创建客户端
`Client::new_selfhosted(api_url, api_key)`	为自托管 Firecrawl 实例创建客户端

use firecrawl::Client;// 云服务let client = Client::new("fc-your-api-key")?;// 自托管let client = Client::new_selfhosted(    "http://localhost:3002",    Some("fc-your-api-key"),)?;// 自托管（无需身份验证）let client = Client::new_selfhosted(    "http://localhost:3002",    None::<&str>,)?;

环境变量#

请设置 FIRECRAWL_API_KEY 环境变量，而不要直接传入密钥：

export FIRECRAWL_API_KEY=fc-YOUR-API-KEY

let api_key = std::env::var("FIRECRAWL_API_KEY")    .expect("FIRECRAWL_API_KEY must be set");let client = Client::new(api_key)?;

轮询间隔#

同步方法 (crawl、batch_scrape、agent) 会轮询直到完成。你可以通过 options 结构体自定义轮询间隔：

use firecrawl::CrawlOptions;let options = CrawlOptions {    limit: Some(50),    poll_interval: Some(3000), // 每 3 秒轮询一次（默认值：2000ms）    ..Default::default()};

错误处理#

SDK 使用 FirecrawlError 枚举，该枚举实现了 Error、Debug 和 Display 接口。所有方法都返回 Result<T, FirecrawlError>。

use firecrawl::{Client, FirecrawlError};match client.scrape("https://example.com", None).await {    Ok(doc) => println!("{}", doc.markdown.unwrap_or_default()),    Err(FirecrawlError::HttpRequestFailed(action, status, msg)) => {        eprintln!("HTTP {}: {} ({})", status, msg, action);    }    Err(FirecrawlError::APIError(action, api_err)) => {        eprintln!("API error ({}): {}", action, api_err.error);    }    Err(FirecrawlError::JobFailed(msg)) => {        eprintln!("Job failed: {}", msg);    }    Err(FirecrawlError::Misuse(msg)) => {        eprintln!("SDK misuse: {}", msg);    }    Err(e) => eprintln!("Error: {}", e),}

如果你是需要 Firecrawl API 密钥的 AI 代理，请参阅 firecrawl.dev/agent-onboarding/SKILL.md 获取自动化接入说明。

安装#

使用方式#

抓取 URL#

JSON 提取#

解析上传的文件#

ParseFile#

ParseOptions#

爬取网站#

开始爬取#

查看爬取状态#

取消爬取#

检查爬取错误#

网站映射#

搜索网页#

批量抓取#

代理#

与抓取任务绑定的交互式会话#

配置#

环境变量#

轮询间隔#

错误处理#

`ParseFile`#

`ParseOptions`#