跳转到主要内容

​
安装

官方 .NET SDK 由 Firecrawl monorepo 中的 apps/.net-sdk 维护。 要安装 Firecrawl .NET SDK，请添加以下 NuGet 包：
bash dotnet add package firecrawl-sdk
需要 .NET 8.0 或更高版本。

​
使用方式

  1. 从 firecrawl.dev 获取 API 密钥
  2. 将 API 密钥设置为名为 FIRECRAWL_API_KEY 的环境变量，或在 FirecrawlClient 构造函数中传入该密钥
下面是一个基于当前 SDK API 的快速示例： 
using Firecrawl;
using Firecrawl.Models;

var client = new FirecrawlClient("fc-your-api-key");

// 抓取单个页面
var doc = await client.ScrapeAsync("https://firecrawl.dev",
    new ScrapeOptions { Formats = new List<object> { "markdown" } });

// 爬取网站
var job = await client.CrawlAsync("https://firecrawl.dev",
    new CrawlOptions { Limit = 5 });

Console.WriteLine(doc.Markdown);
Console.WriteLine($"Crawled pages: {job.Data?.Count ?? 0}");

​
抓取单个 URL

要抓取单个 URL，请使用 ScrapeAsync 方法。 
using Firecrawl.Models;

var doc = await client.ScrapeAsync("https://firecrawl.dev",
    new ScrapeOptions
    {
        Formats = new List<object> { "markdown", "html" },
        OnlyMainContent = true,
        WaitFor = 5000
    });

Console.WriteLine(doc.Markdown);
Console.WriteLine(doc.Metadata?["title"]);

​
JSON 提取

通过 scrape 端点使用 JsonFormat 提取结构化 JSON： 
using Firecrawl.Models;

var jsonFmt = new JsonFormat
{
    Prompt = "Extract the product name and price",
    Schema = new Dictionary<string, object>
    {
        ["type"] = "object",
        ["properties"] = new Dictionary<string, object>
        {
            ["name"] = new Dictionary<string, object> { ["type"] = "string" },
            ["price"] = new Dictionary<string, object> { ["type"] = "number" }
        }
    }
};

var doc = await client.ScrapeAsync("https://example.com/product",
    new ScrapeOptions
    {
        Formats = new List<object> { jsonFmt }
    });

Console.WriteLine(doc.Json);

​
爬取网站

要爬取网站并等待其完成，请使用 CrawlAsync。该方法会自动处理轮询和分页。 
using Firecrawl.Models;

var job = await client.CrawlAsync("https://firecrawl.dev",
    new CrawlOptions
    {
        Limit = 50,
        MaxDiscoveryDepth = 3,
        ScrapeOptions = new ScrapeOptions
        {
            Formats = new List<object> { "markdown" }
        }
    });

Console.WriteLine($"Status: {job.Status}");
Console.WriteLine($"Progress: {job.Completed}/{job.Total}");

if (job.Data != null)
{
    foreach (var page in job.Data)
    {
        Console.WriteLine(page.Metadata?["sourceURL"]);
    }
}

​
开始爬取

使用 StartCrawlAsync 异步启动任务，无需等待。 
using Firecrawl.Models;

var start = await client.StartCrawlAsync("https://firecrawl.dev",
    new CrawlOptions { Limit = 100 });

Console.WriteLine($"Job ID: {start.Id}");

​
检查爬取状态

使用 GetCrawlStatusAsync 查看爬取进度。 
var status = await client.GetCrawlStatusAsync(start.Id!);
Console.WriteLine($"Status: {status.Status}");
Console.WriteLine($"Progress: {status.Completed}/{status.Total}");

​
取消爬取

使用 CancelCrawlAsync 取消正在运行中的爬取任务。 
var result = await client.CancelCrawlAsync(start.Id!);
Console.WriteLine(result);

​
网站映射

使用 MapAsync 发现网站中的链接。 
using Firecrawl.Models;

var data = await client.MapAsync("https://firecrawl.dev",
    new MapOptions
    {
        Limit = 100,
        Search = "blog"
    });

if (data.Links != null)
{
    foreach (var link in data.Links)
    {
        Console.WriteLine(link);
    }
}

​
搜索网页

使用 SearchAsync 并可选配搜索设置进行搜索。 
using Firecrawl.Models;

var results = await client.SearchAsync("firecrawl web scraping",
    new SearchOptions
    {
        Limit = 10,
        Location = "US"
    });

if (results.Web != null)
{
    foreach (var hit in results.Web)
    {
        Console.WriteLine($"{hit.Title} - {hit.Url}");
    }
}

​
批量抓取

使用 BatchScrapeAsync 可并行抓取多个 URL。该方法会自动处理轮询和分页。 
using Firecrawl.Models;

