企业官网建设流程全解析

这些年我养成了一个习惯：凡是觉得以后可能还会翻出来看的网页，都会顺手做一份快照。因为踩过太多次“收藏夹里躺着一堆404”的坑，尤其是那些写得很好的技术文档、接口说明、教程长文，说没就没，连个缓冲的余地都不留。后来我干脆用Python写了一个小工具，把“抓取页面 -> 生成快照 -> 拼成长图归档”这条链路整个自动化，也就是标题里说的“文档站点快照与长图归档器”。这篇文章就把这套工具从需求拆解到代码实现、再到排坑实录完整过一遍。

这套工具解决的是三个很具体的痛点：一是网页内容失效，二是文档资料碎片化，三是长文不便保存和分享。把它做好之后，一条命令就能把一个页面变成一份带完整样式的HTML快照和一张长图，归档到本地目录里，随时能查、能翻、能分享。如果你平时有收集资料、存档报道、维护个人知识库的需求，或者刚学Python爬虫想找一个完整的实战项目练手，这篇内容应该能给你一个可以直接落地复现的参考方案。

1. 需求拆解与整体设计思路

在动手写代码之前，我得先把“文档站点快照与长图归档器”这个标题拆成三个关键词来理解：爬虫、快照、归档。

爬虫解决的是“把内容拿下来”的问题，快照解决的是“把内容定格在某个时间点”的问题，归档解决的是“拿下来的东西怎么组织、怎么长期保存”的问题。这三件事听起来是线性关系，但其实每个环节都有自己的独立难点，放到一起做，需要先想清楚取舍。

1.1 这个工具到底解决什么问题

最朴素的使用场景是这样的：你在网上看到一篇写得很扎实的技术文档，比如某个框架的源码解析、一套运维排障手册，或者一份接口对接协议。你收藏了，甚至复制粘贴到笔记软件里。然后某一天，站点改版了，或者站长关站了，这些内容就再也找不回来了。

复制粘贴的笔记也有问题——图片是外链的，样式是丢掉的，代码块是高亮失效的，页面里大量上下文信息根本没法通过“选中文本再粘贴”来保留。如果你是想长期保存一份“当时看到的样子”，那么真正的解决方案是给整个页面做一次快照：把HTML抓下来，把图片、样式、脚本这些资源也一起下载下来，让这份快照在本地能完整复现当时页面的状态。

那为什么还要长图？因为HTML快照虽然完整，但分享和快速预览不太方便。你给别人发一个HTML文件，对方不一定愿意打开，手机上看起来也费劲。而长图是通用性最好的载体，微信、邮件、笔记软件都能直接展示，也便于打印和二次编辑。所以说，快照负责“完整保真”，长图负责“方便流通”，两者是互补关系。

归档器则是把这两类产物统一管理起来：按域名、按日期、按标题组织目录，生成一个索引，避免“快照存了一大堆，想找的时候根本不知道哪个是哪个”的尴尬。这一层功能看起来不起眼，但实际操作下来，我觉得它才是决定这个工具能不能长期用下去的关键。

1.2 技术方案选型与取舍

技术选型上，我并没有一上来就上Scrapy这种重型框架，而是用了requests加lxml的轻量组合，原因有几点。

第一，这个场景不是大规模采集，而是“按需抓取”，一次只处理几个或者几十个URL，Scrapy的并发调度能力在这里属于杀鸡用牛刀。第二，requests加lxml的学习曲线低，代码逻辑直白，出问题好排查。第三，对于需要抓动态渲染页面的场景，我单独用Playwright做补充，这样动静分离，哪些页面用静态抓取、哪些页面走无头浏览器，完全由配置决定，能省不少时间。

快照层面的选型，核心是决定用什么方式保存页面。我试过两种路线，一种是直接把整个网页保存为单个HTML文件，另一种是把页面内的资源全部下载下来、把链接改成相对路径。前者的优点是简单、文件数少，但有些站点的CSS和JS比较复杂，内联后可能出现样式错乱。后者保真度高，但会生成大量零散文件，管理成本高。

我最后的选择是：正文类页面优先做“单文件HTML快照”，用工具把所有资源内联进去；如果遇到资源特别多、内联后文件过大的情况，就退化为“HTML加资源目录”的保存方式，页面主文件保留，图片和样式按原路径结构存放到assets目录里。

