简介PyWebCopy 是一套用 Python 编写的网页镜像与归档工具主要面向 Web 开发者和爬虫爱好者解决单页保存、整站克隆及静态资源CSS、JS、图片抓取的问题。它内置 robots.txt 规则识别、资源链接重映射、自定义配置与高级 API既可直接调用也支持子类扩展适合不同层级的 Python 使用者学习爬虫与站点归档实现思路。压缩包内含 32 个文件主体为 19 个 Python 源码文件覆盖核心爬取、解析、配置、异常处理等模块另有 8 个 Markdown 文档、2 个 YAML 配置及许可证、说明等辅助文件整体仅 65KB结构紧凑、便于通读。已有 569 人学习下载。通过源码与自带示例、测试用例读者可快速掌握网页保存、链接重写、资源筛选等关键实现并据此定制自己的镜像工具。1. pywebcopy 是什么为一件事——把网页完整搬回本地“把网页内容拿下来”和“把网页完整搬回本地”看起来是一回事实际差距非常大。很多人下载过 HTML 文件双击打开时发现照片全是裂的、样式一片空白。pywebcopy 就是围绕“完整搬回本地”这件事来设计的它不光保存你指定的页面还会顺着页面里的链接把配套的 CSS、JS、图片、字体一并抓下来并把资源路径改写成本地文件关系让你拿到手的是一份能双击打开、离线也能浏览的目录。适合做文档归档、产品手册备份、教程站离线包或者给演示环境做一份静态副本。这篇文章会从安装脚本开始走到排查实操给你一套直接能用的镜像工作流。2. pywebcopy 起步安装、最小脚本和第一份离线资料2.1 先装 pywebcopy再确认 Python 环境干净镜像类工具最怕依赖打架建议新开一个虚拟环境再安装别直接塞进全局 Python。这样即使 pywebcopy 依赖的库和别的项目冲突也不会影响你日常开发环境。python -m venv webcopy_env source webcopy_env/bin/activate pip install pywebcopy安装完成后跑一句简单验证确认模块路径能正常导入python -c import pywebcopy; print(pywebcopy.__file__)能打印出模块文件路径就说明基础安装没问题。如果这一步报错优先检查 Python 版本和 pip 是否指向当前虚拟环境而不是急着换源重装。pywebcopy 这类库在不同版本上的依赖差异不小先保证解释器环境是干净的后面跑镜像时才不会把时间浪费在环境排错上。2.2 用 save_this_page 保存一个具体页面先不急着整站爬取用 save_this_page 保存一个具体页面把流程走通。这个函数适合保存某个说明文档、单篇文章或活动页。它的工作范围是把当前页面的 HTML、CSS、JS、图片、字体一起拉到本地并重写页面的资源引用。# mirror_one_page.py from pywebcopy import save_this_page save_this_page( urlhttps://docs.example.com/install/, project_folder./archives, project_nameinstall-doc, overwriteTrue, )这里的 url 是镜像入口project_folder 指定镜像存放的根目录不存在时 pywebcopy 会自动创建project_name 是这次镜像的独立子目录名建议一个项目一个名字避免几份镜像混在同一目录里。overwrite 表示如果目标目录已经存在是否允许覆盖第一次跑可以先设 False确认逻辑没问题再设 True。保存完成后会在 archives/install-doc 下看到类似这样的结构archives/install-doc/ ├── index.html └── assets/ ├── css/ ├── js/ └── img/直接用浏览器打开 index.html如果能正常显示样式和图片说明单页镜像已经通了。如果白屏先不用慌后面第四章会集中排查。2.3 用 crawl_this_site 镜像整个站点单页保存只能处理入口页自身的内容站内其他链接不会跟着下来。要把整个站点搬回本地用 crawl_this_site 替代 save_this_page 即可。它会从入口页开始顺着页面里的超链接继续抓取递归镜像站内相关页面。# mirror_whole_site.py from pywebcopy import crawl_this_site crawl_this_site( urlhttps://docs.example.com/, project_folder./archives, project_namedocs-site, overwriteTrue, )这里 url 传的是站点首页crawl_this_site 会以这个地址为起点自动爬取页面里指向站内其他页面的链接并把每层页面的资源一并下载。相比 save_this_page它更适合文档站、教程站这类结构清晰的站点。我一般会先跑一个页面试通再跑整个站点。如果整站爬取时发现个别 JS 或图片抓不下来单独把对应文件放进 assets 目录补上之后重跑一次就好。另外pywebcopy 的命令行入口在不同版本里参数风格不太一致我习惯直接用 Python 代码调用这样语义更明确也方便把参数固化成脚本。3. pywebcopy 的镜像原理与参数调优让输出真正能打开3.1 镜像链路拆解请求、解析、改写、落盘pywebcopy 本质上做的是四件事请求 HTML、解析资源引用、递归下载、改写链接。第一步先请求入口页得到 HTML 文本第二步解析页面里的link、script、img以及与页面相关的 CSS 文件中带url()的资源第三步把这些资源逐一下载到本地对应目录第四步把 HTML 里的资源引用改写成新的本地相对路径。理解这条链路对排查问题很有用。如果镜像后页面白屏多半不是页面没有下载下来而是资源引用没有被正确改写或者改写后的路径对不上实际目录结构。pywebcopy 和普通爬虫的关键区别就在这一步普通爬虫只关心内容pywebcopy 关心的是资源之间的相对关系所以链接改写才是它的核心价值。3.2 常用配置参数与一个实际示例pywebcopy 的核心参数不多但每个都直接影响镜像结果。整理成表如下。参数作用常见取值建议url镜像入口地址https://docs.example.com/入口页建议带完整协议project_folder镜像存放根目录./archives不存在时自动创建project_name站点独立子目录名docs-site一个项目一个目录便于归档overwrite是否覆盖已存在目录False / True首次跑用 False重跑时再 Truedebug是否输出请求级调试日志False / True排查资源丢失时开启实际使用时我把调试日志单独拿出来跑一次方便看清哪些请求失败# mirror_with_debug.py from pywebcopy import crawl_this_site crawl_this_site( urlhttps://docs.example.com/user-manual, project_folderarchives, project_nameuser-manual-v2, debugTrue, )debugTrue 会在控制台输出大量请求日志能看到每个资源的请求状态。日志里大量出现 404 或超时说明目标页面的资源结构比预想复杂可能要检查跨域或链接改写规则。不同版本的 pywebcopy 在参数覆盖机制上略有差异如果你在代码里传参不生效优先看当前版本的实际源码或者调用help(crawl_this_site)确认。不要凭记忆传参这是镜像类工具最容易翻车的地方。3.3 整站镜像和单页快照怎么选不是所有场景都适合整站镜像。文档型站点、教程站、产品手册这类页面间链接关系清晰的目标用完整镜像很合适。活动落地页、临时公告页用 save_this_page 就够了没有必要把无关页面全部抓下来。对于互动型站点比如需要登录、需要实时请求接口的后台应用镜像下来意义不大因为这些功能脱离了服务端数据根本无法工作。所以我在开始镜像前会先问自己一个问题目标页面关掉网络之后内容是否依然完整是就整站镜像否就单页快照或放弃。这个判断能省掉很多无效爬取。4. pywebcopy 常见问题排查白屏、断链、被封与空壳4.1 白屏镜像后的页面为什么只剩骨架现象index.html 用浏览器打开后页面只能看到文字样式全丢。原因页面里的样式文件多半来自跨域 CDN。pywebcopy 默认只会爬取当前域名下的资源外部 CDN 地址会被当成站外资源保留原 URL离线打开时自然加载不到。解决先打开浏览器开发者工具看控制台里哪些 CSS 请求失败。如果确实是 CDN 地址就把 CDN 文件手动下载到本地 assets 目录再批量替换 HTML 里的引用。简单的位置替换脚本如下# replace_cdn_paths.py from pathlib import Path html Path(archives/user-manual/index.html) text html.read_text(encodingutf-8) text text.replace( https://cdn-static.example.com/css/theme.css, assets/css/theme.css, ) html.write_text(text, encodingutf-8)替换之前先确认本地 assets 目录下确实存在对应的 css 文件否则改完还是 404。4.2 断链CSS 抓下来了但字体和背景图仍然 404现象样式文件本地存在但页面里引用的一些字体、背景图片加载不出来。原因CSS 文件内部通过相对路径引用资源镜像后 CSS 文件所在的目录层级变化原本的../fonts/路径已经对不上新的目录位置。解决打开本地 CSS 文件检查url()里的引用基准。如果 CSS 在 assets/css 下而字体在 assets/fonts 下路径应该是../fonts/xxx.woff2。可以写个脚本统一修复 CSS 里的相对路径但改完一定抽查几个文件。# fix_css_relative_paths.py import re from pathlib import Path css_path Path(archives/user-manual/assets/css/theme.css) text css_path.read_text(encodingutf-8) text re.sub(rurl\([\]?([^)\]?)[\]?\), rurl(../\1), text) css_path.write_text(text, encodingutf-8)正则替换只适合路径层级固定的场景如果资源来源比较复杂建议手动确认几个关键文件不要一把梭全替换。4.3 403 或验证页目标站把请求挡在门外现象爬取速度很快结束下载下来的页面全是同一个验证页面。原因目标站识别到默认请求头不是浏览器直接返回验证页或 403 状态码。解决先用普通 HTTP 客户端测试一下直达页面的返回状态换一个常见浏览器 User-Agent 再请求。等确认能拿到 200 后再回到 pywebcopy 跑镜像。# probe_headers.py import requests headers {User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64)} resp requests.get(https://docs.example.com/install/, headersheaders, timeout10) print(resp.status_code, resp.url)如果换 UA 以后仍返回 403基本就是风控策略更严格。这种情况直接降低请求频率或者考虑这个站点是否适合镜像别硬来。4.4 镜像目录只有几 MB明显内容缺失现象爬取任务很快结束整个镜像目录体积小得反常。原因目标站大量内容是异步加载的图片懒加载数据通过接口填充pywebcopy 默认只抓取初始 HTML不会执行 JavaScript所以很多资源没有被触发。解决先判断内容缺失是否不可接受。如果只是图片没有触发下载直接检查页面里 img 的真实地址手动补齐如果是接口渲染的正文pywebcopy 本身就不合适需要用能执行 JavaScript 的无头浏览器先把最终 DOM 导出来再交给 pywebcopy 做资源搬运。4.5 空壳SPA 页面镜像后只剩一个空 div现象Vue、React 这类单页应用镜像后index.html 里只有一个div idapp没有任何正文。原因SPA 首屏 HTML 本来就没有正文内容全靠 JavaScript 在浏览器里渲染。pywebcopy 请求来的 HTML 是空壳。解决先用无头浏览器打开目标页面等待渲染完成后保存当前页面 HTML再把这个已渲染的 HTML 作为入口交给 pywebcopy。这条路径能解决大部分 SPA 镜像问题但要接受抓取成本明显上升不是所有站点都值得这样做。5. 进阶用法把镜像收尾做成一个可交付的检查流程镜像跑完不算完交付前还要验证。我现在的习惯是写一个固定脚本把爬取和检查串在一起跑完自动输出资源统计发现异常直接报错。# final_check.py from pathlib import Path from pywebcopy import crawl_this_site crawl_this_site( urlhttps://docs.example.com/user-manual, project_folderarchives, project_nameuser-manual, overwriteTrue, ) site_dir Path(archives/user-manual) index_path site_dir / index.html assert index_path.exists(), 镜像失败缺少入口页 index.html css_count len(list(site_dir.rglob(*.css))) js_count len(list(site_dir.rglob(*.js))) img_count len(list(site_dir.rglob(*.png)) list(site_dir.rglob(*.jpg))) print({css: css_count, js: js_count, img: img_count}) assert css_count 0, 没有抓到样式文件检查入口页资源引用这段脚本先跑完整镜像再检查入口页是否存在、CSS 和图片是否有实际下载。如果 CSS 数量为零说明入口页的资源引用结构可能超出了 pywebcopy 的默认处理范围需要人工介入。资源数量统计也可以作为基线下次重爬后对比一下数量是否合理避免页面改版导致镜像不完整。镜像工具不会解决所有网页保存需求遇到动态渲染很重的站点我最终还是会切换到无头浏览器方案。但 90% 的文档型和内容型站点这条脚本链路足够交差。我自己现在接手镜像类任务时一定会把校验步骤放进流程确保交付出去的目录能双击打开、链接不裂。希望帮到你。本文还有配套的精品资源点击获取