1. 先摸清多语言帮助中心的三种结构规律说实话我第一次接到“把某产品所有语言的帮助中心内容都抓下来”这个需求时第一反应不是打开代码编辑器而是打开浏览器把要采集的站点翻了整整一晚上。原因很简单写爬虫之前如果连站点结构都没搞清楚后面所有代码都是在沙地上盖楼。尤其是多语言帮助中心它的URL规则、页面组织方式、语言切换机制每家实现得都不一样而这些差异恰恰决定了采集器怎么写、要写多厚。1.1 URL语言路径的两套主流布局帮助中心的多语言在URL层面常见的有三种表达方式子域名、路径前缀、查询参数。做采集时遇到最多的是路径前缀典型样式是example.com/help/zh-cn/docs/install、example.com/help/en-us/docs/install语言代码直接坐在路径里连着一层docs再接具体的文档路径。这种布局对采集器最友好——URL的语义非常清晰语言前缀去掉之后剩下那段路径基本就是文档的唯一标识了。子域名布局也不少见比如zh.example.com/docs、en.example.com/docs但它在实际产品里比较容易被运维配置出各种幺蛾子比如证书没覆盖子域名、部分地区的DNS解析异常采集时遇到超时的概率明显偏高。查询参数布局比如example.com/help?langzh-CN多见于一些旧系统是目前三种里最不推荐优先支持的——因为URL里缺了语言语义搜索引擎的SEO表现通常也差点意思很多产品已经逐步改掉了。URL方式示例采集时的难度备注路径前缀/help/zh-cn/docs/install低最常见语言标识显式可拆子域名zh.example.com/docs中注意DNS、证书和超时问题查询参数/help?langzh-CN低~中相关性较弱易被忽略1.2 内容组织模型手册树与问答广场光看URL还不够还要看帮助中心是按“手册树”组织的还是按“问答广场”组织的。这两种模型采集时的策略完全不同。手册树型站点最典型的就是用GitBook、ReadTheDocs这类工具搭建的文档站左侧通常有一棵完整的目录树下面挂着若干章节章节下面再挂若干页面。URL路径天然就带着层级比如/docs/guide/getting-started采集器只需要从目录树里递归拿到所有叶子页面的链接就能保证文档不漏。这里有个常见误区很多人以为有了sitemap就不用分析目录树了但很多文档站的sitemap只收录了最近更新的一小部分页面或者根本没有把每个语言版本的页面都写进去拿目录树作为主干、sitemap做兜底才是稳妥的做法。问答广场型站点国内外的产品支持中心、客服知识库基本都长这样典型结构是“分类大类 → 分类小类 → 文章列表 → 文章详情页”文章URL里带分类ID和文章ID比如Zendesk类的站点会有/hc/zh-cn/categories/xxx和/hc/zh-cn/articles/xxx这类特征明显的路径。采集这种结构时要分三步走先拿所有分类页再进入每个分类页拿文章列表链接最后再去详情页抓正文。采集器里对这类结构至少要预留“分类链接列表”和“文章链接列表”两个解析器。1.3 语言切换入口真正省力的hreflang多语言站点在SEO上有个标准做法叫 hreflang在页面head里用一组link relalternate hreflang语言代码 href完整URL声明这个页面的其他语言版本分别在哪。对于采集器来说这组标签几乎就是官方免费提供的“语言版本全量地图”。我之前做某产品帮助中心采集时一开始是从首页找语言下拉框用XPath硬挑select下的option结果下拉框变了两次样式之后规则就失效了。后来改成优先解析//link[contains(hreflang, -)]或者//link[hreflang]直接从任意一个已知页面的head里一次性拿到所有语言版本的URL稳了很多而且连“每个语言版本的主页”都自动知道了。唯一要注意的是过滤一下hreflangx-default那个是给搜索引擎兜底用的采集时用不上。提示采集器启动时的第一步永远是从入口页面解析 hreflang 系列链接而不是硬编码一长串语言代码。硬编码会腐烂hreflang才是站点自己维护的最新状态。2. 采集器架构设计边界清晰比功能多更重要很多人在只跑一次性采集的时候会想“我直接写个脚本跑完拉倒”但对于多语言帮助中心这种要长期维护、经常增量更新的场景脚本写太随意后期每次改需求都要推倒重来。我的习惯是先画边界再写代码哪怕只是单文件脚本也要在脑子里把职责拆清楚。2.1 为什么用requests加parsel而不是Scrapy聊“用Python写爬虫”总绕不开Scrapy。Scrapy确实是个好框架分布式、并发调度、管道、中间件全都有但我最终没有用它来写这个采集器。原因有三一是Scrapy的项目结构和配置流程对新手来说有一定成本而这个采集器的任务量级就是“十几个语言版本、几百到上千篇帮助文档”完全没到需要框架撑场面的规模二是帮助中心的页面结构相对规整自己管理十几个页面模板的解析逻辑并不困难三是Scrapy的并发能力在这个场景下反而容易变成劣势——并发一高还没采多少页对面的WAF就该来找你了。我选的是requests加parsel的组合。parsel就是Scrapy底层那套解析器单独抽出来一样好用支持XPath和CSS选择器用起来和Scrapy的response.xpath()几乎完全一致后面真觉得规模大了再迁移到Scrapy也不难。整个采集器单线程、顺序请求、随机延时慢但稳很适合帮助中心这类不追求高吞吐的目标。2.2 五层职责拆分不管代码是写在一个文件还是分模块逻辑上我都会拆成五层每一层只干一件事路由层负责根据语言代码和URL模板生成待访问URL列表是“采哪些页面”的决策者。抓取层负责发请求、处理超时和重试、设置UA和随机延时是唯一和网络打交道的地方。解析层把HTML转成结构化数据标题、正文、语言版本链接是XPath规则最密集的地方。清洗层去掉正文里夹带的导航文字、面包屑、页脚、相关文章推荐让内容干净。存储层负责决定输出成JSON、CSV还是SQLite以及增量时如何对比。这五层之间谁也别越界。我见过太多翻车案例就是把解析规则和存储逻辑混在一起每加一个站点就要动主流程函数很难维护。边界拆好之后哪怕某个站点结构特殊也只是往“站点适配器”里加解析规则而已。2.3 多语言采集的状态管理多语言采集比单语言多一层复杂度同一个文档中文版抓成功了不代表日文版也抓成功了日文版这次成功了也不代表以后内容更新后还不需要重抓。所以采集器一定要有一张“状态表”记录每个URL的语言、状态、内容哈希和最后抓取时间。我用的是最简单的字典加列表task_state { url: https://example.com/help/zh-cn/docs/install, lang: zh-cn, status: pending, # pending / success / failed content_hash: , retry_count: 0, }状态流转是pending进入抓取成功变成success并写入内容哈希失败则重试重试次数超过阈值标成failed输出到日志文件里人工排查。有了这张表断点续采、按语言补采、增量更新都变得非常简单只需要在启动时扫描一次状态表找出不是success的URL去抓就好。3. 核心代码实现从语言首页到正文落地架构说完直接上可以抄的代码。这里我用一个虚构的帮助中心站点做演示URL结构是/help/{lang}/docs/{doc_path}正文容器是div.article-body语言页通过 hreflang 声明。实际使用时你只需要改解析规则那一层。3.1 第一步通过hreflang发现所有语言版本import requests from parsel import Selector HEADERS { User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0 Safari/537.36 } def discover_languages(start_url): resp requests.get(start_url, headersHEADERS, timeout10) sel Selector(textresp.text) languages {} for node in sel.xpath(//link[hreflang]): href node.xpath(href).get() lang node.xpath(hreflang).get().strip().lower() if lang and href and lang ! x-default: languages[lang] href return languages这段代码做的事情很单纯从一个已知入口页面比如你手工确认过的某个帮助中心首页发起请求然后把head里的 hreflang 链接全部捞出来返回一个“语言代码 → 该语言首页URL”的字典。输出大概是这样的{ en-us: https://example.com/help/en-us/docs/home, zh-cn: https://example.com/help/zh-cn/docs/home, ja-jp: https://example.com/help/ja-jp/docs/home, }有一类站点比较坑它的 hreflang 只有en-us和x-default其他语言的页面却没有反向声明。遇到这种情况只能退回到解析首页的语言下拉框或者直接读取语言配置文件。不过从我的实测情况来看大多数正经做多语言的产品hreflang 都会配齐因为SEO部门会盯着这块。3.2 第二步抓取每个语言版本的目录页拿到每个语言的主页后接下来要拿到文档目录树。手册树型站点通常把目录树放在页面侧边栏里链接的URL和正文路径是对应的采集时过滤掉无效链接即可def collect_doc_links(lang_home_url): resp requests.get(lang_home_url, headersHEADERS, timeout10) sel Selector(textresp.text) doc_links [] for link in sel.xpath(//a/href).getall(): # 过滤掉外部链接、javascript链接、锚点链接 if not link or link.startswith(javascript) or link #: continue if link.startswith(http) and example.com/help not in link: continue doc_links.append(link) return list(set(doc_links))这里我故意用很朴素的过滤方式就是为了说明一个基本原则目录树的采集规则宁可宽一点也不能窄。因为漏掉一个链接就漏一整篇文档而多一点链接最多是后面去重时多花一点算力。清洗去重的债可以后面还但漏采的损失没办法通过代码补救。问答广场型站点则不同你需要先把/categories/下的分类链接拿到然后每个分类页再拿文章链接。采集时我建议专门写一个分类页解析器和文档链接解析器分开因为两种页面的页面结构差异实在太大混在一起会让XPath规则越来越难维护。3.3 正文提取XPath中text()函数的三个坑正文解析是整个采集器最核心、也是踩坑最多的一环。XPath里的text()函数看起来简单用起来全是细节至少有三个坑我几乎每次都会碰到。第一个坑//text()返回的是一个文本节点列表而不是一个字符串。很多人直接写成sel.xpath(//div[contains(class,article-body)]/text()).get()拿到的只是第一个直接子文本节点一段正文可能只抓到了开头几个字。正确做法是getall()拿到列表之后join并且把多余空白strip掉。第二个坑string(.)只返回第一个匹配节点的字符串值。比如sel.xpath(string(//div[classarticle-body])).get()它返回的是第一个div.article-body的文本内容但这里的“文本内容”只包含该节点下第一个文本节点的直接值并不等于所有后代文本的拼接。你把一大段正文都放在这个div里用string(.)抓出来往往只有第一段的开头几个字。第三个坑contains(text(), 关键词)判断的是第一个文本节点是否包含关键词。如果目标节点开头是一个空白符、回车符或者内嵌了其他标签比如p里的第一个子节点是code那contains(text(), ...)直接判断失败。正确写法是用contains(string(.), 关键词)或者//text()[contains(., 关键词)]。一份比较稳妥的正文提取代码长这样def parse_article(html_text): sel Selector(texthtml_text) # 标题优先取 article 区块内的 h1不要直接取全页面第一个 h1 title_nodes sel.xpath(//article//h1[1]//text()).getall() if not title_nodes: title_nodes sel.xpath(//main//h1[1]//text()).getall() title .join(t.strip() for t in title_nodes if t.strip()) # 正文指定容器把容器内的所有文本节点拼起来 content_nodes sel.xpath( //div[contains(class, article-body)]//text() ).getall() lines [t.strip() for t in content_nodes if t.strip()] content \n.join(lines) return title, content注意标题提取时我用了//article//h1[1]来限定范围。帮助中心的页面往往会有两个h1——一个在顶部导航栏里当品牌名一个才是真正的文档标题不限定范围非常容易抓成导航里的那个。3.4 第三步按语言目录落地存储内容提取完毕后存储层我选择了“目录加JSON文件”和“SQLite”两种方案并存。文档量不大时按语言目录输出JSON每个文件就是一篇完整的文档方便人工预览和直接用文本工具搜索import json import hashlib from pathlib import Path def save_article(lang, url, title, content, base_diroutput): out_dir Path(base_dir) / lang out_dir.mkdir(parentsTrue, exist_okTrue) content_hash hashlib.md5(content.encode(utf-8)).hexdigest() doc_key url.split(f/{lang}/, 1)[-1].replace(/, _) .json record { lang: lang, url: url, title: title, content: content, content_hash: content_hash, } out_path out_dir / doc_key out_path.write_text(json.dumps(record, ensure_asciiFalse, indent2), encodingutf-8) return content_hash用SQLite方案时我会建这样一张表CREATE TABLE IF NOT EXISTS articles ( id INTEGER PRIMARY KEY AUTOINCREMENT, lang TEXT NOT NULL, url TEXT NOT NULL UNIQUE, title TEXT, content TEXT, content_hash TEXT, fetched_at TEXT DEFAULT CURRENT_TIMESTAMP );增量更新的判断依据就是content_hash。每次抓取前先查库如果URL存在且哈希一致说明内容没变化跳过如果哈希变了说明文档被更新过用新内容覆盖旧记录。这套机制确保采集器不会重复下载未变化的页面多语言环境下尤其省事。4. 多语言去重与聚合采集器是否好用的分水岭如果采集器只是把不同语言的内容一批一批地抓进文件夹那它充其量是个“下载器”离“好用”还差得远。真正让它变得好用的是能把同一个文档的不同语言版本关联起来能在重复内容之间做出智能判断甚至能主动帮业务方产出翻译对照表。这一步我称为多语言内容的聚合。4.1 同一文档不同语言版本怎么关联多语言站点的同一个文档英文版URL可能是/help/en-us/docs/install中文版是/help/zh-cn/docs/install日文版是/help/ja-jp/docs/install。如果只是抓取存储这三条URL会被当成三篇完全不同的文档。但聚合的需求偏偏要求你知道它们是同一篇文档的三个翻译版本这时就必须要做“归一化”。最常见的归一化做法是去掉语言前缀用剩下的路径做文档IDLANG_PREFIXES [en-us, zh-cn, ja-jp] # 从 discover_languages 结果获取 def normalize_doc_key(url, lang_prefixes): for prefix in lang_prefixes: marker f/{prefix}/ if marker in url: return url.split(marker, 1)[1] from urllib.parse import urlparse return urlparse(url).path归一化之后/docs/install就成了这三篇文档的共同ID。我在存储表里专门加了一列doc_key采集时算好写进去。有了这一列后续“按文档ID汇总所有语言版本”“查哪些语言版本缺失”都成了简单的SQL或字典操作。4.2 内容相似度去重帮助中心还有一个问题会让去重变得棘手同一篇文档可能被挂在多个分类下或者历史页面保留了旧版本URL不一样但正文内容几乎一样另外不同语言版本之间标题经常是“Install on Linux”和“在Linux上安装”这种翻译关系文本相似度并不高没法直接靠标题去重。我的处理策略是“标题语义化”加“正文章节内容哈希”双管齐下。同语言版本之间用首段正文的哈希或simhash比对相似度超过阈值就合并处理跨语言版本之间主要靠doc_key关联如果遇到了doc_key对不上但内容明显相关的页面再人工复核。虽然simhash的方案听起来复杂但实际落地很简单jieba分词后建一个64位的指纹然后两两对比汉明距离即可。不过说句大实话帮助中心的文档量级通常没大到需要上simhash的地步我更常用的是取正文字符串的difflib.SequenceMatcher相似度足够解决绝大多数重复问题代码量还少一大截。4.3 导出翻译对照表聚合的真正价值在导出对照表的时候才体现出来。给翻译团队或者产品团队做内容审计时他们需要的不是一堆离散的JSON文件而是一张“同一篇文档在各国语言下的标题和正文状态”的Excel表格让负责人一眼看出哪些语言版本缺了、哪些还在用旧内容。实现这个功能只需要按doc_key分组把每一组语言版本的标题、正文长度、内容哈希、最近抓取时间放到一行里然后用csv模块写出去。正文内容过长时可以只放首段让表格不至于臃肿。这一步能让采集器从“技术工具”变成“业务工具”也是我认为整个项目里投入产出比最高的一部分——逻辑就二三十行但业务方立刻能感受到采集器带来的管理效率提升。5. 反爬与合规采集帮助中心不能踩的红线聊爬虫绕不开“防爬”这个话题。很多刚入门的朋友把精力全放在怎么绕过各种防护上但实际上帮助中心这类站点的形态决定了它的防护策略和电商平台完全不同电商平台要防的是竞争对手偷商品数据帮助中心巴不得所有人来读它的文档。所以采集帮助中心时真正的重点是“克制”而不是“对抗”。5.1 前端防爬的常见处理手段近几年的前端防爬总体上能归成三类。第一类是源码保护压缩混淆JS、禁用右键、DOM遮罩这类措施主要防的是“人肉看源码”对于脚本采集器来说几乎毫无作用因为行业里已经普遍用无头浏览器或者直接请求后端接口了根本不解析前端源码。第二类是动态渲染页面内容由JavaScript异步加载初始HTML里只有空壳requests直接抓只能抓到一堆JS文件和空的容器标签。第三类是访问控制验证码、IP维度频率限制、并发连接数限制、UA/Bot特征检测这是最现实、最影响采集效率的一层。帮助中心站点通常动态渲染和访问控制都配得比较轻因为它要考虑真实用户在弱网环境下的体验也不可能把所有用户都逼到验证码面前。所以遇到的防护更多是“频率控制”和“基础UA检查”只要采集器足够礼貌基本不会触发。5.2 采集器的自我约束我把“采集器的自我约束”写进了代码而不是写在文档上让跑任务的人自觉遵守。具体体现在三个方面限速、退避、遵守robots。import time import random def fetch_with_retry(url, max_retries3): for attempt in range(max_retries): time.sleep(random.uniform(2, 5)) # 每个请求之间随机间隔2到5秒 try: resp requests.get(url, headersHEADERS, timeout10) if resp.status_code 200: return resp.text if resp.status_code in (403, 429): # 被限速或临时封禁指数退避后重试 wait_time 2 ** (attempt 1) time.sleep(wait_time) except requests.RequestException: pass return None这里的关键不是代码而是“宁愿慢、不要快”的心态。一次帮助中心的采集任务几百篇文章分分钟就抓完了真没必要把并发开到几十去给对方服务器制造压力。认真算一下时间账就明白了一篇正文压缩后几十KB按单线程3秒一个页面、上限1000篇文章来算一小时多一点全部搞定完全处于可接受范围。robots.txt方面我的做法一直是“参考但不盲从”。如果某个路径明确写了Disallow我会在采集配置里默认跳过这既是对站点规则的尊重也是给自己降低被投诉的风险。帮助中心的robots里通常会允许搜索引擎访问大部分公开文档所以正常采集基本不会撞到Disallow的路径上。5.3 常见封禁信号与应对采集过程中万一真的被封了通常会有几个典型信号返回码开始大量出现403 Forbidden或429 Too Many Requests页面里出现了验证码HTML或者“检测到异常流量”的字样响应时间突然从500毫秒飙升到10秒以上。遇到这些信号唯一的正确处理是立刻暂停任务而不是换UA、加代理、开并发硬冲。暂停之后做三件事检查最近一次请求的频率和时间段把状态表里failed的任务记录下来等一段时间比如30分钟再用更慢的速度、从断点开始继续。说实话帮助中心的封禁绝大多数都是“临时限速”只要你别在它气头上继续加码过一会儿它自己就解了。我见过太多人把简单任务玩崩都是因为一碰到429就换上代理池和分布式调度结果对面直接看到一批陌生的海外IP在深夜奔涌而来封得更狠。提示采集公开帮助文档用于内部整理、编制索引属于常见需求但如果你打算做二次发布、翻译后商用甚至绕过登录态抓取非公开内容就实实在在地踩线了。动手之前先看站点条款和服务协议既是法律意识也是基本职业素养。6. 实测中的意外状况与排查笔记代码写完之后真正跑起来总会碰到理论上完全想不到、一秒钟就能让别人看出来你踩过的那些坑。这里把我实测中遇到过的几个意外状况罗列出来可以帮你在动手前就避开。6.1 编码乱码响应头里没声明charset有相当一部分站点尤其是海外老牌产品的文档站响应头里只写了Content-Type: text/html没带charset而HTMLmeta里虽然有charsetutf-8但有些页面是在比较靠后的位置才声明。requests默认会先看HTTP头没有charset时就用ISO-8859-1猜结果中文全部变成乱码英文倒是没事。排查方法很直观打印resp.encoding如果显示的不是utf-8而页面里明明有中文就需要强制纠正编码。def fetch_text(url): resp requests.get(url, headersHEADERS, timeout10) if resp.encoding and resp.encoding.lower() not in (utf-8, utf8): resp.encoding resp.apparent_encoding or utf-8 return resp.textapparent_encoding是requests根据页面字节内容推断出的编码对帮助中心页面的UTF-8中文内容判断基本可靠。个别站点如果还没解决就直接resp.encoding utf-8无条件指定反正现代帮助中心已经是UTF-8的天下。6.2 H1与正文容器定位失败第一次抓某个帮助中心的页面前不要轻信浏览器里看到的HTML。浏览器会自动补全标签、隐藏无效节点但requests拿到的是服务器原始返回有可能和你在开发者工具里看到的结构并不一致。常见的问题是页面里有多个h1或者标题根本不是h1而是h2正文容器也不一定就叫article-body可能是markdown-body、content-body、doc-content。我的排查顺序是先用浏览器开发者工具看网络面板的原始HTML确认标题和正文的真实容器结构再在本地用parsel写一条最小XPath试提取确认无误后才把规则写进采集器。不要对着浏览器显示的DOM结构去写XPath规则那和隔着毛玻璃看实物没区别。6.3 目录树由JS动态渲染有的帮助中心采用前后端分离架构文档目录数据是通过接口动态加载的初始HTML里没有链接列表。requests直接访问时目录区域是一片空白。这种情况下我强烈建议先去Network面板里找数据接口而不是急着上无头浏览器。无头浏览器太吃资源只为拿一个目录树就启动一个Chromium实例有点小题大做。常见形态是/api/v2/categories或/api/v2/sections这样的JSON接口返回分类和文章的列表数据直接在采集器里改成请求接口解析JSON速度和稳定性都远胜“模拟浏览器”。6.4 重定向与URL大小写问题帮助中心的多语言路径有一个隐蔽的坑语言路径的大小写不统一。有的页面是/zh-CN/有的又是/zh-cn/或站点配置了301重定向把小写的zh-cn跳到zh-CN。requests默认会自动跟随重定向最终拿到的内容和最终URL都是跳转后的版本但状态表里记录的还是跳转前的URL导致下次运行又重复抓一遍。解决方法是每次抓取后把response.url取出来与请求URL比对如果不同就用最终URL覆盖状态表里的记录并同步更新语言前缀映射。语言前缀统一用小写存储页面上遇到大写的原始地址则在下一次运行前自动转换成小写再去请求。另外一类很隐蔽的问题是某语言版本页面成功抓取后重定向到了另一个语言的同一篇文档比如中文文档缺失站点就直接把用户导到英文版。这类情况靠content_hash就能发现——抓到的中文版内容哈希和英文版一模一样明显有问题应该标记为“缺语言版本待跟进”而不是直接把英文内容当成中文版存储。这类小细节才是多语言采集器质量的真正分水岭。最后再分享一个我自己的使用习惯无论站点结构看起来多乱、多“不标准”我都会在代码里维护一份“站点配置”把语言前缀、目录链接过滤器、正文容器XPath、内容是否需要排除的导航区全部写成可配置的字典。这样换一个帮助中心站点时只需要改配置不改代码。这套采集器我从最初的两百行脚本一直演进到现在跑过英语、简体中文、繁体中文、日语、德语五个语言池稳定用了差不多一年每次有新产品上线帮助中心我第一反应就是把它的站点配置填进去而不是再从零写一个新的爬虫。