长图生成这一层，我对比过三套方案，细节放在后面第3章细说，这里先给结论：最省事的是用无头浏览器直接截图整个页面，最可控的是自己用Pillow把多段截图拼起来。我的工具默认走Playwright整页截图，因为它的渲染效果最接近真实浏览器，代码量最少；但当页面过长（超过20屏）或者某些元素在滚动加载时会变化时，我会退回到分段截图加Pillow拼接的方案。

2. 核心模块一：页面抓取与正文提取

这一章先把整条链路的第一个环节讲透：如何稳定地把一个文档页面的内容抓下来，并且把正文从一堆导航、侧边栏、广告、推荐阅读里剥离出来。这一步做得好不好，直接决定了后续快照和长图的质量。

2.1 请求层：头信息、超时、重试与限速

写爬虫这么多年，我最大的体会是：请求层是翻车率最高的地方，但恰恰是很多人最不重视的地方。很多人写爬虫就是一行requests.get(url)，然后就开始为各种报错头疼。

一个规范的请求层，至少要有这么几样东西：浏览器风格的User-Agent、Accept、Accept-Language这些头信息；超时设置；重试机制；以及对目标站点的基础限速。

我自己常用的写法是构造一个session对象，统一设置headers，然后用requests.adapters.HTTPAdapter把重试逻辑挂载到session上。这样在代码里就不需要到处写try except重试，HTTP连接层面的临时故障会自动处理。

import requests from requests.adapters import HTTPAdapter from urllib3.util.retry import Retry session = requests.Session() session.headers.update({ "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36", "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,*/*;q=0.8", "Accept-Language": "zh-CN,zh;q=0.9,en;q=0.8", }) retry_strategy = Retry( total=3, status_forcelist=[429, 500, 502, 503, 504], allowed_methods=["HEAD", "GET", "PUT", "DELETE", "OPTIONS", "TRACE"], backoff_factor=0.5, ) adapter = HTTPAdapter(max_retries=retry_strategy) session.mount("http://", adapter) session.mount("https://", adapter)

这里有几个值得说透的细节。status_forcelist里的429表示“请求太频繁”，很多站点用这个状态码做限流，遇到它自动重试是对的，但必须配合backoff_factor做退避，否则就是加重对方服务器压力，也容易被封。Retry默认不会重试POST之类的方法，但我建议allowed_methods里只保留GET和HEAD，因为快照抓取场景里根本没有POST请求的必要。

超时设置也得分两个维度：connect超时控制建立连接的最长时间，read超时控制读取响应的最长时间。很多文档站点的响应并不快，尤其是一些老旧的文档系统，read超时给到30秒是合理的，connect给10秒就差不多了。连接都建立不了的情况，10秒内该失败早就失败了。

最后是限速。我做快照是一个一个页面顺序抓取的，每个请求之间sleep一下，一般1到2秒。这个速度对个人归档场景完全够用，又不至于对目标站点造成压力。

2.2 正文提取：标题、时间、正文容器与清洗规则

拿到HTML之后，解析层就上场了。我的解析流程是：先解析标题，再找发布时间，最后定位正文容器，然后对正文做清洗。

标题的提取比较简单，绝大多数页面都有h1标签，而且文档站点一般一个页面只有一个h1，直接取第一个h1的文本即可。但如果h1的内容是“首页”“文档”“帮助”这类导航性文字，就说明这个页面可能不是正文页，需要靠后续的正文提取来判断。

发布时间的提取麻烦一些。有的站点有meta标签，有的把时间写在页面里。我的策略是优先读meta标签里的article:published_time，如果没有，就用正则去常见的时间格式里碰，例如：

import re def extract_pub_time(html_text): patterns = [ r'property="article:published_time" content="([^"]+)"', r'name="pubdate" content="([^"]+)"', r'<time[^>]*datetime="([^"]+)"', ] for pat in patterns: m = re.search(pat, html_text, re.IGNORECASE) if m: return m.group(1) return ""

正文定位是这层的关键。文档站点通常结构规律，正文容器多集中在article、main、div[class*=content]、div[id*=content]这类节点里。我的做法是给候选节点打分：节点内文本长度、链接密度、段落数量、代码块数量，综合加权后取分数最高的节点作为正文区域。

