3步搞定网站整站下载器，手写实现避坑指南

官方文档翻了三遍还是晕？别慌，整站下载看着复杂，其实核心就那几行代码。今天直接上干货，带你手写实现一个轻量级爬虫，不用装一堆重型框架，用 Python 标准库和 requests 就能跑通。

很多新手卡在“怎么递归抓取链接”这一步，其实只要理清 HTTP 请求和文件保存的逻辑，整站镜像并不难。咱们不整虚的，直接拆解实战流程，保证你看完就能在本地跑出一个完整的离线站点。

概念速懂：整站下载到底在抓什么

先搞清楚，网站整站下载器不是把网页源码存下来就完事了。它需要处理三类资源：HTML 页面、静态资源（CSS/JS/图片）、以及动态加载内容。

传统工具如 wget 或 httrack 虽然好用，但面对反爬严格的站点经常失效。而手写实现的优势在于可控性——你可以自定义请求头、处理验证码、甚至模拟人类操作节奏。

核心逻辑很简单：

1. 广度优先搜索（BFS）：从首页开始，把发现的链接放入队列。
2. 去重机制：用 Set 记录已访问 URL，避免死循环。
3. 本地映射：把网络 URL 转成本地文件路径，保持相对路径一致。

这里有个关键细节：很多教程忽略相对路径解析。比如 a 标签指向 ./page2.html，而绝对路径是 https://example.com/page2.html。如果本地保存时不统一处理，页面打开后样式和图片全会裂开。

环境准备：别装错依赖包

咱们只依赖两个库：requests 发请求，urllib.parse 处理 URL。其他全是 Python 内置模块。

pip install requests

创建项目结构：

downloader/
├── main.py          # 主程序
├── crawler.py       # 核心爬虫类
├── utils.py         # 工具函数
└── downloads/       # 输出目录

为什么不用 Scrapy？对于整站下载这种线性任务，Scrapy 太重了。启动慢、配置繁琐，对于个人开发者或轻量级需求，手写实现反而更灵活。你随时可以插入断点调试，而不是被框架黑盒化。

核心语法：三个关键函数拆解

整站下载器的灵魂在 crawl 方法里。我们分三步走：解析链接、下载资源、保存文件。

1. URL 规范化与去重

直接复制网上代码最容易出的 bug 就是 URL 格式不一致。比如带不带斜杠、带不带端口号。

from urllib.parse import urlparse, urljoin, urldefragdef normalize_url(url):"""统一URL格式，去掉fragment和多余参数"""# 去掉锚点部分 #sectionurl, _ = urldefrag(url)# 解析URL组件parsed = urlparse(url)# 如果是协议相对路径，补全协议if not parsed.scheme:url = "https://" + urlparsed = urlparse(url)# 默认端口80/443可省略netloc = parsed.netlocif parsed.scheme == "http" and parsed.port == 80:netloc = parsed.hostnameelif parsed.scheme == "https" and parsed.port == 443:netloc = parsed.hostname# 重建URL，路径为空时补/path = parsed.path or "/"query = f"?{parsed.query}" if parsed.query else ""return f"{parsed.scheme}://{netloc}{path}{query}"

重点：urldefrag 这一步千万别省。很多网站导航栏带锚点，如果不去掉，同一个页面会被当成多个 URL 重复下载。

2. 链接提取与过滤

用正则提取 <a> 和 <img> 标签不够稳健，推荐用 lxml 或简单的字符串匹配。为了轻量，这里用正则：

import redef extract_links(html_content, base_url):"""从HTML中提取所有外部链接"""links = set()# 匹配 href 和 src 属性pattern = r'(?:href|src)\s*=\s*["\']([^"\']+)[\'"]'matches = re.findall(pattern, html_content)for link in matches:# 跳过邮件、javascript、纯锚点if link.startswith(('mailto:', 'javascript:', '#')):continue# 转为绝对路径abs_url = urljoin(base_url, link)abs_url = normalize_url(abs_url)# 只保留同域名的链接（防止爬遍全网）if urlparse(abs_url).netloc == urlparse(base_url).netloc:links.add(abs_url)return links

避坑提示：urljoin 是处理相对路径的关键。比如当前页是 https://example.com/a/b.html，链接是 ./c.html，urljoin 会正确解析为 https://example.com/a/c.html，而不是 https://example.com/c.html。

3. 文件路径映射

这是整站下载最容易出错的地方。网络路径 https://example.com/css/style.css 不能直接映射为本地路径，因为域名不能当文件夹名。

import os
from urllib.parse import urlparsedef url_to_path(url, base_domain):"""将URL转换为本地文件路径"""parsed = urlparse(url)path = parsed.path# 如果路径是 /，映射为 index.htmlif path == '/' or path == '':path = '/index.html'# 清理路径中的特殊字符safe_path = re.sub(r'[<>:"/\\|?*]', '_', path)# 拼接本地目录local_path = os.path.join("downloads", base_domain, safe_path)# 确保父目录存在os.makedirs(os.path.dirname(local_path), exist_ok=True)return local_path

注意：Windows 下路径分隔符是 \，但 Python 的 os.path 会自动处理。千万别手动拼接字符串，否则跨平台必挂。

完整代码示例：可运行的整站下载器

