在本指南中，你将看到：

将网站爬虫为 Markdown 的含义，以及为什么这很有用。
将网页 HTML 转换为 Markdown 的主要方法，适用于静态和动态网站。
如何使用 Python 将网页爬虫为 Markdown。
此解决方案的局限性，以及如何使用 Bright Data 克服这些局限。

让我们深入了解！

“将网站爬虫为 Markdown”是什么意思？

“将网站爬虫为 Markdown”意味着将其内容转换为 Markdown。
更具体地说，它指的是获取网页的 HTML，并将其转换为 Markdown 数据格式。

例如，连接到一个网站，打开 DevTools，并复制其 HTML：

然后将其粘贴到一个 HTML 转 Markdown 转换器中：

输出将类似于你想要通过网页爬虫获得的 Markdown 文档。现在目标是自动化这个过程，而这正是本文的内容！

[额外] 为什么选择 Markdown？

为什么选择 Markdown 而不是其他格式（比如纯文本）？因为，如我们的数据格式基准测试所示，Markdown 是最适合 LLM 摄取的格式之一。前三个原因是：

它保留了页面的大部分结构和信息（例如，链接、图片、标题等）。
它很简洁，带来有限的 token 使用量和更快的 AI 处理速度。
LLM 往往比纯 HTML 更能理解 Markdown。

这就是为什么最佳 AI 爬虫工具默认使用 Markdown。

HTML 转 Markdown 方法

你现在知道，将网站爬取为 Markdown 仅仅意味着将其页面的 HTML 转换为 Markdown。从高层次来看，该过程如下所示：

连接到网站。
以字符串形式检索 HTML。
使用 HTML 转 Markdown 库生成 Markdown 输出。

挑战在于，并非所有网页都以相同方式交付。前两个步骤可能会根据目标页面是静态还是动态而显著不同。让我们通过扩展所需步骤来探索如何处理这两种场景！

步骤 #1：连接到网站

在静态网页上，服务器返回的 HTML 文档正是你在浏览器中看到的内容。换句话说，一切都是固定的，并嵌入在服务器生成的 HTML 中。

在这种情况下，检索 HTML 很简单。你只需要使用任何 HTTP 客户端对页面的 URL 执行一次 GET HTTP 请求：

相比之下，在动态网站上，大部分（或一部分）内容是通过 AJAX 检索的，并通过 JavaScript 在浏览器中渲染。这意味着 Web 服务器返回的初始 HTML 文档只包含最基本的内容。只有在 JavaScript 在客户端执行后，页面才会填充完整内容：

在这种情况下，你不能仅使用简单的 HTTP 客户端获取 HTML。相反，你需要一个能够实际渲染页面的工具，例如浏览器自动化工具。Playwright、Puppeteer 或 Selenium 等解决方案使你能够以编程方式控制浏览器来加载目标页面并获取其完全渲染后的 HTML。

步骤 #2：以字符串形式检索 HTML

对于静态网页，此步骤很直接。Web 服务器对你的 GET 请求的响应已经包含完整的 HTML 文档字符串。大多数 HTTP 客户端，如 Python 的 Requests，都提供了直接访问它的方法或字段：

url = "https://quotes.toscrape.com/"
response = requests.get(url)

# Access the HTML content of the page as a string
html = response.text

对于动态网站，事情要棘手得多。这一次，你感兴趣的不是服务器返回的原始 HTML 文档。相反，你需要等到浏览器渲染页面、DOM 稳定，然后再访问最终的 HTML。

这对应于你通常手动打开 DevTools 并从 <html> 节点复制 HTML 的操作：

挑战在于知道页面何时完成渲染。常见策略包括：

等待 DOMContentLoaded 事件：在初始 HTML 被解析且延迟的 <script> 已加载并执行时触发。等待此事件是 Playwright 的默认行为。
等待 load 事件：在整个页面已加载时触发，包括样式表、脚本、iframe 和图片（懒加载的除外）。
等待 networkidle 事件：当在给定持续时间内没有网络请求时（例如 Playwright 中的 500ms），认为渲染已完成。对于带有实时更新内容的网站，这并不可靠，因为它永远不会触发。
等待特定元素：使用浏览器自动化框架提供的自定义等待 API，等待某些元素出现在 DOM 中。

页面完全渲染后，你可以使用浏览器自动化工具提供的特定方法/字段提取 HTML。例如，在 Playwright 中：

html = await page.content()

步骤 #3：使用 HTML 转 Markdown 库生成 Markdown 输出

一旦你以字符串形式检索到 HTML，就只需将其传给众多可用的 HTML 转 Markdown 库之一。最流行的是：

库	编程语言	GitHub 星标
`markdownify`	Python	1.8k+
`turndown`	JavaScript/Node.js	10k+
`Html2Markdown`	C#	300+
`commonmark-java`	Java	2.5k+
`html-to-markdown`	Go	3k+
`html-to-markdown`	PHP	1.8k+

将网站爬虫为 Markdown：实用 Python 示例

在本节中，你将看到完整的 Python 代码片段，用于将网站抓取为 Markdown。下面的脚本将实现前面解释的步骤。请注意，你可以轻松地将该逻辑转换为 JavaScript 或任何其他编程语言。

输入将是网页的 URL，输出将是对应的 Markdown 内容！

静态网站

在此示例中，我们将使用以下两个库：

requests：用于发出 GET 请求并以字符串形式获取页面 HTML。
markdownify：用于将页面的 HTML 转换为 Markdown。

使用以下命令安装它们：

pip install requests markdownify

目标页面将是静态的“待抓取的名言”页面。你可以使用以下代码片段实现目标：

import requests
from markdownify import markdownify as md