链接密度这个指标很实用。一个纯正文的容器，链接密度应该很低；如果某个容器里全是“相关阅读”“热门推荐”，那链接密度必然畸高。用这个特征能过滤掉绝大多数干扰。

正文拿到之后，清洗也有讲究。不是把标签一删就完事，而是要保留结构信息。我保留p、h2、h3、pre、code、ul、ol、li这些标签，去掉script、style、ins、iframe这些无关元素。顺便把图片标签里的src和alt保留下来，这样后面做长图展示时图片不会丢。

2.3 资源本地化：让快照真正“独立存活”

很多人理解的网页快照就是Ctrl+S存个网页，但真正意义上的快照，必须做到“断网也能完整打开、样式图片全部在本地”。这就要处理资源本地化。

处理思路是两步：第一步，扫描页面里所有需要加载的资源，包括img的src、link的href、script的src，可能还有CSS里通过url()引用的图片和字体；第二步，逐个下载这些资源，然后把页面里的URL替换成本地路径。

听起来容易，做起来坑不少。最大的坑是相对路径和绝对路径的混用：有的资源是完整URL，有的是以斜杠开头的站点相对路径，有的干脆是“../../images/xxx.png”这种目录相对路径。统一处理的办法是先用urljoin把相对路径拼成完整URL，再统一做下载。

from urllib.parse import urljoin, urlparse import os def localize_resource(page_url, resource_url, save_root): full_url = urljoin(page_url, resource_url) # 按路径结构生成本地保存路径 parsed = urlparse(full_url) path = parsed.path.lstrip("/") if not path or path.endswith("/"): path = path + "index.html" local_path = os.path.join(save_root, parsed.netloc, path) return full_url, local_path

第二个坑是防盗链。不少站点会检查Referer头，不允许外部站点直接引用它的图片。下载资源的时候，我得把Referer设置成原始页面URL，这个细节不处理的话，快照里会有一堆破图。

第三个坑是CSS里的资源。有些页面的背景图、字体文件是从CSS里引用的，如果只处理HTML里的标签，快照的样式还是会缺。精细一点的方案是用CSS解析器去扫描CSS内容里的url()，然后把它们也下载下来。但我要提醒你，这个操作有点费劲，而且收益看站点。我的策略是：文档站点这种以文字和代码为主的页面，优先保证HTML里的图片资源本地化，CSS背景图这类资源允许失败。

3. 核心模块二：从快照HTML到长图

HTML快照负责“完整保真”，但绝大多数人日常更愿意看长图。这一章讲清楚从已经保存的HTML到最终长图，中间到底发生了什么，以及每一条路线各自的优劣势。

3.1 三种主流截图方案对比

我在做长图生成的时候接触过三类方案，这里直接上结论对比：

先说HTML转PDF再转图片这条路。工具本身很成熟，但你会发现一个问题：文档站点的正文宽度一般被限制在800像素左右，但PDF渲染出来后，放大到宽图时字体和间距会有微妙的变化。更麻烦的是，代码高亮这个东西在PDF渲染时经常丢样式，因为代码块通常是用span标签加行内样式实现的，而PDF渲染器对行内样式的支持有时候不太稳定。这条路适合“我已经有一份稳妥的HTML，只想顺便出一版PDF存档”的场合，不适合作为长图的主要生成手段。

无头浏览器整页截图是目前最主流的方式。它的逻辑就是打开一个真实的浏览器内核，把页面加载出来，然后调接口把整个页面画到一张图上。用Playwright做这事，代码量非常小，而且对懒加载、异步渲染、CSS动画都有比较好的支持，因为浏览器引擎帮你处理了这一切。

分段截图再拼接属于保底方案。当页面超过一定长度，无头浏览器整页截图会超时或内存溢出，这时候就手动控制滚动，每滚动一屏截一张图，最后用Pillow拼起来。缺点在于某些页面滚动时会触发懒加载，而滚动期间有些元素可能来不及渲染，拼出来的长图会出现内容缺失。

3.2 Playwright截图的完整实操

我当前的实现默认走Playwright。具体做法是：启动一个无头Chromium实例，设置合适的视口宽度，打开页面，等待网络空闲，然后截图。

