pywebcopy网页镜像入门：单页保存、目录管理与避坑

简介：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 走。新手常见的翻车现场是：电脑里装了两个 Python，pip 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_ok=True) # 主页：引用 style.css 和 pic.svg，方便观察资源有没有被保存 (base / "index.html").write_text( """<!doctype html> <html lang="zh-CN"> <head> <meta charset="utf-8"> <title>镜像测试页</title> <link rel="stylesheet" href="style.css"> </head> <body> <h1>Hello, 网页镜像</h1> <p>这是一段用于测试的本地页面。</p> <img src="pic.svg" alt="测试图"> <p><a href="about.html">打开第二页</a></p> </body> </html>""", encoding="utf-8", ) # 第二页：后面用 URL 列表练习时可以用到 (base / "about.html").write_text( """<!doctype html> <html lang="zh-CN"> <head> <meta charset="utf-8"> <title>第二页</title> </head> <body> <h1>About</h1> <p>这是用于测试链接保存的第二个页面。</p> </body> </html>""", encoding="utf-8", ) # 样式文件：如果镜像后样式丢了，打开页面会很明显 (base / "style.css").write_text( "body { font-family: sans-serif; margin: 40px; } h1 { color: #2b6cb0; }", encoding="utf-8", ) # 一张简单的 SVG 图片：用来检查图片资源有没有一起保存 (base / "pic.svg").write_text( """<svg xmlns="http://www.w3.org/2000/svg" width="160" height="80"> <rect width="160" height="80" fill="#e2e8f0"/> <text x="20" y="45" font-size="18" fill="#2d3748">test image</text> </svg>""", encoding="utf-8", ) print("测试页已生成：demo/index.html")

这段代码用了pathlib，它是 Python 自带的路径工具。mkdir(exist_ok=True)的意思是“目录不存在就创建，已经存在也不报错”。write_text(..., encoding="utf-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( # 本地测试页地址，和上一步启动的服务器对应 url="http://127.0.0.1:8000/index.html", # 所有镜像任务的父目录 project_folder="mirror_demo", # 这次任务的子目录名，起一个能看懂且不重复的名字 project_name="first_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( url="http://127.0.0.1:8000/index.html", project_folder="mirror_demo", project_name="20250101_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( url="http://127.0.0.1:8000/index.html", project_folder="mirror_demo", project_name="first_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, start=1): save_webpage( url=url, project_folder="mirror_demo", # 每个页面一个独立任务名，避免互相覆盖 project_name=f"page_{index:02d}", )

enumerate(urls, start=1)的作用是同时拿到序号和地址，index从 1 开始。f"page_{index:02d}"会把序号格式化成两位数，比如page_01、page_02。这样每个页面都有自己的输出目录，后面检查时不会混在一起。

这个写法看起来没有“高级过滤”，但对新手最实用：你知道自己抓了哪几个地址，也知道结果在哪个目录。等你把单页、列表、整站小范围都跑过一遍，再去看更细的范围控制，会容易得多。

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 里的link、img、script是怎么写路径的，看相对路径和绝对路径有什么区别。这个知识点不难，但能解释很多“为什么图片没存下来”的问题。然后学一点 HTTP 状态码和编码常识，遇到乱码、拒绝访问、页面空白时，至少知道先看哪里。

我第一次做整站镜像时，觉得参数越多越稳，结果目录里混进了旧文件，排查了半天。从那以后我每次先建新目录、先跑单页、再扩大范围，最后才看整站结果。希望帮到你。

本文还有配套的精品资源，点击获取