核心用法
xcrawl-map 是 XCrawl 官方提供的站点 URL 发现技能，用于在执行全站爬取前完成站点结构测绘与爬取范围规划。核心工作流程为：明确测绘目标（纯发现、选择性爬取规划或结构分析）→ 构建并执行 POST /v1/map 请求 → 直接返回上游 API 原始响应。
请求需携带从 ~/.xcrawl/config.json 读取的 API Key，支持通过 cURL 或 Node.js 发起调用。关键参数包括：url（入口地址，必填）、filter（正则过滤 URL）、limit（上限 100,000 条，默认 5,000）、include_subdomains（是否含子域，默认 true）、ignore_query_parameters（是否忽略查询参数，默认 true）。
显著优点
- 官方原生集成：直接调用 XCrawl 官方
/v1/map端点，数据可信度与实时性有保障 - 灵活的范围控制：正则过滤、子域开关、查询参数处理三项机制可精确界定爬取边界
- 按需计费透明：基于实际发现 URL 数量扣减积分，并提供详细的
credits_detail明细 - 零环境依赖：仅需 curl 与 node，不强制要求 Python 或其他运行时
潜在缺点与局限性
- 非免费服务：依赖 XCrawl 账户积分，虽提供 1000 积分试用额度，但大规模测绘需持续充值
- 无本地缓存机制：每次调用均为实时 API 请求，重复测绘相同站点仍消耗积分
- 原始数据直出：默认仅返回上游原始 JSON，不生成可读性摘要或 URL 家族归类，需用户自行处理
- 上限约束：单任务上限 10 万 URL，超大规模站点需分片策略
适合人群
- 需要在正式爬取前评估站点规模与结构的开发者
- 希望用正则精确筛选特定路径（如
/docs/.*）进行定向内容采集的用户 - 已拥有或愿意注册 XCrawl 账户、接受按量计费模式的技术团队
常规风险
- 积分耗尽导致服务中断：未监控余额时可能在任务执行中途失败
- 范围估计偏差：
limit触顶时不会自动提示"未完整覆盖"，需用户主动判断 - 配置泄露风险：API Key 存储于本地 JSON 文件，共享环境或误提交代码库可能导致密钥泄露
- 误过滤导致数据缺失：正则表达式编写不当可能意外排除目标 URL