这里有一个关键调优点：视口宽度。桌面端的文档页面在1200像素到1440像素之间会有一个比较舒服的排版宽度，长图做出来在电脑上看得清楚。但我实际测试发现，很多文档站点在响应式布局下，超过某个宽度反而会把侧边栏展开，导致正文区域变窄。所以我一般把视口宽度设置成1440像素，然后判断正文区域的实际宽度和位置，截图时精确裁剪到正文区域。

from playwright.sync_api import sync_playwright def capture_full_page(url: str, output_path: str, max_height: int = 30000): with sync_playwright() as p: browser = p.chromium.launch() page = browser.new_page(viewport={"width": 1440, "height": 900}) page.goto(url, wait_until="networkidle", timeout=60000) page.wait_for_timeout(1000) # 手动触发一下滚动，让懒加载的内容渲染出来 page.evaluate(""" async () => { const scrollHeight = document.body.scrollHeight; const step = window.innerHeight; for (let y = 0; y < scrollHeight; y += step) { window.scrollTo(0, y); await new Promise(r => setTimeout(r, 100)); } window.scrollTo(0, 0); } """) height = page.evaluate("document.body.scrollHeight") if height > max_height: raise Exception(f"页面高度 {height} 超过上限 {max_height}，建议走分段截图方案") page.screenshot(path=output_path, full_page=True) browser.close()

这段代码里有三个细节值得注意。

第一个是wait_until="networkidle"。它表示等待所有网络请求都结束才继续执行。但有些页面有轮询请求，每隔几秒就发一次心跳，networkidle可能会一直等不到，导致超时。我在实际使用里会把超时设成60秒，并且如果networkidle等不到，就退而求其次用domcontentloaded，多等几秒再截图。

第二个是手动滚动的这个动作。很多文档页面有图片懒加载，如果用full_page直接截图，往往底部的内容还没加载出来，图片位置全是空白。我特意先让页面从上到下滚动一遍，每100毫秒滚一屏，让懒加载的图片有时间完成请求，然后再滚回顶部，最后才截整页图。这个步骤看着多此一举，实际对长图完整性影响很大。

第三个是max_height的上限判断。页面超过3万像素的时候，整页截图的内存压力会很大，我见过截出来的图直接花屏的情况。所以超过这个阈值就改用分段截图，不硬扛。

3.3 长图后处理：拼接、裁剪和压缩

如果走分段截图的保底方案，那就要用Pillow处理拼接。我的做法是：固定视口宽度，每次滚动一个固定距离，然后滚动偏移取整，避免相邻两张截图出现缝隙或者重叠。

from PIL import Image import os def stitch_images(segments_dir: str, output_path: str): imgs = [] for name in sorted(os.listdir(segments_dir)): if name.endswith(".png") or name.endswith(".jpg"): imgs.append(Image.open(os.path.join(segments_dir, name))) width = max(img.width for img in imgs) total_height = sum(img.height for img in imgs) canvas = Image.new("RGB", (width, total_height), "white") y = 0 for img in imgs: canvas.paste(img, (0, y)) y += img.height canvas.save(output_path, quality=90)

拼接的思路是创建一个足够高的空白画布，然后按顺序把每一屏的截图贴上去。这里的细节集中在滚动步长的计算上：如果用固定像素滚动，浏览器总会有亚像素的取舍，相邻截图可能会有几像素的偏差。我的做法是先用evaluate取页面总高度，除以屏幕数量，得到一个平均步长，再从0开始按步长累加滚动，每张截图后用window.scrollY的返回值校正下一步的位置，确保滚动距离严格对齐。

长图做出来之后，还有个压缩的问题。一张完整的文档长图，动辄三四千像素高，如果不压缩，一张图可能好几MB，发微信会被自动压缩成渣。我的习惯是把长图限制在2MB以内，通过调整JPEG压缩质量来实现，正文类页面质量降到85，肉眼看不出区别，体积却少很多。如果是代码为主的页面，我保存成PNG，因为代码区域有大量纯色块和文字，PNG压缩率其实不差，还不会有JPEG带来的文字边缘噪点。

4. 核心模块三：归档管理与增量更新