把前面片段组装起来，这是一个最小可运行的版本。

import requests
import time
import os
from crawler import normalize_url, extract_links, url_to_path
from urllib.parse import urlparseclass SiteDownloader:def __init__(self, start_url, max_pages=100):self.start_url = normalize_url(start_url)self.base_domain = urlparse(self.start_url).netlocself.visited = set()self.queue = [self.start_url]self.max_pages = max_pagesself.session = requests.Session()# 设置请求头，模拟浏览器self.session.headers.update({'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36'})def download(self):print(f"Starting download from {self.start_url}")print(f"Domain: {self.base_domain}")while self.queue and len(self.visited) < self.max_pages:current_url = self.queue.pop(0)if current_url in self.visited:continueprint(f"Processing: {current_url}")self.visited.add(current_url)try:response = self.session.get(current_url, timeout=10)if response.status_code != 200:print(f"  Skipping: {current_url} (Status: {response.status_code})")continue# 判断内容类型content_type = response.headers.get('Content-Type', '')if 'html' in content_type:self._process_html(current_url, response.text)else:self._save_file(current_url, response.content)except requests.RequestException as e:print(f"  Error: {e}")# 礼貌爬取，避免被封time.sleep(0.5)print(f"Finished. Downloaded {len(self.visited)} pages.")def _process_html(self, url, html_content):"""处理HTML页面，提取新链接"""# 保存HTML文件local_path = url_to_path(url, self.base_domain)with open(local_path, 'w', encoding='utf-8') as f:f.write(html_content)print(f"  Saved: {local_path}")# 提取新链接加入队列new_links = extract_links(html_content, url)for link in new_links:if link not in self.visited:self.queue.append(link)def _save_file(self, url, content):"""保存非HTML资源（图片、CSS、JS）"""local_path = url_to_path(url, self.base_domain)with open(local_path, 'wb') as f:f.write(content)print(f"  Saved: {local_path}")if __name__ == "__main__":# 测试用：选择一个开放且简单的站点target = "https://httpbin.org/html"downloader = SiteDownloader(target, max_pages=5)downloader.download()

运行说明：

1. 把代码保存为 main.py，crawler.py 包含前面提到的三个函数。
2. 执行 python main.py。
3. 检查 downloads/ 目录，HTML 文件里引用的 CSS 和图片应该都能正确打开。

关键优化点：

• Session 复用：requests.Session 会保持 TCP 连接，比每次新建连接快 3-5 倍。
• 超时设置：timeout=10 防止卡在无响应的服务器上。
• 最大页数限制：max_pages 防止意外爬遍整个 CDN 域名，烧掉你硬盘和带宽。

常见报错与避坑指南

实际跑起来，90% 的问题出在这几个地方：

1. 编码乱码

现象：保存的 HTML 打开全是方块或问号。 原因：服务器没返回 Content-Type 的 charset，或者返回的是 gbk 而非 utf-8。 解决：

# 在 _process_html 中动态检测编码
if 'charset' not in response.headers.get('Content-Type', '').lower():response.encoding = response.apparent_encoding  # 自动检测

根据 MDN Web Docs 的建议，当 HTTP 头未指定编码时，浏览器会尝试自动检测。我们在 Python 里也要模拟这个行为，否则中文页面必乱。

2. 死循环爬取

现象：队列无限增长，内存爆炸。 原因：URL 规范化不彻底，比如 ?utm_source=xx 参数每次不同。 解决：在 normalize_url 中过滤掉追踪参数：

# 在 normalize_url 中添加
params = parsed.query
if params:# 过滤常见追踪参数exclude = ['utm_', 'fbclid', 'gclid']filtered = [p for p in params.split('&') if not any(ex in p for ex in exclude)]query = f"?{'&'.join(filtered)}" if filtered else ""

3. 403 Forbidden

现象：部分页面返回 403，下载不完整。 原因：IP 被限流或 User-Agent 被拦截。 解决：

• 随机更换 User-Agent。
• 增加 time.sleep 间隔，建议 1-3 秒。
• 对于重要站点，考虑使用代理池。

4. 相对路径失效

现象：本地打开页面，样式丢失。 原因：CSS 文件里的 url() 指向相对路径，但本地文件结构没对齐。 解决：目前这个简单版只下载 HTML 和资源文件，不修改 CSS 内容。如果需要完美离线，还需要解析 CSS，把其中的 url() 也转换为本地路径。这是进阶需求，初期可忽略。

小结与实战建议

手写实现整站下载器，核心不在于代码多复杂，而在于URL 规范化和路径映射这两个细节。很多人抄完代码跑不起来，90% 是栽在路径解析上。

给公路工程从业者或全栈开发者的建议：

1. 先小后大：先用 httpbin.org 或公司内网测试站点跑通，再上生产。
2. 日志为王：把每个 URL 的处理状态写进日志，出问题时能快速定位。
3. 合规第一：遵守目标网站的 robots.txt。虽然代码里没写，但实际部署时必须加上。根据 MDN Web Docs 关于爬虫的指南，尊重 Disallow 规则是基本底线。

你公司项目里是怎么处理整站备份或数据归档的？是用现成工具还是自己写脚本？欢迎评论聊聊你的踩坑经验，特别是那些奇葩的反爬策略。