最近总在整理自己的收藏夹发现一个很扎心的事实很多当年认真保存的文章链接已经打不开了有些技术文档还活着但页面被改版得面目全非旧版本再也找不回来。我后来琢磨了一个Python爬虫小项目把它叫做“开源数字博物馆”本质上是一个文档站点快照与长图归档器。输入一个网址它会用requests把页面抓下来用lxml的XPath抽取正文再通过playwright给整页拍一张“全景长图”最后把所有文件按时间归档到本地目录。这个项目就是为了解决“网页会消失”这件事适合做知识库沉淀、文档留存、页面改版对比也适合刚入门的爬虫学习者练手。这篇文章会把手搭环境到跑通全流程完整讲一遍代码都能直接复制使用。1. 这个“开源数字博物馆”到底要解决什么问题1.1 为什么需要网页快照网页会“消失”很多人都有一个错觉觉得东西放在网上就等于永远存在。实际上网页消失的速度比你想象中快得多。我遇到过几次特别心疼的情况一个技术论坛因为维护关闭里面几百篇老帖子全没了某个开源项目把文档站重构老版本的接口说明直接下架还有人写了好几年的博客某天域名到期文章全部404。这些内容一旦失去搜索引擎也救不回来因为源头已经没有了。收藏链接只能算“记住了位置”并不等于“拥有了内容”。真正可靠的方案是在内容还活着的时候把页面以快照形式完整保存到本地。快照的意义不是“复制一份文字”而是把某个时间点页面真实的样子固定下来。等将来网页变了、没了你还能打开本地版本看到当时的排版、当时的配图、当时的完整正文。1.2 快照归档器的核心设计分层保存按需取用我给这个工具定的核心设计理念是“每个网站是一个分馆每个页面是一件展品”。抓下来的内容不是简单堆在一个文件夹里而是按域名、按时间组织成清晰的目录每一层保存不同粒度的信息。一个完整的快照包含三种形态原始HTML、清洗后的纯文本、整页长图。设计成三种而不是一种是因为用途完全不同。原始HTML用于“原样还原”哪怕CSS丢失也能看到最完整的页面结构纯文本用于阅读和检索去掉广告、导航、评论区噪音之后正文可以很方便地复制进笔记软件整页长图用于“打开即看”不需要任何依赖双击图片就能浏览整个页面的全貌。这里的核心取舍是“保真”和“可用”并重。只存HTML虽然完整但离线打开时样式和图片经常出问题只存文本虽然清爽但丢失了版式和视觉信息。让三种形态各司其职归档才真正有价值。1.3 技术选型requests lxml playwright Pillow这个项目的技术栈不算新但每一层都是仔细想过的。requests负责最基本的网络请求足够稳定也好理解。lxml负责解析HTML它的XPath能力在文档类网站里特别好用比正则表达式抗改版能力强太多。playwright负责两件事一是无头浏览器渲染动态页面二是按固定视口高度分段截图。Pillow负责把分段截图拼成一张长图。对比过其他方案Selenium虽然也能做渲染和截图但依赖浏览器driver安装配置相对繁琐纯正则提取正文遇到稍微复杂的页面就崩维护起来像噩梦直接用requests下载HTML不做渲染碰上SPA站点就只有一个空壳。所以这个组合是在“简单够用”和“覆盖动态页面”之间找平衡。工具越简单越好但渲染和截图这两步省不了。2. 环境搭建与爬虫基础先把“展品”抓下来2.1 环境准备与依赖安装我在本地用的是Python 3.9以上的版本。安装依赖这一步建议不要图省事直接pip全局安装先建一个虚拟环境后面项目多了不打架。python3 -m venv .venv source .venv/bin/activate # Windows 下用 .venv\Scripts\activate pip install requests lxml html2text playwright Pillow playwright install chromium这里有个细节值得说一下。playwright不像requests那样装完就能用它还需要单独执行一条playwright install chromium来下载浏览器内核。如果不做这一步后面调用浏览器时就会报错。很多初学者卡在这不是代码写错而是漏了这条命令。2.2 目录结构与档案文件设计整个归档目录我设计成下面这样museum/ ├── index.html ├── archives.json └── sites/ └── example.com/ ├── cover.jpg └── snapshots/ └── 20250114_152030/ ├── raw.html ├── article.md ├── meta.json ├── longpage.jpg └── assets/用域名做分馆目录用时间戳做快照目录。时间戳精确到秒这样同一个页面在不同时间抓取的版本不会覆盖彼此天然形成了“时间线”。raw.html是原始页面文件article.md是清理后的正文longpage.jpg是长图meta.json记录快照的元信息assets存离线化的图片资源。这种结构看着简单但用起来非常顺手。想找历史版本按时间戳排序就行想批量处理遍历sites目录下的snapshots就行。2.3 网络请求基础requests 的抓取细节抓取页面的第一个函数是fetch_html。看起来只是调用requests.get但里面有几个细节决定了成功率。import time import requests HEADERS { User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/125.0 Safari/537.36 } def fetch_html(url: str, timeout: int 15, retries: int 3) - str: last_exc None for attempt in range(retries): try: resp requests.get(url, headersHEADERS, timeouttimeout) resp.raise_for_status() if resp.encoding is None or resp.encoding.lower() iso-8859-1: resp.encoding resp.apparent_encoding or utf-8 return resp.text except requests.RequestException as exc: last_exc exc time.sleep(2 ** attempt) raise RuntimeError(f请求失败: {url} - {last_exc})这函数里我特别想强调的是编码问题。requests在没有charset信息时会默认把encoding设成ISO-8859-1中文网页用这个编码解码直接乱码。所以要在拿到响应后判断一下如果encoding缺失或者被设置成ISO-8859-1就用resp.apparent_encoding重新判断。apparent_encoding是根据内容字节自动检测的大部分中文页面都能正确识别成UTF-8或GBK。重试机制也很重要。网络请求总有偶发超时直接失败会让整个归档任务中断。这里用2的指数退避第一次失败等2秒第二次等4秒第三次等8秒不激进也不拖沓。再加上完整UA伪装成正常浏览器能避免相当一部分站点设置的简单拦截。3. 正文提取与文本清洗用 XPath 精准“策展”3.1 为什么用 XPath 而不是正则一提到“解析网页提取信息”很多人第一反应是写正则表达式。正则适合精确匹配固定格式的数据比如提取所有链接的href、提取电话号码但对“提取一整块正文”这种场景非常不友好。因为HTML结构是嵌套的树正文区域可能是一堆嵌套的div和p正则很难表达“从这个div开始到那个div结束”的边界。XPath把HTML当成一棵树来查询可以直接定位节点也能按属性筛选。比如找一个article标签下的所有段落用正则可能要写几十行用XPath就是一句//article//p。这个项目里提到的python xpath爬虫text函数正是正文提取的关键。文档类网站结构普遍规律用XPath选正文容器再抽取文本比正则稳得多页面做小幅改版也不至于全盘崩溃。3.2 用 lxml 提取页面标题与正文提取标题和正文的代码核心是“候选容器依次尝试”。不同网站的正文容器不同有的用article标签有的用main标签有的用classcontent还有的用idarticle。完全通用是不可能的所以我把常见的选择器列成一个列表逐个尝试谁命中就用谁。from lxml import html as lxml_html def parse_title_and_body(html_text: str): doc lxml_html.fromstring(html_text) title_node doc.xpath(string(//title)) title title_node.strip() if title_node else 未命名页面 candidates [ //article, //main, //div[contains(class,article)], //div[contains(class,content)], //div[contains(class,post)], //div[contains(id,content)], ] node None for xp in candidates: found doc.xpath(xp) if found: node found[0] break article_text if node is not None: article_text extract_clean_text(node) return title, article_text这里有两个容易踩的坑。第一个//title/text()返回的是一个列表而string(//title)返回的是节点内的完整字符串。用text()提取标题时如果title标签里还有嵌套标签text()只会拿到直接文本节点内容可能不完整。用string()更稳妥。第二个候选容器找出来后不要直接按长度判断哪个最合适有些站点aricle标签里可能只有几行摘要。更好的做法是每个候选容器都提取一下文本取文本最长的那个。实操中也可以简单点先按列表顺序取第一个命中的然后检查提取结果少于100字就换下一个。3.3 从 HTML 到干净文本清洗链路的细节提取文本时我优先遍历p、h1到h4、li、blockquote、pre这些段落级标签。为什么不直接取整个容器里的所有文本因为正文容器里经常混着脚本、样式、广告脚本、评论区内容直接text_content()会把一堆噪音一起带出来。def extract_clean_text(node) - str: blocks [] for tag in (h1, h2, h3, h4, p, li, blockquote, pre): for el in node.iter(tag): text el.text_content().strip() if text and len(text) 2: blocks.append(text) return \n\n.join(blocks)lxml的iter(tag)方法会按照文档顺序遍历所有匹配的标签所以段落顺序不会乱。这个函数没有再做复杂的去重是因为日常归档已经够用了。如果想输出Markdown格式可以在遍历时根据标签类型给文本加前缀标记比如h1开头加#、h2开头加##、li开头加-这样生成的文本直接就是一篇结构清晰的Markdown文档。清洗后的文本写入article.md就是给“展品”配的说明书。正文抽取这一步是整个项目里最需要手工调参的地方。我做了一个小小的改进当提取结果不足100字时自动把候选列表往后挪继续尝试下一个选择器。这个阈值可以根据实际页面调整但100字对绝大多数文档页面都适用。4. 整页截图与长图生成给每个页面拍一张“全景登记照”4.1 两种长图生成方案对比长图是整个归档器的灵魂。我在早期版本里尝试直接用playwright的full_pageTrue参数截整页一行代码就能输出一张完整长图。但实际跑了几轮之后发现页面高度超过两三万像素时full_page截图的内存占用猛增生成的PNG体积动辄几十MB打开都费劲。所以我改用“分段滚动截图 Pillow拼接”的方案。思路很简单把页面按固定视口高度切成若干段浏览器每滚到一段就截一张最后用Pillow把每张图按坐标粘到一张大画布上。对比下来各有优劣方案优点缺点full_page 单次截图代码简单无拼接缝隙超高页面内存大单张图片体积惊人分段截图 拼接内存可控可加等待时间触发懒加载步骤多滚动和截取坐标要精确我的建议是默认用分段拼接因为它的可控性更强。懒加载图片需要时间渲染full_page在页面尚未加载完时直接截会发现图片区域是空白分段滚动过程中可以插入等待效果明显更稳。4.2 Playwright 渲染页面并分段截图分段截图的完整流程很长我把其中最关键的一段拿出来说明。首先打开浏览器设置视口宽度1280、高度900。900是经验值太矮截图次数多太高容易触发页面自身的懒加载策略。打开页面后先直接滚到底部再回顶部这一步是为了唤醒所有懒加载图片让它们有时间请求并渲染。import math from io import BytesIO from pathlib import Path from PIL import Image from playwright.sync_api import sync_playwright SCREENSHOT_WIDTH 1280 SCREENSHOT_HEIGHT 900 def capture_long_screenshot(url: str, output_path: Path): with sync_playwright() as p: browser p.chromium.launch(headlessTrue) page browser.new_page(viewport{ width: SCREENSHOT_WIDTH, height: SCREENSHOT_HEIGHT }) page.goto(url, wait_untilnetworkidle, timeout30000) # 先滚到底再回顶触发懒加载 page.evaluate(window.scrollTo(0, document.documentElement.scrollHeight)) page.wait_for_timeout(800) page.evaluate(window.scrollTo(0, 0)) page.wait_for_timeout(500) total_height page.evaluate(document.documentElement.scrollHeight) total_height max(total_height, 1) segments math.ceil(total_height / SCREENSHOT_HEIGHT) canvas Image.new(RGB, (SCREENSHOT_WIDTH, segments * SCREENSHOT_HEIGHT), white) for i in range(segments): y i * SCREENSHOT_HEIGHT clip_h min(SCREENSHOT_HEIGHT, total_height - y) page.evaluate(fwindow.scrollTo(0, {y})) page.wait_for_timeout(400) shot page.screenshot(clip{ x: 0, y: y, width: SCREENSHOT_WIDTH, height: clip_h }) im Image.open(BytesIO(shot)).convert(RGB) canvas.paste(im, (0, y)) canvas.save(output_path, formatJPEG, quality92, subsampling2) browser.close()这段代码里有几个细节要特别讲。第一个是clip参数里的height。最后一段的剩余高度可能小于900如果仍然传900playwright会尝试截取超出页面范围的内容结果可能报错也可能截出透明区域。用min(SCREENSHOT_HEIGHT, total_height - y)做保护就稳了。第二个是滚动和截图之间要加400毫秒等待。滚动动画和图片加载都需要时间如果滚完立即截图画面会停留在半加载状态。第三个是Pillow的convert(RGB)playwright截出来的图是RGBA格式直接粘贴到RGB画布上会出现模式不匹配的警告先转换再粘贴就没事了。4.3 Pillow 拼接与超长页面内存控制Pillow拼接的思路很简单建立一张宽1280、高为页面总高度的画布然后按顺序把每一段截图粘贴到对应的y坐标。由于roll坐标和clip坐标完全一致只要没有页面自身动画干扰拼接效果基本是无缝的。这里有一个容易翻车的地方有些页面设置了scroll-behavior: smooth滚动不是瞬间到位而是有一段动画。滚动还没结束时截图已经发生就会出现两张图边缘重叠或错位。遇到这种情况可以在打开页面后先注入一段JS把平滑滚动强制覆盖成自动滚动page.add_script_tag(contentdocument.documentElement.style.scrollBehaviorauto;)另外超长页面保存成JPEG而不是PNG可以明显减少体积。PNG是无损压缩一张5万像素高的长图可能到100MBJPEG的quality92肉眼几乎看不出差别体积却能压到几MB以内。如果是本地归档我通常还会生成一张封面缩略图只截长图顶部300像素用于展厅卡片展示避免页面加载整张长图卡顿。5. 离线化与展厅页面把抓到的内容变成可以长期浏览的归档5.1 离线化下载页面图片到本地用requests抓回来的raw.html直接保存是能看的但有一个问题HTML里引用的图片、CSS、JS仍然是外链地址一旦断网或者目标站点关闭这些资源照样加载不出来。为了让快照真正“离线可用”我在保存之前会把页面里的img标签的src批量下载到本地assets目录并把HTML里的引用改成相对路径。import hashlib from urllib.parse import urljoin def download_assets(html_text: str, base_dir: Path, site_url: str) - str: doc lxml_html.fromstring(html_text) assets_dir base_dir / assets assets_dir.mkdir(exist_okTrue) for img in doc.xpath(//img[src]): src img.get(src) if not src: continue full_url urljoin(site_url, src) try: resp requests.get(full_url, headersHEADERS, timeout10) if resp.status_code ! 200: continue ext Path(src).suffix or .img name hashlib.md5(full_url.encode()).hexdigest() ext local_path assets_dir / name local_path.write_bytes(resp.content) img.set(src, fassets/{name}) except Exception: continue return lxml_html.tostring(doc, encodingunicode, pretty_printTrue)这段代码有三个设计考量。第一文件名用URL的MD5值而不是原始文件名避免两个页面存在同名图片互相覆盖。第二每个图片下载都包在try里单个资源失败不阻塞整站归档。第三urljoin用来处理相对路径比如src/images/a.png时可以拼出完整的绝对URL。对很多不懂HTML的读者来说这一步做完离线快照才算真的完整。5.2 生成 meta.json 与 archives.json 索引每生成一个快照我都会写两个JSON文件。第一个是快照目录内的meta.json记录单个页面的元信息第二个是项目根目录的archives.json聚合所有快照方便程序整体扫描。{ title: 示例技术文档如何使用XPath抽取正文, url: https://example.com/docs/xpath-guide, domain: example.com, timestamp: 20250114_152030, html_file: raw.html, text_file: article.md, image_file: longpage.jpg, html_size: 58234, text_size: 8322 }archives.json则是这个对象的列表每次新增快照就追加一条。有了这个全局索引后续想扩展全文搜索、按时间线浏览、做页面变更对比都不用再去遍历文件夹直接读JSON就行。它为项目保留了扩展空间。5.3 一键生成 index.html 展厅页面直接让用户去翻sites目录下的文件不现实所以我用一个很轻量的方式生成展厅页面根目录的index.html会把所有快照渲染成卡片每张卡片显示封面缩略图、标题、抓取时间、原文链接点击后可以打开长图或正文。def render_index_html(records: list[dict]) - str: cards [] for rec in records: cover fcover_{rec[domain].replace(., _)}.jpg cards.append(f div classcard img src{cover} loadinglazy altcover h3{rec[title]}/h3 p{rec[timestamp]}/p a hrefsites/{rec[domain]}/snapshots/{rec[timestamp]}/longpage.jpg查看长图/a a hrefsites/{rec[domain]}/snapshots/{rec[timestamp]}/article.md阅读正文/a /div ) return f!doctype html html langzh-CN headmeta charsetutf-8title我的数字博物馆/title style body {{ font-family: sans-serif; max-width: 1200px; margin: 0 auto; padding: 24px; }} .grid {{ display: grid; grid-template-columns: repeat(auto-fill, minmax(280px, 1fr)); gap: 16px; }} .card {{ border: 1px solid #ddd; border-radius: 8px; padding: 12px; }} .card img {{ width: 100%; max-height: 220px; object-fit: cover; object-position: top; border-radius: 4px; }} .card a {{ display: block; margin-top: 6px; color: #0366d6; text-decoration: none; }} /style /head body h1我的数字博物馆/h1 div classgrid{.join(cards)}/div /body /html封面缩略图的生成很简单在保存长图之后用Pillow把长图顶部300像素crop出来作为cover文件保存。这样展厅页面的卡片加载速度快也不会因为长图尺寸过大导致浏览器卡顿。这套页面不需要任何服务端逻辑双击index.html直接在本地就能看非常符合“归档”的定位。6. 常见问题与排查技巧实录6.1 提取内容为空先判断是XPath问题还是渲染问题我在调试时遇到最多的情况是parse_title_and_body返回的正文是空的。刚开始会以为是XPath表达式写错了反复改选择器都没有效果。后来才发现问题根本不在解析层而是目标页面是纯JavaScript渲染的SPArequests拿到的HTML里只有空壳div根本没有正文内容。排查顺序应该是先用requests抓到的HTML里搜一下关键字如果正文的关键词根本没出现说明页面需要渲染如果关键词出现了才轮到XPath的问题。需要渲染的页面可以在请求成功后额外调用一个渲染函数用playwright打开页面等networkidle之后取page.content()。这个渲染后的HTML再交给XPath解析通常就能正常提取了。6.2 长图拼接出现裂缝或重复分段截图理论上不会出现裂缝但如果页面存在固定定位的头部导航栏滚动到每一段时导航栏都固定在顶部最后拼出来的长图每隔900像素就会重复出现一次导航栏。这个不需要逐段去P图可以在截图前用print样式模式弱化页面装饰page.emulate_media(mediaprint)很多站点为打印场景优化过样式会隐藏固定导航、广告区域正文区域反而更干净。如果站点不响应打印样式也可以在截图前执行JS把fixed元素隐藏掉但不建议对所有页面都这样处理容易误伤正常布局。6.3 超长页面截图内存爆炸高度超过3万像素、又有很多高清图片的页面即使分段截图Pillow拼接时也会占用大量内存。除了把最终保存格式改成JPEG我还会设置一个“最大高度”保护当页面高度超过5万像素时只截前3万像素并且在meta.json里标记“已截断”。这个妥协是不得已的。绝大多数文档站不会长到这个程度但确实遇到过产品文档页面一次性加载了几百个模块页面高度突破天际。归档的关键是保住主要内容头部信息通常就是核心截断尾部影响不大。等以后需要截全时再针对性调参数就行。6.4 中文乱码的处理乱码问题在上一部分已经提过核心就是requests的encoding属性。resp.encoding为空时必须重置否则中文内容会变成一堆问号。更稳的做法是直接用resp.content配合chardet检测再解码但apparent_encoding已经能满足绝大多数场景。如果遇到个别页面声明charset错误可以在fetch_html之后手动检查一个关键词比如“正文”这两个字是否出现没出现就尝试用其他编码重新解码。6.5 定时归档用快照做页面变更对比数字博物馆不应该只拍一次照就完事好东西会更新页面会改版定期补拍才能形成时间线。我后面给项目加了一个定时扫描功能用系统定时任务每天跑一次归档脚本每次抓完都用hash对比当前HTML和上次快照的差异发现变化就生成一个diff文件。这样不仅能做备份还能追踪页面内容的每次变更。这在跟踪线上文档更新时特别实用。归档器的合规边界同样要讲清楚。这个工具适合归档自己有权访问的公开页面比如技术文档、个人博客、允许爬取的开放内容。使用前最好看一下目标站点的robots.txt尊重站点声明。遇到需要登录、有明确访问限制或设有反爬机制的页面就应该停下来不要尝试对抗或破解。我们的目标是把值得保存的公开内容保护下来而不是和站点本身的访问控制较劲。写在最后用了半年多这个“开源数字博物馆”已经攒下上百个快照里面有不少是现在互联网上已经搜不到的旧内容。个人体会最深的一点是归档的意义不在于收藏本身而在于给内容留下了“第二次生命”。每次翻那些早期截图我都庆幸当时多花了30秒启动脚本。最后分享一个小技巧归档时一定要在meta.json里把页面标题写清楚。我早期贪图省事文件名只用了时间戳三个月后根本记不住某个快照是什么内容。后来给每个快照自动生成“站点名页面标题时间”的可读目录名翻起来舒服太多了。这个项目后续还有很多可以扩展的地方比如全文检索、按关键词聚类、压缩旧快照但核心思路始终不变——先把页面当下这一刻完整地保存下来。