快照和长图都生成了，如果只是丢在一个乱糟糟的文件夹里，那这个工具还缺最后一公里。个人文档归档器要想长期用下去，组织方式非常重要。

4.1 目录结构设计

我采用的目录结构是按站点和日期组织的。结构上长这样：

archive/ ├── index.json ├── www.example.com/ │ ├── 2025-01-15/ │ │ ├── 001-how-to-build-snapshot/ │ │ │ ├── snapshot.html │ │ │ ├── assets/ │ │ │ ├── page.png │ │ │ └── meta.json

第一层是域名，第二层是抓取日期，第三层是编号加标题片段。这样的好处一目了然：你想回顾某个站点某天抓了什么，直接进对应文件夹；不同站点之间不会互相污染；同一个页面抓了多次也互不影响。

但这里有一个必须想清楚的坑：一天之内同一个URL可能会被抓多遍，如果都用同一个日期目录，新文件会覆盖旧文件。我的策略是在文件重名时追加时间戳后缀。归档这种事，宁可多存几份“同一内容的历史版本”，也不要让新快照悄悄覆盖掉旧的有用信息。

meta.json这个文件不是为了装样子而存在的，它记录了抓取时间、目标URL、页面标题、当时的HTTP状态码、快照文件大小、长图文件大小这些信息。这些信息在后期检索和维护时会非常有用，比如你能快速揪出哪些页面抓取失败了，哪些页面体积异常大，哪些页面当时返回了重定向。

4.2 索引与检索：让资料变得可查

文件目录有了，我还会额外维护一个index.json，作为整个归档器的索引。每次抓完一个页面，就把页面的元信息和关键字段追加进索引。

index.json的结构很轻量，就是一个数组，每个元素对应一次归档。字段包括publish_time、title、url、local_path、screenshot_path、archived_at和domain。为什么要做成JSON而不是塞进某个数据库？因为这个归档器的体量就是千级以下文件，一个JSON文件几十KB，打开和修改都很快，而且可以直接被git追踪，通过git来管理历史变更。

有了这个索引，后续可以做的事情就多了。比如写一个简单的搜索函数，按关键词过滤title和正文前200字；再比如用FastAPI包一层HTTP接口，做成个人知识库的后端。不过这些都属于扩展玩法，核心还是先建立起“每一份快照都有明确索引”的纪律。

4.3 增量更新与去重策略

文档站点是活的，今天抓的快照，下周可能就更新了。归档器诞生第一天就要思考增量更新问题。

我采用的策略是：以URL为主键做去重。每次归档前，先查index.json里有没有同一URL的记录。如果没有，全量抓取。如果有，就检查这次抓到的页面和上次快照是否有内容差异，比较方式是对正文容器的文本做哈希比对。有差异才更新，没差异就不重复生成长图，只更新元数据里的last_checked时间。

文本哈希比对这件事，看起来要写不少代码，但实际上就是取正文区域之后调一下hashlib，非常简单。关键是你要在提取正文之后、生成快照之前做这一步。这样“是否值得重新生成长图”在早期就被决定，可以省下大量截图开销。

import hashlib def fingerprint_text(content_element_text: str) -> str: return hashlib.md5(content_element_text.encode("utf-8")).hexdigest()

另一个值得说的去重策略是“面向内容的重复检测”。有些文档站点会有转载内容，不同URL指向的正文内容是一样的。在index.json里顺便记录正文的指纹哈希，归档时如果发现新页面与已有页面的哈希相同，我就可以选择不新增记录，而是给已有记录追加一个新的URL别名。这对搜索引擎优化、对个人知识库的整理都有很实际的意义，能让归档器里尽量少存重复内容。

5. 实操全流程与高频问题排查

前面几章把核心模块的原理讲透了，这一章面向实际操作，从环境准备到完整跑通，再到常见问题排查，一次性给你一套可复现的流程。

5.1 从零跑通完整流程

先交代环境。我在Windows和Linux上分别跑过这套工具，Python版本用的是3.10以上，主要依赖是requests、lxml、Pillow和playwright。前三个装起来很快：

pip install requests lxml Pillow pip install playwright playwright install chromium