var urls = new List<string>
{
    "https://firecrawl.dev",
    "https://firecrawl.dev/blog"
};

var job = await client.BatchScrapeAsync(urls,
    new BatchScrapeOptions
    {
        Options = new ScrapeOptions
        {
            Formats = new List<object> { "markdown" }
        }
    });

if (job.Data != null)
{
    foreach (var doc in job.Data)
    {
        Console.WriteLine(doc.Markdown);
    }
}

​
使用幂等键执行批量抓取

为确保不会处理重复请求，请传入 IdempotencyKey： 
var job = await client.BatchScrapeAsync(urls,
    new BatchScrapeOptions
    {
        IdempotencyKey = "my-unique-key",
        Options = new ScrapeOptions
        {
            Formats = new List<object> { "markdown" }
        }
    });

​
使用方式与指标

查看并发数和剩余额度： 
using Firecrawl.Models;

var concurrency = await client.GetConcurrencyAsync();
Console.WriteLine($"Concurrency: {concurrency.Current}/{concurrency.MaxConcurrency}");

var credits = await client.GetCreditUsageAsync();
Console.WriteLine($"Remaining credits: {credits.RemainingCredits}");

​
异步支持

.NET SDK 中的所有方法默认均为异步，并返回 Task<T>。它们支持通过 CancellationToken 进行协作取消。 
using Firecrawl.Models;

using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(30));

var doc = await client.ScrapeAsync("https://example.com",
    new ScrapeOptions
    {
        Formats = new List<object> { "markdown" }
    },
    cancellationToken: cts.Token);

Console.WriteLine(doc.Markdown);

​
配置

FirecrawlClient 构造函数支持以下选项：
选项类型默认值描述
apiKeystring?FIRECRAWL_API_KEY 环境变量您的 Firecrawl API 密钥
apiUrlstring?https://api.firecrawl.dev (或 FIRECRAWL_API_URL)API 基础 URL
timeoutTimeSpan?5 分钟HTTP 请求超时
maxRetriesint3发生瞬时故障时自动重试
backoffFactordouble0.5以秒为单位的指数退避系数
httpClientHttpClient?根据 timeout 构建预先配置的 HttpClient 实例
using Firecrawl;

var client = new FirecrawlClient(
    apiKey: "fc-your-api-key",
    apiUrl: "https://api.firecrawl.dev",
    timeout: TimeSpan.FromMinutes(5),
    maxRetries: 3,
    backoffFactor: 0.5);

​
自定义 HTTP 客户端

你可以传入一个预先配置好的 HttpClient，以控制连接池、代理、消息处理程序以及 HttpClient 的其他功能。提供后，将忽略 timeout 设置，改为使用该客户端自身的配置。 
using Firecrawl;

var handler = new HttpClientHandler
{
    Proxy = new WebProxy("http://proxy.example.com:8080"),
    UseProxy = true
};

var httpClient = new HttpClient(handler)
{
    Timeout = TimeSpan.FromSeconds(60)
};

var client = new FirecrawlClient(
    apiKey: "fc-your-api-key",
    httpClient: httpClient);

​
环境变量配置

当省略构造函数参数时，SDK 会从环境变量中获取配置： 
// 使用 FIRECRAWL_API_KEY 和 FIRECRAWL_API_URL 环境变量
var client = new FirecrawlClient();

​
错误处理

SDK 会抛出 Firecrawl.Exceptions 下定义的特定异常。 
using Firecrawl.Exceptions;
using Firecrawl.Models;

try
{
    var doc = await client.ScrapeAsync("https://example.com");
}
catch (AuthenticationException ex)
{
    Console.Error.WriteLine($"Auth failed: {ex.Message}");
}
catch (RateLimitException ex)
{
    Console.Error.WriteLine($"Rate limited: {ex.Message}");
}
catch (JobTimeoutException ex)
{
    Console.Error.WriteLine($"Job {ex.JobId} timed out after {ex.TimeoutSeconds}s");
}
catch (FirecrawlException ex)
{
    Console.Error.WriteLine($"Error {ex.StatusCode}: {ex.Message}");
}
异常层级：
ExceptionHTTP Code触发时机
AuthenticationException401API 密钥无效或缺失
RateLimitException429请求过多
JobTimeoutException—异步任务 (爬取/批量抓取) 未能在规定时间内完成
FirecrawlExceptionvaries其他所有 API 错误的基础异常
在抛出异常之前，瞬时故障 (408、409、502 和其他 5xx 错误) 会先以指数退避方式自动重试。
你是需要 Firecrawl API 密钥的 AI 代理吗？请参见 firecrawl.dev/agent-onboarding/SKILL.md 了解自动化接入说明。