周一至周五 09:00 - 18:00（UTC+08:00） 
©2026 NST LABS TECH LTD. 保留所有权利。Marcus ChenProduct & Network Architect
通过单个 API 请求爬取整个网站
TL;DR
- 您可以使用一个
POST /api/v1/crawl 请求提交整个网站的爬取到 Nstproxy Crawl。该请求会启动一个异步作业；之后仍需进行轮询和分页结果检索。
- 安全的全站爬取是有界限的，而非字面上的无限制。设置
maxDepth、maxPages，包含/排除 URL 模式、查询处理、输出格式和在爬虫跟随链接之前的超时。
- 深度和页面限制解决不同的问题。深度限制爬虫可以通过的链接跳数；页面计数即使在链接图较宽时也限制总工作量。
- 规范化和陷阱决定数据质量。日历路径、分面导航、跟踪参数、重定向和重复规范可能会在达到有价值页面之前消耗大量爬取。
- 将完成视为数据集质量事件。检查已完成、待处理和失败的计数；分页每个结果页面；去重；并验证覆盖率与网站地图或已知 URL 集合的比较。
“整个网站”很少是一个有限的、干净的列表。一个域名可以展示数百万的参数组合、日历链接、搜索页面、本地化重复项和 JavaScript 路由。因此，一个有用的爬取需要一个起始 URL 以及明确的边界。
Nstproxy Crawl 将发现、页面检索、渲染、提取、代理路由、任务状态和工件存储打包在一个API后面。本教程提交一个有界网站作业，控制范围，轮询状态，检索每个结果页面，并检查完成的数据集是否足够完整以供其预定使用。
Nstproxy Crawl 从一个 URL 开始，发现同站链接，并根据请求中的限制处理符合条件的页面。提交返回一个任务标识符，而不是在整个网站完成之前保持 HTTP 连接打开。
“单个 API 请求”这一术语适用于作业提交。生产客户端必须随后调用状态和页面结果端点。这样的异步设计是合适的，因为整个网站可能需要比正常请求超时更长的时间，并且可能会生成一个分页数据集。
当前的 Nstproxy Crawl 文档 确定了这些站点级控件：
| 控件 | 目的 |
|---|
url | 发现开始的种子 URL |
formats | 请求的页面工件，如 Markdown 或 HTML |
maxDepth | 与种子的最大链接距离 |
maxPages | 处理的最大页面数 |
includeUrls | 允许进入爬取的模式 |
excludeUrls |
onlyMainContent | 主要集中提取页面内容 |
为什么爬取整个网站很难
全站爬取很难，因为网站暴露的是图形，而不是目录。爬虫必须决定哪些发现的 URL 代表新内容，哪些是重复的，以及哪些进入无限或低价值的空间。
- 带有“下个月”链接的日历，这些链接永无止境；
- 产品过滤器，其组合成倍增加；
- 会话、推荐、跟踪和排序参数；
- 打印视图和替代手机 URL；
- 语言和区域镜像；
- 重定向链和不一致的规范标签；
- 客户端链接仅在 JavaScript 执行后出现；
- 返回 HTTP 200 的软 404 页面；
- 不是 HTML 页面的大文件和端点。
Robots 规则和网站地图发现提供了重要的信号。机器人排除协议 标准化了 robots.txt 的行为，而 网站地图协议 定义了通用 XML URL 列表格式。没有任何来源允许收集数据；您还必须遵守条款、身份验证边界、版权、隐私和适用法律。
先决条件
您需要一个 Nstproxy 帐户，一个爬取 API 密钥，一个经过授权的公共种子 URL，以及对所需覆盖范围的明确定义。在提交之前决定您是否需要页面文本、链接、HTML、屏幕截图或其他支持的工件。
- 预期的 URL 家族，例如
/docs/ 或 /products/；
- 排除的家族，例如
/account/、/cart/、/search/ 和日历；
- 最大深度和页面预算；
- 预期的语言和规范主机规则；
- 对接受页面的最低内容检查；
- 下游存储的刷新和删除策略。
从一个有代表性的部分开始，使用较低的 maxPages 值。一个受限的试点可以揭示 URL 陷阱，而不会消耗完整的工作预算。
.image-icon:before { content: ""; position: absolute; left: 7px; top: 14px; width: 13px; height: 8px; background: #3a70ff; clip-path: polygon(0 100%,35% 35%,55% 65%,72% 45%,100% 100%); }
.image-icon:after { content: ""; position: absolute; right: 6px; top: 6px; width: 4px; height: 4px; border-radius: 50%; background: #3a70ff; }
.line { height: 7px; margin-top: 10px; border-radius: 4px; background: #e6e8ec; }
.line.short { width: 65%; }
.line.tiny { width: 45%; }
.code-copy { margin-top: 8px; font-family: "SFMono-Regular", Consolas, monospace; color: #858b97; font-size: 12px; line-height: 1.45; }
.shot-window { margin-top: 12px; height: 62px; overflow: hidden; border: 1px solid #c8cdd6; border-radius: 6px; background: #f6f7f9; }
.shot-top { height: 13px; border-bottom: 1px solid #d7dbe1; background: #fff; }
.dots { display: inline-block; width: 4px; height: 4px; margin: 4px 0 0 5px; border-radius: 50%; background: #ccd0d7; box-shadow: 7px 0 #ccd0d7, 14px 0 #ccd0d7; }
.shot-hero { float: left; width: 68px; height: 30px; margin: 10px 8px; border-radius: 3px; background: #d2d5db; }
.shot-copy { margin: 10px 8px 0 86px; height: 6px; border-radius: 3px; background: #d5d8dd; box-shadow: 0 12px #e0e2e6, -12px 24px #d5d8dd; }
@media only screen and (max-width: 650px) {
.canvas { padding: 12px; }
.copy-cell, .visual-cell { display: block; width: 100%; }
.copy-cell { padding: 32px 24px 16px; text-align: center; }
.visual-cell { padding: 16px 12px 28px; }
.description br { display: none; }
.cta { margin-top: 22px; }
.crawl-visual { transform-origin: top center; transform: scale(.88); margin: 0 auto -31px; }
}
@media only screen and (max-width: 520px) {
h1 { font-size: 22px; }
.description { font-size: 14px; }
.crawl-visual { left: 50%; margin-left: -265px; transform: scale(.62); margin-bottom: -99px; }
</style>
<main class="canvas">
<section class="feature" aria-label="Nstproxy Crawl overview">
<table class="layout" role="presentation" cellpadding="0" cellspacing="0">
<tr>
<td class="copy-cell">
<h1>将一个 URL 转换为网站数据集</h1>
<p class="description">使用 Nstproxy Crawl 在明确的限制内发现、渲染和返回页面。</p>
<a class="cta" href="https://app.nstproxy.com/auth/login?utm_source=official&utm_medium=blog&utm_campaign=/crawl-entire-website-api/" target="_blank" rel="noopener">开始爬取</a>
</td>
<td class="visual-cell">
<div class="crawl-visual" aria-label="将 URL 转换为 Markdown、JSON 和截图的示意图">
<div class="url-bar">
<svg class="url-icon" viewBox="0 0 24 24" aria-hidden="true"><path d="M10.6 13.4a1 1 0 0 0 1.4 1.4l3.5-3.5a3 3 0 0 0-4.2-4.2L9.5 8.9" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round"/><path d="M13.4 10.6a1 1 0 0 0-1.4-1.4l-3.5 3.5a3 3 0 0 0 4.2 4.2l1.8-1.8" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round"/></svg>
<span class="url-text">https://example.com/article</span>
<span class="crawl-button">爬取</span>
</div>
<span class="stem"></span><span class="branch"></span><span class="branch-cap-left"></span><span class="branch-cap-right"></span>
<span class="drop one"></span><span class="drop two"></span><span class="drop three"></span>
<span class="node top"></span><span class="node mid"></span><span class="node left"></span><span class="node center"></span><span class="node right"></span>
<div class="format-card markdown">
<div class="card-title"><span class="mini-icon">M↵</span>Markdown</div>
<div class="line"></div><div class="line"></div><div class="line short"></div><div class="line tiny"></div>
</div>
<div class="format-card json">
<div class="card-title"><span class="mini-icon">{}</span>JSON</div>
<div class="code-copy">{<br> "title": "...",<br> "url": "..."<br>}</div>
</div>
<div class="format-card screenshot">
<div class="card-title"><span class="mini-icon image-icon"></span>截图</div>
<div class="shot-window"><div class="shot-top"><span class="dots"></span></div><div class="shot-hero"></div><div class="shot-copy"></div></div>
</div>
</div>
</td>
</tr>
</table>
</section>
</main>
## 提交整个网站的爬取
提交一个异步作业到当前的网站爬取路由。2026年9月4日进行的无凭证探测返回 HTTP 401，确认 `/api/v1/crawl` 正在运行且需要身份验证。下面的请求与文档对齐，但在没有帐户密钥的情况下无法完成。
```bash
curl --request POST
--url 'https://api.nstproxy.com/api/v1/crawl'
--header 'x-api-key: YOUR_NSTPROXY_API_KEY'
--header 'Content-Type: application/json'
--data '{
"url": "https://example.com/docs/",
"formats": ["markdown", "html"],
"maxDepth": 3,
"maxPages": 50,
"includeUrls": ["example.com/docs/"],
"excludeUrls": ["example.com/docs/archive/"],
"ignoreQuery": true,
"onlyMainContent": true,
"timeout": 60000
}'
预期的响应封装包含任务 ID 和处理状态。请勿将说明性 ID 复制到后续请求中；始终保留您提交的确切标识符。
仅请求您将使用的格式。Markdown 适合于 LLM 和 RAG 处理，而 HTML 有助于当您的解析器需要选择器或语义标记时。多种格式会增加工件数量和后续处理。
Nstproxy 的 [Crawl 启动概述](https://www.nstproxy.com/blog/nstproxy-crawl-launch) 描述了更广泛的产品工作流程，包括站点发现和 LLM 准备的输出。
## 控制爬取深度和范围
通过组合深度、页面数量、路径模式和查询规范化来控制范围。单一设置不足以满足需求。
### 按信息架构选择 `maxDepth`
深度为零或一有助于验证种子和立即导航。文档中心可能需要两次或三次跳转才能到达主题页面。如果重要页面只能通过站点地图或 JavaScript 搜索到达，则高深度并不能保证覆盖。
深度还取决于所选的种子。从域主页开始可能会在营销页面中浪费跳转；从 `/docs/` 开始会使同样的深度预算更具相关性。
### 将 `maxPages` 视为硬预算
页面数量防止宽链接图无限扩大。设置一个低于您预期语料库的初始预算，检查发现的 URL 混合，然后仅在有价值的页面占主导地位时才提高该预算。
如果作业达到 `maxPages`，完成并不意味着整个预期站点已被覆盖。这意味着受限的工作停止在其配置的上限处。
### 使用包含规则而非排除规则
允许列表，例如 `*example.com/docs/*`，比数十个排除规则更易于理解。在允许的部分内添加已知低价值子树的排除规则。
在启动之前测试模式行为与示例 URL。错误的斜杠或主机模式可能会悄悄排除每个页面或包含不相关的子域。
### 小心规范化查询参数
当参数不更改有意义的内容（如跟踪和排序值）时，启用 `ignoreQuery`。当查询字符串选择您数据集所需的真实区域、产品变体、文档版本或分页状态时，请勿丢弃查询字符串。
URL 比较必须遵循一致的解析规则。 <a href="https://url.spec.whatwg.org/" rel="nofollow noopener"><strong>WHATWG URL 标准</strong></a> 文档描述了现代 URL 解析行为；避免针对主机、路径和查询的临时字符串拆分。
## 轮询爬取状态
使用返回的任务 ID 查询作业状态。将下面的占位符替换为您的真实标识符：
```bash
curl --request GET \
--url 'https://api.nstproxy.com/api/v1/crawl/YOUR_TASK_ID' \
--header 'x-api-key: YOUR_NSTPROXY_API_KEY'
使用有界指数退避与抖动，而不是持续轮询。停止在文档记录的终端状态，并在您的应用程序中强制执行总体截止日期。
检查响应体，而不仅仅是 HTTP 200。Nstproxy 当前模型可以在成功的 HTTP 封装内报告任务级失败信息。在存在时记录 total，completed，pending 和 failed 数量，以及非秘密请求和任务标识符。
不要因为少数页面失败而自动重新提交整个网站。检索页面级结果，分类失败，并仅重试合格的 URL。认证失败、不允许的目标、解析错误和短暂超时需要不同的响应。
检索每个爬取的页面
curl --request GET \
--url 'https://api.nstproxy.com/api/v1/crawl/YOUR_TASK_ID/pages?limit=50' \
--header 'x-api-key: YOUR_NSTPROXY_API_KEY'
如果响应包含 nextCursor，请求下一页并继续，直到不再有游标。完成爬取后在第一个 API 响应后停止是导致完成的爬取似乎仅包含部分站点的常见原因。
大型工件可能作为参考令牌到达，例如 markdownRef 或 htmlRef。通过文档存储端点解析参考；永远不要自己构建或修改存储令牌。
至少保留请求的 URL、最终 URL、标准 URL（如果可用）、状态、标题、语言、内容哈希、爬取时间和输出参考。确保页面身份与分页游标分开，后者是传输状态而不是文档 ID。
验证覆盖和数据质量
爬取成功的标准是覆盖所需语料库并且内容页符合要求，而不仅仅是状态显示已完成。将结果集与站点的站点地图、已知的导航树或手动标记的样本进行比较。
- 预期发现的 URL；
- 处理的发现 URL；
- 具有有效内容的页面；
- 唯一规范页面；
- 重复和重定向；
- 按原因分类的失败；
- 每个路径族消耗的 URL 预算。
检查来自浅层和深层路径的分层样本。检查依赖 JavaScript 的页面、表格、代码块、分页、本地变体和已知的软404。如果爬取预算被低价值路径主导，请在增加 maxPages 之前收紧包含规则。
在构建与购买的背景下，Nstproxy 的 开源网页爬虫比较 涉及提供更低级控制的爬虫框架，但需要你自己操作调度、渲染、存储、代理和监控。
处理失败和刷新
分开提交错误、任务错误和页面质量失败。无效请求应在作业创建之前失败。有效任务仍可能包含目标超时、访问拒绝、解析器失败或空内容。技术上成功的页面仍可能因重复、地区错误或同意屏幕而被拒绝。
对于定期爬取，保留内容哈希并比较规范 URL。重新处理已更改的页面，添加新页面，并从下游索引中删除已删除页面。不要无限期地追加每次运行。
对于稳定存档，使用较慢的刷新频率，对于变更日志、库存或政策则使用较快的频率。尊重缓存头并在适当的情况下考虑目标容量。如果源提供变更信息或修改时间戳，请使用它们以减少不必要的获取。
负责任的全站爬取
全站访问必须获得授权并且成比例。不要使用 API 绕过身份验证、付费墙、权限或技术保护措施。避免私有页面并最小化个人或受监管数据。
在接受用户提供的种子时，防止服务器端请求伪造。阻止 localhost、私有和链路本地网络、云元数据端点、不安全的方案、可疑的端口和超出批准范围的重定向。OWASP SSRF 指南 提供了实际的威胁模型。
将 API 密钥保存在批准的秘密存储中，绝不要放在日志或源代码控制中。任务 ID 和存储引用可以提供结果访问权限，因此请避免向未授权用户暴露它们。
全站爬取清单
在提交之前，验证种子 URL、允许的主机、包含路径、排除项目、查询策略、最大深度、页面预算、输出格式和法律授权。在任务过程中，使用有限轮询监控状态。完成后，对所有结果进行分页，解析所需的构件，去重规范内容，审查失败，并与已知来源进行覆盖比较。
一次提交，明确边界，验证结果
一个 API 请求可以启动完整的站点工作流，但好的爬取仍然依赖于明确的边界和验证。maxDepth 形状链接遍历，maxPages 保护预算，URL 模式集中发现，分页结果检索将任务转变为可用的数据集。
首先使用最小的代表性爬取。一旦 URL 分布、页面质量、失败处理和覆盖检查正确，逐渐提高限制。
常见问题
可以。一个 POST 请求可以提交一个受限的Nstproxy网站爬取，但异步工作流程仍然需要后续的状态轮询和分页结果检索。
Q: maxDepth和maxPages之间有什么区别？
maxDepth限制了从种子URL出发的链接跳数，而maxPages则限制了作业处理的页面总数，无论图形宽度如何。
将严格的页面限制与允许的路径模式、已知的排除项、查询规范化、规范去重和低预算的试点爬取相结合。日历和分面导航路径应进行明确测试。
将唯一的接受结果与网站地图或已知的URL清单进行比较，检查失败和路径覆盖情况，并确保每个分页结果页面都已检索。
Ivy Lin
Sep. 4th 2026
立即访问住宅、数据中心、IPv6 与 ISP 高质量代理池。