playwright install这一步会下载一个Chromium内核，体积不小，但这是整页截图的基础设施，躲不掉。国内网络环境如果下载慢，可以考虑设置playwright的下载镜像。

代码组织上，我建议不要把所有逻辑塞在一个文件里。我的实际工程结构是：

snapshot_archiver/ ├── config.py # 限速、超时、目录配置 ├── fetcher.py # 请求层 ├── parser.py # 正文提取和清洗 ├── localizer.py # 资源本地化 ├── screenshot.py # 长图生成 ├── archiver.py # 归档管理和索引更新 └── cli.py # 命令行入口

跑通的流程是：读待归档URL列表，逐个抓取，提取正文和元信息，做指纹去重，然后生成HTML快照和长图，最后更新索引。

5.2 高频问题：从403到乱码再到拼接白条

我在这套工具的迭代过程中遇到不少问题，挑几个典型的，连同排查思路列在下面：

403这个问题我要多说两句。很多人一遇到403就想到“封IP”或者“绕过限制”，但在归档这个场景里，绝大多数情况只是你的请求长得太像爬虫。先补全请求头，再降低频率，往往就解决了。如果对方站点确实明确禁止爬虫，技术上你总有办法继续，但合规层面就必须停下来，这个原则我在第5.3节展开说。

乱码问题也很典型。文档站点大多是UTF-8，但老站经常出现GBK和GB2312。我的做法是写一个统一的decode_response函数，优先用响应头里charset参数，如果没有就在前1024个字节里做charset检测，实在不行才用apparent_encoding。

5.3 合规红线、抓取边界与个人经验

爬虫这个领域，技术本身就是中性的，但使用场景有边界。我这个归档器从设计的初衷就是“个人备份自用”，所以有两条线我始终坚持。

第一，只归档我有权访问的内容，不绕登录墙，不破解权限。站点公开可访问的内容，我做一份本地快照自用，这跟用户用浏览器看一遍、再存个书签没有本质区别。但如果内容是登录后才能看的，那就不能通过技术手段绕过。第二，抓取频率必须克制。归档器的定位是低频工具，不是抢票软件，默认1到2秒一个请求已经很够了，没必要把对方服务器打得喘不过气。

再补充一点合规层面的经验：机器人协议文件我建议花一分钟看看，如果对方的robots里明确禁止爬虫抓取，那就尊重这个约定。有些站点即使没写，但是服务条款里有相关声明，也一样要遵守。个人存档用途和技术讨论是一回事，碰触到版权和商业利益的边界就是另一回事了。

关于频率控制，我有个比较保守但省心的实现：用一个简单的装饰器，在所有“对外发请求”的函数上统一做限速。这样就算新增了抓取规则，也不会忘了限速逻辑。

import time import functools _last_request_time = 0.0 def rate_limit(min_interval=1.0): def decorator(func): @functools.wraps(func) def wrapper(*args, **kwargs): global _last_request_time elapsed = time.time() - _last_request_time if elapsed < min_interval: time.sleep(min_interval - elapsed) result = func(*args, **kwargs) _last_request_time = time.time() return result return wrapper return decorator

6. 写在最后：归档之外的思考

这套文档站点快照与长图归档器，我陆陆续续用了大半年，中间迭代了好几个版本。最初它只是解决我自己的痛点——某些技术文档站点频繁改版，旧链接成片地失效，我连备份都没留下。后来的价值渐渐超出工具本身：当我开始用git来管理整个archive目录时，它实际上变成了个人版的网页时光机。每次快照提交上去，目录的索引也会变化，整个演进历史一目了然。

我特别想分享的一个小技巧是：把归档器接到定时任务里，每周跑一次，对收藏夹里的核心URL做一次增量抓取。更新过的正文会被自动发现，新版本会生成新的快照，老版本保留，长图也随之更新；长期运行下来，你手上就多了一份“谁在什么时候改了什么”的信用记录，这在查证资料时非常有用。

另外，这套代码的可复用性很高。爬虫抓取、正文提取、快照保存、长图生成这几个模块，单独拿出来也能用在其他项目里，比如批量抓取在线文档并整理成离线阅读包、监控某个页面是否更新、甚至把长图生成用于新闻报道存档。如果你自己动手把这一套跑通了，后面各种知识管理相关的需求都能顺着这个思路延展。