提到 QQ 空间很多 90 后、00 后都不会陌生。从当年农场的“偷菜”提醒到深夜写在留言板里的小情绪再到现在偶尔翻出来的旧相册QQ 空间保存了大量个人数字记忆。但真正等到你想把日志、说说、相册一次性导出到本地时会发现官方并没有提供那种“一键下载我的全部内容”的功能。删掉的说说找不回来换手机后相册原图也容易丢失时间一长这些数据就真的没有了。GitHub 上有一个开源项目 gaoshu705/qzonearchive很多开发者习惯把它叫作“QQ 空间恢复助手”。它和我们平时理解的“恢复已删除内容”不太一样本质上是一个基于登录态的 QQ 空间数据归档工具把你在 QQ 空间公开和私密可见范围内的数据抓取下来整理成本地文件方便长期保存、检索和迁移。这篇文章会围绕这个开源项目拆解它的工作原理梳理从环境准备、配置 Cookie、执行归档到结果验证的完整过程并在最后给出常见报错和隐私安全方面的建议。无论你是想给自己留一份数字备份还是想学习“如何用登录态驱动一个数据导出工具”这篇文章都会对你有帮助。1. 背景与核心概念QQ 空间数据为什么需要归档1.1 QQ 空间的数据困境QQ 空间从 2005 年上线到现在经历了 Web 1.0 时代的内容农场、Web 2.0 时代的社交信息流以及移动端时代的流量主阵地。早期的大量日志、说说、相册、留言、访客记录很多都还停留在老版本的服务器存储结构中。官方虽然有“我的中心”“相册管理”等入口但并没有提供完整的个人数据导出服务。对普通用户来说想把数据从平台迁移到本地最常见的办法只有两种复制粘贴正文文字或者用截图工具一张一张截屏。这两种方式在小数据量时勉强可行但面对几百篇日志、上千条说说、几个 GB 的相册时效率低得让人崩溃而且会丢失发布时间、评论列表、点赞记录等元信息。对于有内容备份需求的用户来说一个能自动抓取并结构化的工具就显得格外重要。1.2 开源项目 QZoneArchive 是什么QZoneArchive 是 GitHub 上一个用于 QQ 空间数据归档的开源项目仓库地址为 gaoshu705/qzonearchive。它通过解析 QQ 空间网页端在浏览器中产生的数据请求在携带用户登录态的条件下把 QQ 空间中的日志、说说、相册等数据按类型导出到本地并生成便于浏览的归档文件。和很多同类工具一样它并不直接访问数据库或服务器后台而是模拟用户在浏览器中点击“下一页”“加载更多”时的行为。它不需要输入密码只需要用户提供浏览器登录后的 Cookie然后持续向 QQ 空间的数据接口发出请求再把返回的 JSON 数据解析、清洗、落盘。使用这套方式数据在平台侧看起来只是普通的前端翻页行为不需要任何后台权限也不涉及撞库、注入等高风险操作。需要注意qzonearchive 属于社区个人维护项目体积不大、定位明确它的最终价值取决于维护者对 QQ 空间前端接口变化的跟进速度。如果你的场景比较特殊建议先看仓库的 README 和近期 Issue再决定是否使用。1.3 备份、恢复与归档的区别标题里的“恢复助手”很容易让人误解为“把已经删除多年的 QQ 空间内容找回来”。这里有必要把三个概念区分开备份在数据还存在的时候把数据复制到另一个安全的存储位置防止未来丢失。恢复把备份数据重新还原到原平台或原系统里通常需要平台提供写入接口。归档把平台上的数据整理、转存为可访问、可检索的本地文件重点在于“长期保存”和“可查阅”。qzonearchive 做的是归档而不是真正意义上的“恢复”。它没有办法把已经删除的说说重新写回腾讯服务器但只要数据还在你的 QQ 空间里可见它就可以帮你抓下来、存到本地。如果你之前误删了内容且本地没有备份那这个工具无法解决如果你有大量内容还挂在空间里想搬回本地那它就是一个很合适的方案。2. 环境准备与版本说明2.1 运行时环境在开始使用 qzonearchive 之前需要确认本地环境满足基本要求。由于这是一个开源社区项目具体依赖会随时间更新以下给出通用环境说明环境项建议版本/要求说明操作系统Windows 10/11、macOS、常见 Linux 发行版跨平台项目建议优先使用 README 说明Git2.x 及以上用于克隆仓库和切换分支Python 或 Node.js以项目 README 标注为准不同归档工具技术栈不同不盲目猜版本浏览器Chrome、Edge 或 Firefox用于登录 QQ 空间并获取 Cookie终端Windows Terminal / iTerm2 / bash执行 Python 或 Node 命令这里不写死具体语言版本因为仓库可能存在技术栈调整。你只需要提前装好 Git以及你用来运行脚本的运行时环境其他包依赖在安装阶段通过项目自带配置文件统一安装。2.2 获取项目源码测试环境准备完成后下一步就是把代码拉到本地。打开终端进入你打算存放项目的目录然后执行git clone https://github.com/gaoshu705/qzonearchive.git cd qzonearchive如果你不准备参与二次开发只是希望使用最新稳定功能克隆默认分支即可。执行完git clone后建议先查看目录结构确认是否包含 README、requirements.txt 或 package.json、配置文件模板等关键文件。如果你经常访问 GitHub 不稳定下载大文件或者频繁拉取代码失败可以考虑使用 GitHub 镜像站或者稍后在网络状态较好的时候重新执行命令。不建议把整个仓库压缩包通过不安全的第三方渠道下载以防文件被篡改。2.3 安装项目依赖当项目使用 Python 时通常会在根目录提供一个 requirements.txt 或 pyproject.toml 文件。这时可以创建一个独立的虚拟环境把依赖安装在虚拟环境中避免污染系统 Pythonpython -m venv venv source venv/bin/activate pip install -r requirements.txtWindows 环境下激活虚拟环境的命令是venv\Scripts\activate pip install -r requirements.txt当项目使用 Node.js 时依赖安装命令通常是npm install无论是哪种技术栈都要特别注意安装依赖前先确认项目有没有独立的依赖清单。如果项目只提供了源码没有依赖清单此时需要检查 README 中对第三方库的说明。没有把握的情况下不要盲目尝试运行主脚本否则很容易遇到缺模块的报错。2.4 IDE 与调试工具命令行工具加上简单的文本编辑器就足够跑通流程。不过如果你准备二次开发或想搞清楚每个文件的作用建议使用 VS Code 或 PyCharm。额外推荐准备一个浏览器开发者工具。因为 QQ 空间的登录态最终是以 Cookie 形式存在的而获取 Cookie 的最直接方式就是打开浏览器开发者工具的 Network 面板找到任意一个请求从请求头中拷贝 Cookie 字段。虽然项目本身可能提供了更简便的“扫码登录获取 Cookie”的辅助脚本但理解浏览器中 Cookie 的位置仍然很重要。3. 核心原理拆解QQ 空间归档到底在做什么3.1 登录态与 CookieQQ 空间里大部分个人数据并不是完全公开的。要读取你自己可见的内容工具必须以你的身份向服务器发起请求。在网页端用户登录成功后浏览器会保存一组 Cookie这组 Cookie 中包含了会话凭证。后续每一次请求只要在请求头里带上 Cookie服务器就会认为你是登录用户从而返回完整数据。获取 Cookie 的标准流程是先用浏览器登录 qzone.qq.com打开开发者工具切换到 Network 面板刷新页面找到任意一个 XHR 请求复制请求头中的 Cookie 值。这里要注意Cookie 具有时效性过一段时间可能失效失效后需要重新登录并更新配置。你可以把 Cookie 看作一把临时钥匙它只能证明“某个时间窗口内你是你”因此不要把它提交到公共仓库也不要随意发给他人。3.2 数据接口与抓取策略QQ 空间网页端的前端页面不会一次性把所有数据渲染出来日志、说说、相册都是按页加载的。当用户滚动到页面底部或点击“查看更多”时浏览器会发送一个带着页码或起始时间戳的 XHR 请求服务器返回一段 JSON 数据前端再把 JSON 渲染成页面元素。qzonearchive 的核心思路就是模拟这个翻页过程。工具会构造和浏览器一样的请求参数带上你的 Cookie循环请求到没有更多数据为止。一次完整的归档可能包含多个数据类别例如说说列表日志列表与正文相册列表与相片原图 URL留言板内容个人资料信息不同数据类型的接口差异较大有些分页模式是页码递增有些是基于时间游标。项目在抓取时通常会针对不同类型的接口做适配并将原始 JSON 数据先保存下来避免因为请求中断而丢失已经获取到的内容。3.3 数据解析与落盘拿到 JSON 原始数据后工具会做数据清洗。典型的清洗操作包括去掉 HTML 标签、将时间戳转换成可读日期、把图片缩略图地址替换为原图地址、把嵌套的评论列表拍平。清洗后的数据通常按以下结构保存archive/ ├── index.html ├── moments/ │ ├── 2025-01-01-001.json │ └── ... ├── diaries/ │ ├── 2025-01-02-hello-world.md │ └── ... ├── photos/ │ ├── album-01/ │ └── ... └── meta/ └── profile.json有些项目会直接生成一组静态 HTML 文件通过目录索引的方式提供离线浏览体验。这样做的好处是即使 QQ 空间未来改版或关闭你依然可以在本地浏览器中打开归档页面按时间线浏览自己的历史内容。3.4 为什么选择传 Cookie 而不是账号密码很多人第一次接触这类工具时会疑惑为什么工具不直接让我输入 QQ 号和密码主要原因有两个。第一账号密码属于最高敏感级凭证一旦被恶意脚本窃取攻击者可以登录账号、修改密码、读取全部隐私风险太大。第二QQ 登录流程往往包含验证码、设备锁、二次验证等额外环节自动化处理这些环节不仅复杂还容易被平台风控拦截。Cookie 的作用范围相对有限它只代表当前会话的访问权限而且有效期内过期后需要重新授权。使用 Cookie意味着工具只负责“用你的身份去读取数据”而不需要触碰你的密码。话虽如此Cookie 同样不能泄露。拿到 Cookie 的人完全可以模拟你的请求读取数据因此在保存和传输 Cookie 时要像对待密码一样谨慎。4. 完整实战从克隆仓库到导出归档4.1 创建项目结构先把 qzonearchive 克隆到本地并建立好输出目录mkdir -p ~/projects/qzone-archive-demo cd ~/projects/qzone-archive-demo git clone https://github.com/gaoshu705/qzonearchive.git cd qzonearchive mkdir -p output这里单独创建 output 目录是为了把源码和归档结果分开。归档结果会包含大量带个人隐私的数据放在独立目录中方便后续打包备份也更易于在.gitignore中排除避免误提交。4.2 查看 README 与配置文件执行以下命令查看仓库文件列表ls -la重点关注是否存在以下文件README.mdrequirements.txt或package.jsonconfig.example.yaml或config.example.json入口脚本例如main.py、index.js或run.py如果存在配置文件模板复制一份并改名为实际配置文件名cp config.example.yaml config.yaml修改 config.yaml 时通常需要填入账号信息、Cookie、导出数据范围等参数。不同项目的配置项差异很大不要照搬网上的旧教程一切以仓库内模板注释为准。以常见配置为例大概长这样# config.yaml示例以仓库实际模板为准 account: qq: 123456789 cookie: 粘贴你的 Cookie export: output_dir: ./output include_moments: true include_diaries: true include_photos: true photo_size: original request: delay_seconds: 2 max_retries: 3 timeout_seconds: 10这里的request.delay_seconds尤其重要。请求间隔太短容易被风控拦截间隔太长又会拖慢整体速度。一般建议设在 1 到 3 秒之间正式执行时根据实际情况微调。4.3 获取并配置 Cookie在浏览器中登录 QQ 空间打开开发者工具切换到 Network 面板刷新页面随便点开一个名为qzone或cgi-bin的请求在 Request Headers 中找到Cookie:开头的字段。复制整段 Cookie 值粘贴到 config.yaml 的cookie字段中。操作时注意不要把引号一起复制进去。如果配置文件中 Cookie 字段已经带引号那粘贴时只需要替换引号中间的部分。这里有一个常见误区直接把浏览器地址栏里的 URL 复制出来。URL 和 Cookie 完全是两回事地址栏里只有访问地址没有身份凭证。必须从请求头中取 Cookie否则工具无法识别你的登录身份。4.4 运行归档脚本配置完成后在项目根目录执行入口脚本。以 Python 项目为例python main.py --config config.yaml运行过程中终端会输出进度信息。合理预期输出类似[INFO] 开始归档 QQ 空间数据 [INFO] 账号123456789 [INFO] 正在抓取说说数据... [INFO] 获取第 1 页成功累计 20 条 [INFO] 获取第 2 页成功累计 40 条 [INFO] 获取第 3 页成功累计 60 条 [INFO] 说说抓取完成共 60 条 [INFO] 正在抓取日志数据... [INFO] 日志抓取完成共 8 篇 [INFO] 正在抓取相册数据... [INFO] 相册抓取完成共 3 个相册32 张照片 [INFO] 正在生成静态归档页面... [INFO] 归档完成输出目录./output不同项目输出格式可能有差异但整体流程类似。运行时间取决于数据量和请求间隔几百条说说通常几分钟内完成如果相册原图很多下载图片可能耗时长一些。4.5 验证归档结果归档完成后进入输出目录检查文件cd output du -sh . find . -type f | head -20用du查看总大小用find查看文件列表。随后在本地启动一个静态服务器预览归档页面python -m http.server 8080打开浏览器访问http://localhost:8080查看index.html。确认是否能正常浏览说说时间线、日志正文、相册缩略图和原图。如果图片较多也可以直接用浏览器打开本地 HTML 文件不过部分浏览器对本地文件的安全限制比较严格很多“file:// 协议下加载本地图片”的页面会出现空白所以更推荐用http.server的方式访问。4.6 二次开发一个极简的归档思路示例下面这段代码不是 qzonearchive 的原始源码只是一个用来帮助你理解归档逻辑的极简示意。它展示的是“从 JSON 数据生成静态 HTML”的过程不涉及任何 QQ 空间接口。# 文件路径examples/build_archive.py # 说明示意代码仅用于理解归档原理不能直接用于抓取 QQ 空间 import json import pathlib from datetime import datetime def load_moments(json_path: str) - list: with open(json_path, r, encodingutf-8) as f: return json.load(f) def build_index_html(moments: list, output_path: str) - None: items_html [] for m in moments: ts datetime.fromtimestamp(m[timestamp]) content m.get(content, ) items_html.append( flitime{ts:%Y-%m-%d %H:%M}/timep{content}/p/li ) page f!DOCTYPE html html langzh-CN head meta charsetUTF-8 titleQQ 空间归档/title /head body h1我的说说归档/h1 ul{.join(items_html)}/ul /body /html pathlib.Path(output_path).write_text(page, encodingutf-8) if __name__ __main__: build_index_html( load_moments(moments.json), archive/index.html, )这个例子展示了“原始数据 渲染模板 静态归档”的基本思路。真实项目的复杂之处在于大量接口适配、分页处理、反爬风控和图片下载本质上的数据处理模式和这段示意代码是一致的。5. 常见问题与排查思路5.1 高频问题整理问题现象常见原因解决思路运行后提示 Cookie 失效或请求返回登录页Cookie 过期或复制时漏掉字段重新登录空间重新复制完整 CookieModuleNotFoundError: No module named xxx未安装依赖或虚拟环境未激活激活虚拟环境后重新执行 pip install只抓到了说说日志/相册为空配置中对应开关未打开或隐私权限限制检查配置文件开关确认空间隐私设置下载图片时频繁失败请求频率过高或个别图片链接失效调大请求延迟开启重试机制归档页面打开后图片不显示file:// 协议对本地文件限制使用本地静态服务器访问抓取中途程序被中断网络波动或风控触发观察是否支持断点续传不支持的需重跑GitHub 下载源码速度很慢网络环境影响使用镜像站或选择网络空闲时段拉取5.2 提示 Cookie 过期怎么处理Cookie 过期是最常见的坑。很多人上午还能跑通下午再跑就提示登录失效。本质上是因为会话凭证有有效期限制或者你曾经在别处修改过密码、退出过登录导致旧会话被作废。解决方法是回到浏览器重新打开 QQ 空间确认登录状态正常后再重新获取一次 Cookie。在正式执行归档之前可以先跑一条测试请求确认数据接口返回的不是登录跳转页面。不要等到抓了几百页以后才发现 Cookie 已经失效那会浪费大量时间。5.3 数据只导出了一部分如果你发现自己某年的说说没有出现在归档文件中先不要怀疑工具坏了更可能是数据可见性配置。QQ 空间的很多内容支持“仅自己可见”“部分好友可见”“所有人可见”而抓取工具只能抓到“以你的身份登录后能够看到的数据”。如果你的某个相册设置了独立密码或者某条日志对指定好友分组可见另外一台设备上抓取时可能不会返回相同结果。建议在归档前先到 QQ 空间网页端把需要导出的相册、日志、留言板都设置为“所有人可见”或保持默认登录可见状态。如果某些内容设置了访问密码需要在浏览器中先解开访问权限再去抓取。5.4 GitHub 访问异常时如何继续GitHub 在国内的访问并不总是稳定偶尔会出现Connection reset、Failed to connect或下载速度极慢的情况。遇到这类问题不需要尝试任何学术或代理访问方式可以按下面几种方案依次尝试过几分钟或换个时间段重新执行git clone。使用 GitHub 镜像站下载 release 压缩包。如果只是想浏览代码直接在 GitHub 网页端查看。这里特别提醒不要迷信网上所谓的“加速工具”。很多加速脚本来源不明可能会在你的环境中植入恶意代码处理包含个人隐私的项目时风险尤其大。5.5 抓取请求被风控拦截怎么办当工具在较短时间内发出过多请求时QQ 空间可能会临时限制当前会话的接口频率。表现是前几页正常后面突然连续返回空数据或跳转到安全验证页面。这时候立即停止运行不要反复重试。等待 10 到 30 分钟后再重新运行。同时可以在配置中把请求延迟调大例如从 1 秒调整到 3 秒。归档不是竞速比赛数据完整比速度重要。6. 最佳实践与工程建议6.1 隐私安全底线Cookie 等同于你的临时身份凭证。拿到 Cookie 的人可以在有效期内读取你的 QQ 空间数据、好友可见内容甚至部分账号信息。因此必须做到不要把含 Cookie 的配置文件提交到 GitHub。不要让工具输出目录暴露在公网。归档完成后及时删除临时配置文件中的 Cookie 字段。如果怀疑 Cookie 泄露去 QQ 安全中心强制下线所有会话再重新登录。如果你要分享归档文件给他人建议先清理包含个人敏感信息的数据或者只分享允许公开的部分。6.2 数据完整性的验证方法归档完成不等于归档成功。建议按下面的 checklist 校验说说条数是否和页面显示的“全部说说数量”一致。日志正文是否包含图片图片是否能正常打开。相册缩略图数量是否和原相册一致。随机抽查几条点赞、评论数据确认嵌套数据没有丢失。用du -sh检查输出目录大小确认图片下载完整。更稳妥的方式是在正式归档前两天先跑一次小范围测试只导出一个相册或第一页说说确认流程没有异常后再全量执行。6.3 定期归档与版本化管理数字数据不是静态的。你今天归档了明天可能又发了几条新说说旧的评论也可能新增。建议把归档做成周期性任务例如每季度执行一次全量归档。如果你具备一定开发能力可以把归档输出目录做成 Git 仓库每次归档后提交一次。好处是可以对比不同时间点的数据差异也能在你误删本地文件时找回历史版本。需要注意含隐私的文件推送到远程仓库前要三思建议只提交本地不同步到远程。6.4 合理控制请求频率很多抓取工具在持续请求后触发风控本质原因是频率太高。一个比较稳妥的策略是普通文本数据请求间隔 1 到 2 秒。图片下载请求间隔 0.5 到 1 秒。每抓取 50 个请求后暂停 5 到 10 秒。遇到异常响应时指数退避重试。这些参数不要盲目套用需要结合你所在网络环境和项目限制调整。核心原则是让自己看起来像一个正常滚动网页的用户而不是一个高速扫描器。6.5 评估项目活跃度与维护状态使用社区开源项目之前建议花几分钟评估项目是否值得信赖查看 README 是否详细、是否有使用截图。查看最近一次提交时间判断是否持续维护。查看 Issues 中是否有大量未关闭的相同故障。查看 Star 数、Fork 数但不要把这些数值作为唯一指标。如果项目已经半年没有更新而 QQ 空间前端接口最近发生大改那工具很可能已经失效。这时可以关注仓库相关的 pull request看是否有人提交了修复代码。你也可以自己 Fork 一份进行修复这也是开源社区常见的参与方式。7. 总结与后续学习方向通过这篇教程你应该已经理解 qzonearchive 这类 QQ 空间归档工具的核心逻辑借助 Cookie 携带登录态模拟网页端的翻页请求把原本只存在于平台服务器中的个人数据转换成 JSON、图片和静态页面最终落到你的本地磁盘。你也应该能独立完成从克隆仓库、安装依赖、配置 Cookie 到运行脚本、验证输出这一整套流程。如果你只是想把 QQ 空间数据保存下来下一步要做的事情很简单找一个完整的时间段在浏览器里重新确认登录状态按照第四章的步骤跑一次全量归档然后把结果目录同步到移动硬盘或网盘。删除任何线上内容之前先确认归档文件可以在本地正常浏览不要依赖“删了还能恢复”的侥幸心理。如果你是开发者这个项目其实是很好的学习样本。你可以顺藤摸瓜研究几个方向QQ 空间网页端的数据接口是怎么设计的分页和游标机制有什么区别JSON 数据如何高效转成静态站点以及如何在请求层做限速、重试和断点续传。理解这些以后你不仅能维护自己的归档工具还能迁移到微博、小红书等其他平台的个人数据导出场景。开源项目的价值不仅在代码本身也在于它能给你一个完整的分析样本。与其到处找现成的“恢复教程”不如趁这个机会把自己的备份体系建立起来把主动权拿回自己手里。