# The URL of the page to scrape
url = "http://quotes.toscrape.com/"

# Retrieve the HTML content using requests
response = requests.get(url)
# Get the HTML as a string
html_content = response.text

# Convert the HTML content to Markdown
markdown_content = md(html_content)

# Print the Markdown output
print(markdown_content)

可选地，你可以使用以下方式将内容导出到 .md 文件：

with open("page.md", "w", encoding="utf-8") as f:
    f.write(markdown_content)

脚本的结果将是：

如果你复制输出 Markdown 并将其粘贴到 Markdown 渲染器中，你将看到：

注意这看起来像是来自“待抓取的名言”页面的原始内容的简化版本：

任务完成！

动态网站

在这里，我们将使用这两个库：

playwright：用于在受控浏览器实例中渲染目标页面。
markdownify：用于将页面渲染后的 DOM 转换为 Markdown。

使用以下命令安装上述两个依赖项：

pip install playwright markdownify

然后，使用以下命令完成 Playwright 安装：

python -m playwright install

目标将是 ScrapingCourse.com 网站上的动态“JavaScript 渲染”页面：

该页面通过 AJAX 在客户端检索数据，并使用 JavaScript 进行渲染：

按如下方式将动态网站抓取为 Markdown：

from playwright.sync_api import sync_playwright
from markdownify import markdownify as md

with sync_playwright() as p:
    # Launch a headless browser
    browser = p.chromium.launch()
    page = browser.new_page()

    # URL of the dynamic page
    url = "https://scrapingcourse.com/javascript-rendering"
    # Navigate to the page
    page.goto(url)

    # Wait up to 5 seconds for the first product link element to be filled out
    page.locator('.product-link:not([href=""])').first.wait_for(timeout=5000)

    # Get the fully rendered HTML
    rendered_html = page.content()

    # Convert HTML to Markdown
    markdown_content = md(rendered_html)

    # Print the resulting Markdown
    print(markdown_content)

    # Close the browser and release its resources
    browser.close()

在上面的代码片段中，我们选择了选项 4（“等待特定元素”），因为它最可靠。具体来说，请看这行代码：

page.locator('.product-link:not([href=""])').first.wait_for(timeout=5000)

这会最多等待 5000 毫秒（5 秒），直到 .product-link 元素（一个 <a> 标签）具有非空的 href 属性。这足以表明页面上的第一个产品元素已经渲染，这意味着数据已被检索，DOM 现在已经稳定。

结果将是：

Et voilà！你刚刚学会了如何将网站爬虫为 Markdown。

这些方法的局限性和解决方案

本博客文章中的所有示例都有一个共同的基本方面：它们指的是被设计为易于抓取的页面！

不幸的是，大多数真实世界的网页并不那么欢迎网页爬虫机器人。恰恰相反，许多网站会实施反抓取保护，例如 CAPTCHA、IP 封禁、浏览器指纹识别等。

换句话说，你不能期望简单的 HTTP 请求或 Playwright goto() 指令按预期工作。当目标是大多数真实世界网站时，你可能会遇到 403 Forbidden 错误：

或错误 / 人机验证页面：

另一个需要考虑的关键方面是，大多数 HTML 转 Markdown 库执行的是原始数据转换。这可能导致不希望出现的结果。例如，如果页面包含直接嵌入在 HTML 中的 <style> 或 <script> 元素，它们的内容（即分别为 CSS 和 JavaScript 代码）将被包含在 Markdown 输出中：

这通常是不需要的，特别是如果你计划将 Markdown 提供给 LLM 进行数据处理。毕竟，这些文本元素只会增加噪音。

解决方案？依赖专用的 网络解锁器 API，它可以访问任何网站，无论其保护措施如何，并生成适用于 LLM 的 Markdown。这确保提取的内容干净、结构化，并为下游 AI 任务做好准备。

使用网络解锁器爬虫为 Markdown

Bright Data 的网络解锁器是一个基于云的网页爬虫工具 API，可以返回任何网页的 HTML。无论是否存在反爬虫或反机器人保护，也无论页面是静态还是动态，都是如此。

该 API 由一个超过 1.5 亿 IP 的代理网络提供支持，使你能够专注于数据收集，而 Bright Data 负责完整的解锁基础设施、JavaScript 渲染、CAPTCHA 破解、扩展和维护更新。

使用它很简单。使用正确参数向网络解锁器发出 POST HTTP 请求，你就会取回完全解锁的网页。你还可以配置该 API 以返回 LLM 优化的 Markdown 格式内容。

按照初始设置指南，然后只需几行代码即可使用网络解锁器将网站爬虫为 Markdown：

# pip install requests

import requests

# Replace these with the right values from your Bright Data account
BRIGHT_DATA_API_KEY= "<YOUR_BRIGHT_DATA_API_KEY>"
WEB_UNLOCKER_ZONE = "<YOUR_WEB_UNLOCKER_ZONE_NAME>"

# Replace with your target URL
url_to_scrape = "https://www.g2.com/products/bright-data/reviews"

# Prepare the required headers
headers = {
    "Authorization": f"Bearer {BRIGHT_DATA_API_KEY}", # For authentication
    "Content-Type": "application/json"
}

# Prepare the Web Unlocker POST payload
payload = {
    "url": url_to_scrape,
    "zone": WEB_UNLOCKER_ZONE,
    "format": "raw",
    "data_format": "markdown" # To get the response as Markdown content
}

# Make a POST request to Bright Data Web Unlocker API
response = requests.post(
    "https://api.brightdata.com/request", 
    json=payload, 
    headers=headers
)

# Get the Markdown response and print it
markdown_content = response.text
print(markdown_content)

执行脚本后，你将得到：