简介pywebcopy 是一款用 Python 编写的网页镜像与归档工具面向需要离线保存网页、网站资源或研究爬虫实现的开发者。它尊重 robots.txt一次调用即可把 CSS、JS、图片等资产连同页面完整下载并能重新映射链接、克隆整站API 简洁且支持子类定制。这份资源包共 32 个文件以 py 源码为主19 个另有 md 文档、yml 配置与测试文件整体仅 65KB结构紧凑。已有 569 人学习下载适合 Python 中阶开发者对照源码学习网页爬取、解析器和归档工具的设计思路。除核心爬取与解析外还包含异常处理、配置、命令行入口等模块可帮助读者快速上手二次开发或作为网页克隆功能的轻量参考实现。1. 从一段 HTML 到整站离线能用 pywebcopy 解决什么镜像网页这事儿听起来简单但真做起来全是细节。用爬虫框架从头写你要处理 URL 去重、资源解析、目录规划、编码转换还得应付加载不全的样式和死链。这套基于 pywebcopy 的 Python 镜像方案把上面这些脏活封装成十几个可调参数——你给一个 URL它把页面 HTML、CSS、JS、图片按原站结构落到本地双击 index.html 就能离线浏览。对要快速归档项目文档、保存技术手册、给静态站点做本地快照的开发者来说比逐个“另存为”高效得多。它不是爬虫框架不做数据分析专注在“把页面完整搬到本地”这一件事上。这份资源的核心价值是把镜像流程沉淀成了可复用的 Python 模块你拿到源码包改改配置就能跑不需要从零设计爬虫架构。2. 镜像的底层机制与首条可跑通的命令为什么它能“照搬”整个页面2.1 镜像与普通下载的本质差异先把概念边界划清楚。requests.get(url).text 拿回来的是服务端渲染后的 HTML 文本里面引用的 style.css、app.js、logo.png 都还是远程绝对路径或相对路径。你在本地打开这个 HTML浏览器会去请求远程资源没有网就是白板一片。pywebcopy 这类库的思路不同它分三步走抓取入口页面 HTML用 HTML 解析器把文档对象模型建出来遍历 DOM 里所有带 src、href、data-src 属性的节点归一化 URL逐个下载资源重写本地 HTML 里的资源路径让它们指向本地文件同时保持目录结构第二步里有个关键点css 文件内部的 url(../fonts/xxx.woff2) 引用也需要解析重写。README 里的“html-parser、archive-tool”这两个关键词对应的就是 DOM 解析和资源归档机制。如果你只用正则去匹配 http:// 开头的链接大概率会漏掉 JS 动态插入的资源也会漏掉 CSS 内部引用。pywebcopy 的处理方式是逐级递归下载 HTML → 解析其中的资源 → 下载资源 → 如果资源本身是 HTML/CSS 且允许继续深入再解析下一层。这个“深度”就是后面要说的 depth 参数它是你可控的核心。2.2 最小可用代码三行命令跑通单页镜像先不说复杂的配置我给你一条能立刻看到效果的路径。假设目标地址是 http://example.com/docs/index.html本地输出目录是 ./downloadsfrom pywebcopy import save_this_page save_this_page( urlhttp://example.com/docs/index.html, project_folder./downloads, project_namedemo_site, open_in_browserFalse, )运行后去 ./downloads/demo_site 目录看会出现 example.com 下按路径拆分的目录最外层是 index.html同级有 css/、js/、images/ 这些子目录HTML 里的引用已经全部改写为相对路径。这段代码的逻辑就是“单页快照”save_this_page 只处理入口页面本身能解析到的资源不会沿着链接继续往下抓同站其他页面。适合镜像一个产品说明书页、一篇技术博客文章或者任何“你只需要这一页及其静态资源”的场景。参数说明url 是入口页面地址协议头不能省略https 优先project_folder 是输出根目录不存在会自动创建project_name 是本次镜像的任务名最终目录是 project_folder/project_nameopen_in_browserFalse 表示结束后不自动调用默认浏览器打开页面在服务器或 CI 环境里务必设置为 False2.3 多页面站点镜像从单页到全站的切换开关当你要镜像的是整个文档站比如一个带几十个页面的技术 Wikisave_this_page 就不够了。pywebcopy 提供了另一个函数级入口from pywebcopy import crawl_site, config config.setup_config( project_folder./downloads, project_namewiki_snapshot, default_headers{ User-Agent: Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 }, ) crawl_site( urlhttp://example.com/wiki/, project_folder./downloads, project_namewiki_snapshot, depth1, overwriteFalse, )这里的关键在 depth 参数。depth1 表示只抓取入口页面里出现的同站链接所指向的页面以及它们的资源。depth2 会继续追两层依此类推。很多文档站的侧边栏会挂几十个分类页面depth1 基本就能覆盖一层目录结构。上面代码里 config.setup_config 是全局配置入口crawl_site 是真正的多页入口。这两个对象是完成整站镜像最常用的 API用法上有几个容易踩的位置比如 default_headers 里如果没写 User-Agent部分站点会返回 403 或者给你一堆压缩乱码——我下面第四节会具体说。3. 关键参数调优把镜像行为从“默认能用”调到“符合你的场景”3.1 depth、overwrite、bypass 三件套的取舍逻辑depth 直接影响请求量和耗时。对 documentation、博客这类内容站anchor 文本和多数正文链接都在同一域名下depth2 足够覆盖。对门户型站点首页会挂满各种栏目和文章推荐depth 稍微一加抓取量就是指数级膨胀——你可能只需要“首页栏目页”结果把全站几万篇文章的列表页都拉下来了。overwrite 参数控制同名文件是否覆盖。我一般建议首次镜像时置为 False因为一旦某个资源下载中断留下半个文件重跑时不会把它顶掉方便排查。等确认整个站点结构稳定后再打开 overwriteTrue 做增量刷新。这里的“增量”不是对比内容而是以 URL 路径是否存在本地文件为依据存在的跳过不存在的抓取。bypass 这类参数是代理隧道相关的开关在正常网络环境里保持默认即可。重点是别把深度和范围搞混——depth 是纵向层数而同一层链接的数量由页面内容决定你没法直接限制抓多少个链接只能通过 depth 和后文的文件类型过滤器控制总量。3.2 用 include / exclude 模式过滤不必要资源文件类型过滤是这个库最实用的一组配置。做镜像时你通常不想要这些字体文件的 woff2、iv 视频流、分析统计脚本、地图 SDK 的 JS。它们在离线环境下既打不开又白白增加镜像体积和耗时。常见做法是在 setup_config 里通过自定义 URL 模式数组来控制from pywebcopy import config config.setup_config( project_folder./downloads, project_nameclean_snapshot, exclude_patterns[ *.woff2, *.mp4, *.webm, analytics.js, *tracking*, ], include_patterns[ *.html, *.css, *.jpg, *.png, *.svg, *.js, ], )这段配置的效果是HTML、CSS、常规图片和 JS 保留字体、视频、埋点脚本被排除。如果 include 与 exclude 同时配置我建议只配 exclude——把明确不要的排除掉剩下的都镜像。反过来配 include 容易漏资源因为很多 CDN 上的图片路径后缀不带 .jpg 却有实际图片内容。参数说明include_patterns 是白名单模式exclude_patterns 是黑名单模式两者都支持 * 通配符匹配链接字符串。记住它们的判定发生在下载之前会直接节省带宽和磁盘空间。3.3 设置代理、请求头与超时三个影响成功率的隐藏旋钮镜像过程中遇到最多的两类失败一是服务端限流返回 403/429二是 HTTPS 证书校验失败。这两类问题都可以在 config 里提前设掉from pywebcopy import config config.setup_config( project_folder./downloads, project_nameprivate_docs, default_headers{ User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64), Accept-Language: zh-CN,zh;q0.9,en;q0.8, }, proxy{http: http://127.0.0.1:7890, https: http://127.0.0.1:7890}, timeout30, ssl_verifyFalse, )default_headers 里的 User-Agent 必须有很多站点对无 UA 或空 UA 的请求直接拒绝Accept-Language 设成中文优先能保证拿到中文本地化页面。proxy 字典是给镜像机用的如果你在内部网络或有独立代理出口按这个格式填上即可没有代理就别写这一段。timeout 是单次请求的等待上限单位秒建议 15-30 之间太小了在弱网环境频繁超时太大了遇到卡死资源会拖慢整体进度。ssl_verifyFalse 是断网排查时临时打开用的注意这里关闭了证书校验只在内部测试环境使用镜像公网站点时不要开否则等于把请求裸奔在链路上。3.4 页面加载后的渲染等待处理 JS 动态内容pywebcopy 的核心是抓取服务端返回的 HTML不执行页面里的 JavaScript。很多现代前端框架Vue、React 渲染的站点页面内容是 JS 动态填充的直接抓只能拿到外壳正文和列表全为空。这是这个库与无头浏览器方案最本质的差距。如果你确认目标页面需要 JS 渲染两条路一是放弃这个库改用 Playwright 或 Selenium 拿到渲染后的静态 HTML 再交给 pywebcopy 做资源归档这是常见配合方案二是先看站点有没有提供静态版本或 ?static1 这类参数很多文档站有。别指望在 pywebcopy 里开一个“等 3 秒再抓”的开关它没有。拿到空页面之后先 Fa12 打开开发者工具的 Network 面板看 HTML 响应里有没有正文节点再看接口有没有自动返回服务端渲染版本这两个排查点能省你半天时间。4. 完整镜像一个静态文档站的分步实录从入口 URL 到目录校验4.1 第一步站点结构观察与入口选择动手前先做一次侦察。打开目标站点看导航栏、面包屑、分页链接都指向什么路径。观察 index.html 或根路径返回的页面里侧边栏是服务端渲染还是 JS 动态拼的。这一步决定 depth 怎么设。例如一个 docs 站点结构是docs/index.html首页含侧边栏链接docs/guide/quickstart.htmldocs/guide/install.htmldocs/api/reference.html如果侧边栏在 HTML 源码里能直接看到这些链接depth1 就够了。如果侧边栏是通过 JS 拉 JSON 动态生成即使设 depth3 也抓不到这些页面因为链接根本不在 HTML 里。这是镜像前五分钟必须确认的事比调参数重要。4.2 第二步执行镜像并记录日志入口确定后用一个脚本把配置、抓取、日志落盘放一起import logging from pywebcopy import config, crawl_site logging.basicConfig( levellogging.INFO, format%(asctime)s %(name)s %(levelname)s %(message)s, filenamemirror.log, ) config.setup_config( project_folder./downloads, project_nameguide_snapshot, default_headers{ User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7), }, timeout20, ) crawl_site( urlhttp://example.com/docs/index.html, project_folder./downloads, project_nameguide_snapshot, depth1, overwriteFalse, )运行命令python mirror_job.py跑完后检查 mirror.log 的末尾正常情况最后一行会有“已抓取页面数量”或“完成”之类的标志。日志是唯一的后悔药如果镜像结果不对先打开 mirror.log 看是哪些 URL 请求失败再对照目录结构找原因。4.3 第三步本地目录结构与链接可点性验证镜像完成后不要直接打包走人花两分钟做三项验证打开 index.html检查样式是否加载页面是否是白板点开一两个内页检查浏览器地址栏显示的路径是否变成了 file:/// 开头的本地路径在开发者工具 Network 面板里看有没有远程 URL 的请求记录如果页面样式错乱最可能的原因是 WebFont 被 exclude 掉了——字体文件缺失时浏览器不会报错但页面字体回退成系统默认观感上可能与原站有明显差异。如果页面里图片裂了去对应目录看文件是否存在以及 HTML 里的相对路径层级对不对。4.4 第四步把已完成的任务做成可复用脚本同一个站需要定期重抓时把上面的逻辑抽成一个带命令行参数的脚本import argparse from pywebcopy import config, crawl_site parser argparse.ArgumentParser(descriptionsite mirror job) parser.add_argument(--url, requiredTrue, helpentry page url) parser.add_argument(--name, requiredTrue, helpproject name) parser.add_argument(--depth, typeint, default1, helpcrawl depth) parser.add_argument(--overwrite, actionstore_true, helpoverwrite local files) args parser.parse_args() config.setup_config(project_folder./downloads, project_nameargs.name) crawl_site( urlargs.url, project_folder./downloads, project_nameargs.name, depthargs.depth, overwriteargs.overwrite, )这样重抓时只需要改 URL 和项目名不用再开编辑器改模块参数。注意 depth 是 int 类型而不是字符串透传给 crawl_site 时务必保持一致这在自动化脚本里最容易出问题。5. 避坑指南五个镜像现场的真实翻车记录与排查路径5.1 现象镜像后的 HTML 打开是白板DevTools 里满屏红色 404原因资源 URL 写了绝对路径且没被重写HTML 里的 /css/main.css 在本地被解析成 file:///css/main.css自然找不到。解决重新执行镜像并检查日志里有没有 “rewrite” 相关字段——库会自动把绝对路径改成相对路径。确认你写入 url 时带了完整的协议头和路径不要只写 example.com这会干扰它对路径的判断。5.2 现象几 MB 的 HTML 抓下来本地文件却只有几 KB页面标题正常但主体内容为空原因目标页面是 Vue/React 客户端渲染服务端返回的 HTML 里没有正文 DOM。解决先放弃 pywebcopy用 Playwright 打开页面等待网络空闲后 driver.page_source 拿渲染后 HTML保存为本地入口文件后再用资源下载逻辑取 CSS/JS/图片。单独用 pywebcopy 在这方面是死路别浪费时间调参数。5.3 现象镜像到一半报 timeout重跑之后发现文件越积越多但页面还是缺东西原因首次中断的临时文件没有清理overwriteFalse 导致后续重跑不覆盖这些半截文件。解决把本地项目目录整个删掉重新跑一次完整镜像。半截文件没有校验值无法判断是否完整留着的唯一作用就是误导你。此后跑长任务习惯性加 timeout30 和日志落盘中断后看日志能定位到具体 URL判断是哪个资源卡住。5.4 现象站内搜索结果页、登录页、后台管理页也被抓下来了原因depth 设置过大爬虫顺着“退出登录”“我的账户”这类链接进入了不该进的后台区域。解决在 exclude_patterns 里排除含有 /login、/admin、/logout、/user 的路径。还有一种情况是分页 ?page2 会无限往下走同样可以用 exclude 模式屏蔽。镜像对象是公开文档不是全站爬虫范围收缩得越明确越好。5.5 现象页面里字体、图标全部错位看起来像古董网页原因字体和 iconfont 大多挂在 CDN 跨域资源上exclude 时把.woff2、.ttf 也干掉了或者 CDN 域名不在同站资源抓取范围内。解决将字体内联方案base64 嵌入 CSS除外字体文件本身改成 include 模式保留。排查时先把 exclude_patterns 暂时清空抓一个小页面试试能复现原始样式后再把黑名单加回来逐步逼近问题根因。6. 把镜像做扎实右键菜单集成和首屏验证脚本镜像工程的收尾技巧有两件事一是把重复动作固化成工具二是用简单脚本校验镜像完整性。先说我自己的习惯把镜像脚本注册成系统级右键菜单命令。在 Linux 桌面环境里创建一个 .desktop 文件指向上面写的入口脚本选中 URL 就能发起镜像任务Windows 下用注册表把 python mirror_job.py --url %V 挂到右键菜单。这样一个动作完成一个站点的本地化归档不再打开 IDE。关键一步是首屏验证。镜像后写一个极简自检脚本检查的是本地入口文件里引用的本地资源路径是否存在import os import re from pathlib import Path index_path Path(./downloads/guide_snapshot/index.html) html_content index_path.read_text(encodingutf-8) local_refs re.findall(r(?:src|href)(\.\.?/[^]), html_content) missing [ref for ref in local_refs if not (index_path.parent / ref).exists()] print(本地资源引用数:, len(local_refs)) print(缺失数量:, len(missing)) for ref in missing[:10]: print(MISSING:, ref)这段代码不做远程请求纯本地文件校验跑起来也就几百毫秒。列表里的缺失项一眼能看出是图片、CSS 还是脚本文件大幅减少肉眼核对目录结构的时间。注意正则只在简单的双引号引用场景下有效如果站点模板里用了单引号或动态拼接路径正则需要对应调整——好在绝大多数文档站都符合这个规律。从那以后我每次完成镜像任务都强制走一遍深度设置 → 日志观察 → 路径排除 → 本地校验。这套流程跑顺之后镜像这个动作就从“神秘的黑匣子”变成了可预期、可复现的工程步骤。希望帮到你。本文还有配套的精品资源点击获取