简介PyWebCopy 是一款面向 Python 开发者、网页归档与数据采集学习者的网页镜像库用于将在线网页或整站及其 CSS、JS、图片等静态资产保存到本地适合离线阅读、资料留存和爬虫入门实践。资源包共 32 个文件以 19 个 py 源码模块和 8 个 md 文档为主另含少量 yml 配置、依赖说明与许可证文件压缩包约 65KB体量轻便。源码围绕爬虫抓取、页面解析、链接重映射和 API 封装等环节组织文档覆盖安装配置、基础调用、进阶自定义与测试示例便于理解单页保存与整站克隆的实现路径。已有 572 人学习下载读者可据此掌握直接 API 的用法参考模块划分进行二次开发或借助测试与配置说明排查抓取及资产保存中的问题。1. 先弄懂 pywebcopy它到底是网页复印机还是爬虫第一次听到 pywebcopy你可能以为它是个浏览器插件或者要先把爬虫学一遍。其实它更像“网页复印机”把一个页面连同图片、样式、脚本按原结构存到本地文件夹里双击还能看。它解决的是“这个页面我想留档、想离线看、想对照结构”的问题适合刚学 Python、不想一上来啃框架的新手。你不需要先懂分布式抓取也不用会写正则先会保存一个页面再慢慢扩大范围就够了。2. 为什么新手先学网页镜像从三个场景到环境准备2.1 网页镜像不是爬虫先分清“存页面”和“抽数据”很多新手把网页镜像和爬虫混在一起。爬虫的重点是“抽数据”比如把商品价格、标题、评论数抓成表格网页镜像的重点是“存页面”把一个 HTML 页面和它依赖的图片、样式、脚本按原来的目录关系保存下来。前者像把一本书里的关键句子抄进笔记本后者像把整页扫描成 PDF再附上页面用到的素材。pywebcopy 属于后一种思路。它面向的是 Python 里的网页归档场景你给一个地址它把页面内容拉到本地尽量保留页面结构和资源引用。对零基础的人来说这个方向比“上来就写一个爬虫框架”更友好因为你能马上看到结果一个文件夹里面有 HTML有图片有样式打开就能对照。第一个场景是资料留存。你看到一篇讲 HTML 布局的页面过几天可能改版链接也可能失效。把页面镜像到本地至少能保留当时的页面结构后面复习时不会只剩一张截图。第二个场景是学习页面结构。新手看 HTML 和 CSS 时光看源码容易抽象把页面和资源一起存下来再用编辑器打开能直观看到图片路径、样式文件、页面之间的链接关系。第三个场景是离线演示。你要给别人展示一个静态页面的效果但现场网络不稳定提前镜像一份本地副本比临时开热点稳得多。这里要提醒一句网页镜像不是“想抓什么就抓什么”。你只应该保存自己有权留存的页面并且遵守目标站点的访问规则。新手最容易犯的错是把“能访问”当成“可以随便批量保存”。这个边界先立住后面学技术才不会跑偏。2.2 装环境别急着写代码Python、pip、虚拟环境三件事pywebcopy 是 Python 库所以第一步不是写镜像脚本而是确认你的电脑上有一个能用的 Python。打开终端输入下面两行分别看 Python 和 pip 有没有正常返回# 查看 Python 版本确认命令能正常执行 python --version # 查看 pip 版本pip 是 Python 的包安装工具 python -m pip --version如果第一行报“命令不存在”先装 Python再回来继续。第二行用python -m pip而不是直接写pip是为了让 pip 跟着当前这个 Python 走。新手常见的翻车现场是电脑里装了两个 Pythonpip install装到了另一个环境运行脚本时却提示找不到模块。用python -m pip能减少这类问题。接下来建议建一个虚拟环境。虚拟环境可以理解成“给这个项目单独准备一个工具箱”里面装的库不会和系统里其他项目打架。命令不复杂# 在当前目录创建名为 .venv 的虚拟环境 python -m venv .venv创建完之后要激活。Windows 和 macOS、Linux 的激活命令不一样# macOS 或 Linux 下激活虚拟环境 source .venv/bin/activate# Windows 命令提示符下激活虚拟环境 .venv\Scripts\activate激活成功后终端前面通常会出现(.venv)之类的提示。这个时候再安装 pywebcopy# 在激活的虚拟环境里安装 pywebcopy python -m pip install pywebcopy这条命令的含义很直接用当前虚拟环境里的 pip把 pywebcopy 以及它依赖的库装进来。安装完成后不要急着写复杂脚本先做导入检查。安装环节最怕“看起来装完了其实装错地方”导入检查就是最小的验证。提示第一次练习不要拿真实业务站做目标先用本地测试页。你不需要一上来就处理登录、验证码、限速这些复杂情况。2.3 导入检查跑通确认装对了 Python在终端里执行一条短命令只检查能不能导入核心函数不发起任何抓取# 只做导入检查确认 pywebcopy 装在了当前 Python 环境里 python -c from pywebcopy import save_webpage, save_website; print(import ok)如果输出import ok说明环境基本通了。如果提示ModuleNotFoundError: No module named pywebcopy先别怀疑代码按顺序排查三件事当前终端有没有激活虚拟环境安装时用的是不是python -m pip运行脚本的python和安装时的python是不是同一个。把这三件事对齐通常就能解决。还有一个新手常问的问题要不要先学 HTML 和 CSS答案是“边用边学”。你不需要先把 HTML 学完才能镜像页面但至少要知道一个页面通常会引用样式文件、图片和脚本。这样你打开镜像结果时才知道该看什么。入门阶段的目标不是背标签而是能判断“这个页面保存完整了没有”。3. 第一个例子怎么跑把单个页面保存成能双击打开的文件夹3.1 先造一个不会翻车的本地测试页第一次就跑真实网站变量太多网络可能断页面可能改版站点可能限速。更稳的做法是自己造一个本地测试页。下面这段 Python 会在当前目录下创建demo文件夹里面放一个 HTML 页面、一个 CSS 文件、一张 SVG 图片还有一个简单的第二页方便后面练习多个 URL。from pathlib import Path # 建一个本地测试目录避免第一次就拿真实网站练手 base Path(demo) base.mkdir(exist_okTrue) # 主页引用 style.css 和 pic.svg方便观察资源有没有被保存 (base / index.html).write_text( !doctype html html langzh-CN head meta charsetutf-8 title镜像测试页/title link relstylesheet hrefstyle.css /head body h1Hello, 网页镜像/h1 p这是一段用于测试的本地页面。/p img srcpic.svg alt测试图 pa hrefabout.html打开第二页/a/p /body /html, encodingutf-8, ) # 第二页后面用 URL 列表练习时可以用到 (base / about.html).write_text( !doctype html html langzh-CN head meta charsetutf-8 title第二页/title /head body h1About/h1 p这是用于测试链接保存的第二个页面。/p /body /html, encodingutf-8, ) # 样式文件如果镜像后样式丢了打开页面会很明显 (base / style.css).write_text( body { font-family: sans-serif; margin: 40px; } h1 { color: #2b6cb0; }, encodingutf-8, ) # 一张简单的 SVG 图片用来检查图片资源有没有一起保存 (base / pic.svg).write_text( svg xmlnshttp://www.w3.org/2000/svg width160 height80 rect width160 height80 fill#e2e8f0/ text x20 y45 font-size18 fill#2d3748test image/text /svg, encodingutf-8, ) print(测试页已生成demo/index.html)这段代码用了pathlib它是 Python 自带的路径工具。mkdir(exist_okTrue)的意思是“目录不存在就创建已经存在也不报错”。write_text(..., encodingutf-8)把文本写进文件并明确用 UTF-8 编码避免中文页面在第一步就出现乱码。生成的页面里故意放了 CSS 和图片就是为了让你在镜像后能检查资源有没有跟着走。接下来在demo目录启动一个本地静态服务器# 在 demo 目录启动本地静态服务器端口 8000 python -m http.server 8000 --directory demo这条命令会让 Python 自带一个简单的 HTTP 服务把demo目录作为网站根目录。执行后不要关这个终端另开一个终端跑后面的镜像脚本。浏览器里访问http://127.0.0.1:8000/index.html应该能看到标题、文字和图片。这个地址就是你第一个镜像例子的目标。3.2 写第一个镜像脚本只保存一个页面现在写最小脚本。新建一个first_mirror.py内容如下from pywebcopy import save_webpage # 保存单个页面先不要用整站入口范围越小越容易看懂 save_webpage( # 本地测试页地址和上一步启动的服务器对应 urlhttp://127.0.0.1:8000/index.html, # 所有镜像任务的父目录 project_foldermirror_demo, # 这次任务的子目录名起一个能看懂且不重复的名字 project_namefirst_page_001, )这段脚本只做一件事把index.html这个页面保存到mirror_demo下面。url是起点地址project_folder是父目录你可以理解成“所有归档任务都放在这个抽屉里”project_name是这次任务的子目录名相当于给这次归档贴一个标签。第一次跑建议把project_name写得具体一点比如first_page_001不要用test这种过两天就不知道是什么的名字。运行脚本# 在另一个终端运行镜像脚本 python first_mirror.py如果终端没有报错去文件管理器里找mirror_demo目录。不同环境下目录层级可能略有差异你认准包含index.html和资源文件的文件夹就行。打开里面的 HTML 文件检查标题、文字、图片和样式是不是都在。这个检查很重要镜像不是“终端不报错就完了”最终要看本地页面能不能正常打开。注意如果你反复运行同一个project_name有的环境会复用目录有的环境会提示冲突。入门阶段最稳的办法不是研究覆盖开关而是每次换一个唯一的任务名比如first_page_002。3.3 打开结果后检查三件事打开镜像结果后不要只看一眼标题就结束。建议检查三件事HTML 文件在不在图片和 CSS 有没有跟着下来页面里的链接是指向本地文件还是仍然指向原来的地址。下面这段小脚本可以帮你列出镜像目录里的文件from pathlib import Path # 递归列出 mirror_demo 下的文件先看输出结构 for path in sorted(Path(mirror_demo).rglob(*)): if path.is_file(): print(path)rglob(*)的意思是递归查找所有子目录里的内容is_file()用来过滤掉目录只打印文件。你不需要背这个写法但要知道它的用途确认镜像结果里到底有什么。如果只看到一个 HTML 文件没有图片和样式先不要急着改代码回到源页面看资源是怎么引用的再看输出目录里有没有对应文件。第二件事是双击打开 HTML。能打开、有样式、图片能显示说明基本资源关系没断。第三件事是点一下页面里的链接。如果链接仍然跳到原来的网址说明这个页面只是单页保存链接关系没有被改成本地路径。单页镜像出现这种情况不奇怪后面用整站入口或自己维护 URL 列表时再处理范围问题。4. 常用参数别乱改目录、覆盖、深度和资源范围的入门用法4.1 project_folder 和 project_name目录先管住入门阶段最值得先管住的不是“抓得多深”而是“文件放在哪里”。project_folder是父目录project_name是任务子目录这两个参数决定了你以后能不能快速找到某一次归档。建议固定一个父目录比如mirror_demo然后每次任务用不同的子目录名。下面这种命名方式就比test1、test2好排查from pywebcopy import save_webpage # 用日期和序号做任务名避免不同批次的文件混在一起 save_webpage( urlhttp://127.0.0.1:8000/index.html, project_foldermirror_demo, project_name20250101_page_001, )project_name不是随便起个名字就行它相当于这次归档的“文件夹标签”。你以后打开mirror_demo看到一堆任务目录能靠名字判断哪次是单页测试哪次是整站练习。新手常见的坏习惯是所有任务都叫test跑几次之后自己也分不清哪个目录是最新的。覆盖策略也要提前想清楚。有的版本或调用方式会提供覆盖相关开关但新手不要背参数名也不要把“覆盖”当成默认选项。更稳的做法是正式归档前换一个新的project_name让旧结果保留下来只有确认旧目录可以丢弃时再考虑覆盖。你可以在当前环境里查看函数帮助from pywebcopy import save_webpage # 查看当前安装环境接受的参数别照抄网上过时代码 help(save_webpage)help()会打印当前这个函数的说明。不同安装环境支持的参数可能不完全一样所以入门阶段不要追求“背全参数”先掌握url、project_folder、project_name这三个最核心的入口其他设置遇到问题再查。4.2 单页入口和整站入口先小后大pywebcopy 常见的使用方式有两种保存单个页面和从某个入口开始保存网站范围。单页入口适合先验证环境、检查资源、看输出结构整站入口适合在你已经跑通单页之后再小范围尝试。下面是一个整站入口的最小写法from pywebcopy import save_website # 从入口页开始保存网站范围第一次只拿本地测试站练手 save_website( urlhttp://127.0.0.1:8000/index.html, project_foldermirror_demo, project_namefirst_site_001, )save_website和save_webpage的参数字面很像但范围不一样。单页入口更像“复印这一张”整站入口更像“从这一张开始顺着链接继续看”。新手第一次用整站入口最容易出现两个问题链接越走越多目录越来越大或者目标站有访问限制跑一半停住。所以第一次整站练习建议用本地测试站页面少、链接可控你能把注意力放在“输出结构发生了什么变化”上。如果你只是想保存几个指定页面不希望它顺着链接乱走更稳的做法是自己准备 URL 列表然后循环调用单页入口。这样范围由你控制出了错也容易定位是哪一个地址的问题。4.3 想过滤链接用 URL 列表代替“乱抓”新手很容易一上来就找“过滤参数”希望库能自动只抓某几个目录。实际入门阶段更推荐先用 URL 列表把范围写死。下面这段代码会依次保存两个本地页面from pywebcopy import save_webpage # 自己维护 URL 列表范围清楚出错也好定位 urls [ http://127.0.0.1:8000/index.html, http://127.0.0.1:8000/about.html, ] for index, url in enumerate(urls, start1): save_webpage( urlurl, project_foldermirror_demo, # 每个页面一个独立任务名避免互相覆盖 project_namefpage_{index:02d}, )enumerate(urls, start1)的作用是同时拿到序号和地址index从 1 开始。fpage_{index:02d}会把序号格式化成两位数比如page_01、page_02。这样每个页面都有自己的输出目录后面检查时不会混在一起。这个写法看起来没有“高级过滤”但对新手最实用你知道自己抓了哪几个地址也知道结果在哪个目录。等你把单页、列表、整站小范围都跑过一遍再去看更细的范围控制会容易得多。设置项作用新手建议url抓取的起点地址先用本地测试页project_folder所有任务的父目录固定为mirror_demoproject_name单次任务的子目录名每次唯一带日期或序号单页入口保存一个页面第一个例子先用它整站入口从入口页扩展范围单页跑通后再试覆盖相关开关决定是否复用旧目录不确定就换新任务名5. 新手避坑与排查网页镜像最容易翻车的五个地方网页镜像看起来只是“给个地址、存下来”实际踩坑点不少。下面五个是零基础阶段最容易遇到的我按“现象、原因、解决”拆开讲你遇到问题时可以直接对照。5.1 现象打开是空白页样式全丢现象很直观本地 HTML 能双击打开但页面没有颜色、图片不显示或者干脆一片空白。原因通常不是 pywebcopy 没工作而是资源路径断了。网页里的图片和 CSS 可能用相对路径、绝对路径甚至用脚本动态加载镜像之后目录层级一变原来的引用就找不到了。解决思路是先看输出目录里有没有对应的资源文件。如果资源文件在但页面引用路径不对检查你是不是只移动了 HTML 文件。镜像结果是一个整体HTML、CSS、图片之间的相对位置不能随便拆。如果资源文件根本不在回到源页面看它是怎么引用的再判断是单页保存范围不够还是页面依赖了外部地址。入门阶段尽量用本地测试页练习路径简单排查成本低。5.2 现象只拿到 HTML图片和 CSS 不见这种情况常见于“以为保存页面就是保存一个 HTML 文件”。网页不是单个文件它通常还会引用样式、图片、字体、脚本。单页入口能不能把资源一起带下来取决于页面结构和库的处理方式。你看到目录里只有 HTML不代表命令完全失败可能只是资源没有被纳入这次保存范围。解决时先检查源页面打开开发者工具或直接看 HTML 源码确认图片和样式是用什么地址引用的。然后看镜像目录里有没有类似assets、css、images的文件夹。如果没有换一个资源引用简单的本地页面重新测试先把“HTML CSS 图片”这条链路跑通。不要一上来就处理大量动态加载的页面那会让问题变得很玄学。5.3 现象请求被拒绝或越抓越慢终端里出现 403、429 之类的状态码或者一开始很快、后面越来越慢通常和访问频率、站点规则有关。403 往往表示服务器拒绝访问429 表示请求太频繁。新手容易误以为“换个参数就能解决”但真正要做的是降低请求频率、减少范围并确认目标页面是否允许这样保存。解决方式很朴素先用本地测试页排除代码问题再确认目标站点是否允许保存整站入口先缩小到几个页面不要为了“抓全”把各种限制开关全打开。你可以把整站任务拆成多个 URL 列表任务一次只处理一小批。这样做看起来慢但排查成本低也不会给目标站点造成不必要的压力。注意只保存自己有权留存的页面并遵守目标站点的访问规则。技术手段不是绕过限制的理由。5.4 现象链接越抓越多磁盘很快满整站入口最容易让人上头从首页开始顺着链接一路走目录越来越大最后自己都不知道抓了什么。原因是你给了一个入口但没有控制范围。网页里的导航、标签、分页、相关推荐都会产生新链接范围一大结果就不可控。解决方法是“先列表、后整站”。先用 URL 列表保存三到五个页面确认输出结构稳定再用整站入口跑本地测试站观察目录变化最后才考虑真实站点的小范围任务。每次任务前写清楚边界只保存哪个栏目、最多几个页面、输出到哪个目录。不要用“抓完再说”的方式做归档后面清理目录会比抓取更花时间。5.5 现象重复运行后文件互相覆盖同一个project_name跑多次可能出现旧文件被覆盖、目录里混着两次结果、或者自己分不清哪次是最新。原因是任务名复用了而覆盖策略又没有提前确认。新手常常觉得“反正内容一样覆盖没关系”但一旦某次抓取失败旧结果也可能被破坏。解决办法是给每次任务一个唯一名字比如带日期、序号或用途。正式归档前不要随手打开覆盖开关如果当前环境支持覆盖参数也先用help()看清楚含义。我的血泪经验是目录名越具体后面越省事。page_001比test好20250101_article_001又比page_001更好。你不需要一开始就设计复杂目录但至少要让下一次的自己能看懂。6. 下一步学什么从单页镜像走到可复用的归档习惯入门之后不要马上追求“整站全量”。先做三个递进练习第一保存一个本地页面打开检查样式和图片第二用 URL 列表保存三到五个页面每个任务独立命名第三对本地测试站跑一次整站入口观察目录结构变化。每做完一次只记录三行抓了哪个地址、输出到哪个目录、打开后缺了什么。这个习惯比多背几个参数有用。下一步学习点学到什么程度判断标准HTML 和 CSS 基础知道页面会引用样式、图片和脚本能指出一个页面的资源从哪来HTTP 基础知道 403、404、429 大概意味着什么看到报错先查访问规则和地址目录管理每次任务都能追溯不看代码也能找到输出结果小范围归档能自己控制 URL 列表不会一上来就整站乱抓再往后可以学一点页面结构分析看 HTML 里的link、img、script是怎么写路径的看相对路径和绝对路径有什么区别。这个知识点不难但能解释很多“为什么图片没存下来”的问题。然后学一点 HTTP 状态码和编码常识遇到乱码、拒绝访问、页面空白时至少知道先看哪里。我第一次做整站镜像时觉得参数越多越稳结果目录里混进了旧文件排查了半天。从那以后我每次先建新目录、先跑单页、再扩大范围最后才看整站结果。希望帮到你。本文还有配套的精品资源点击获取
