# 文档解析 (/zh/features/document-parsing)
Related: [搜索](/zh/features/search.md), [搜索高亮](/zh/features/search-highlights.md), [研究索引](/zh/features/research.md), [抓取](/zh/features/scrape.md), [更快的抓取](/zh/features/fast-scraping.md), [批量抓取](/zh/features/batch-scrape.md)
Firecrawl 提供强大的文档解析能力，支持从多种文档 formats 中提取结构化内容。该功能对处理电子表格、Word 文档等文件尤其实用。
## 支持的文档格式 [#支持的文档格式]
Firecrawl 目前支持以下文档 formats：
* **Excel 电子表格** (`.xlsx`、`.xls`)
* 每个工作表会转换为一个 HTML 表格
* 不同工作表以带有工作表名称的 H2 标题分隔
* 保留单元格格式和数据类型
* **Word 文档** (`.docx`、`.doc`、`.odt`、`.rtf`)
* 在保留文档结构的同时提取文本内容
* 保留标题、段落、列表和表格
* 保留基础格式与样式
* **PDF 文档** (`.pdf`)
* 提取包含布局信息的文本内容
* 保留包括章节与段落在内的文档结构
* 支持处理基于文本的 PDF 和扫描版 PDF (含 OCR)
* 支持通过 `mode` 选项控制解析策略：`fast` (仅文本) 、`auto` (文本并在需要时回退到 OCR，默认) 、`ocr` (强制使用 OCR)
* 费用为每页 1 个积分。详情请参阅 [Pricing](https://firecrawl.dev/pricing)。
### PDF 解析模式 [#pdf-解析模式]
使用 `parsers` 选项来控制 PDF 的解析方式：
| Mode | Description |
| ------ | ---------------------------------------------- |
| `auto` | 优先尝试快速的文本解析，如有需要会回退到 OCR。这是默认模式。 |
| `fast` | 仅进行基于文本的解析（嵌入文本）。这是最快的选项，但无法从扫描件或图片较多的页面中提取文本。 |
| `ocr` | 对每一页都强制使用 OCR 解析。适用于扫描文档，或在 `auto` 误判页面类型时使用。 |
```js
// 带模式的对象语法
parsers: [{ type: "pdf", mode: "ocr", maxPages: 20 }]
// 默认（自动模式）
parsers: [{ type: "pdf" }]
```
## 如何使用文档解析 [#如何使用文档解析]
Firecrawl 的文档解析支持两种方式：
1. **基于 URL 的解析 (`/v2/scrape`)**：提供一个指向受支持文档类型的 URL。
2. **文件上传解析 (`/v2/parse`)**：使用 `multipart/form-data` 直接上传文件字节流。
对于基于 URL 的解析，Firecrawl 会根据文件扩展名或内容类型自动识别文件类型。
### 使用 `/v2/parse` 上传文档 [#使用-v2parse-上传文档]
当源文档存储在本地，或无法通过公开 URL 访问时，请使用 `/v2/parse`。
cURL
Node
Python
```bash
curl -X POST "https://api.firecrawl.dev/v2/parse" \
-H "Authorization: Bearer fc-YOUR-API-KEY" \
-F 'options={"formats":["markdown"]}' \
-F "file=@./document.docx;type=application/vnd.openxmlformats-officedocument.wordprocessingml.document"
```
```js
import { Firecrawl } from "firecrawl";
const app = new Firecrawl({ apiKey: "fc-YOUR-API-KEY" });
const doc = await app.parse(
{
data: "Upload Parse
",
filename: "upload.html",
contentType: "text/html",
},
{ formats: ["markdown"] },
);
console.log(doc.markdown);
```
```python
from firecrawl import Firecrawl
from firecrawl.v2.types import ScrapeOptions
app = Firecrawl(api_key="fc-YOUR-API-KEY")
doc = app.parse(
b"Upload Parse
",
filename="upload.html",
content_type="text/html",
options=ScrapeOptions(formats=["markdown"]),
)
print(doc.markdown)
```
### 示例：爬取 Excel 文件 [#示例爬取-excel-文件]
```js title="Node"
import { Firecrawl } from 'firecrawl';
const firecrawl = new Firecrawl({
// 无需 API 密钥即可开始使用 — 添加一个以获得更高的限流额度：
// apiKey: "fc-YOUR-API-KEY",
});
const doc = await firecrawl.scrape('https://example.com/data.xlsx');
console.log(doc.markdown);
```
### 示例：抓取 Word 文档 [#示例抓取-word-文档]
```js title="Node"
import { Firecrawl } from 'firecrawl';
const firecrawl = new Firecrawl({
// 无需 API 密钥即可开始使用 — 添加一个以获得更高的限流额度：
// apiKey: "fc-YOUR-API-KEY",
});
const doc = await firecrawl.scrape('https://example.com/data.docx');
console.log(doc.markdown);
```
## 输出格式 [#输出格式]
所有受支持的文档类型都会转换为简洁、结构化的 Markdown。比如，一个包含多个工作表的 Excel 文件可能会被转换为：
```markdown
## 工作表1
| 名称 | 数值 |
|-------|-------|
| 项目 1 | 100 |
| 项目 2 | 200 |
## 工作表2
| 日期 | 描述 |
|------------|--------------|
| 2023-01-01 | 第一季度|
```
> 你是需要 Firecrawl API 密钥的 AI 代理吗？请参见 [firecrawl.dev/agent-onboarding/SKILL.md](https://www.firecrawl.dev/agent-onboarding/SKILL.md) 了解自动化接入说明。