一、工具前置准备

1. Python 环境：安装 Python 3.6 及以上版本（推荐 3.8+），必须勾选配置环境变量（安装界面的「Add Python to PATH」），安装后可在终端输入python --version/python3 --version验证是否成功。
2. Git 工具（可选）：用于克隆仓库源码，若不会 Git 可直接下载源码压缩包，无需安装。
3. 其他要求：电脑连稳定网络、安装最新版手机 QQ（用于扫码登录），建议将 QQ 昵称中的特殊字符临时删除（避免登录失败）。

二、获取工具源码（两种方式二选一）

方式 1：Git 克隆源码（推荐，更新方便）

1. 打开电脑终端（Windows 用 CMD/PowerShell，macOS/Linux 用终端）；
2. 输入以下命令，克隆有效仓库到本地（命令为专属链接，切勿替换）：
   git clone https://github.com/XenonRuler/GetQQzonehistory.git
   
3. 克隆完成后，进入工具目录：
   cd GetQQzonehistory
   

方式 2：直接下载源码包（适合新手，无需 Git）

1. 打开浏览器访问有效仓库链接：https://github.com/XenonRuler/GetQQzonehistory；
2. 点击页面右上角Code按钮，选择Download ZIP下载源码压缩包；
3. 将压缩包解压到电脑任意目录（如桌面），并进入解压后的根目录（后续所有命令均在此目录执行）。

三、安装工具依赖（两种安装方式，推荐虚拟环境）

方式 1：虚拟环境安装（推荐，无依赖冲突）

1. 在工具根目录终端，输入命令创建虚拟环境（命名为 myenv）：
   python -m venv myenv
   # 若python命令无效，替换为python3：python3 -m venv myenv
   
2. 激活虚拟环境（Windows 和 macOS/Linux 命令不同，切勿混淆）：
   • Windows 系统（CMD/PowerShell）：
     myenv\Scripts\activate
     
   • macOS/Linux 系统：
     source myenv/bin/activate
     
   激活成功后，终端前缀会出现(myenv)标识。
3. 安装依赖（使用阿里云镜像，下载速度快，命令通用）：
   pip install -i https://mirrors.aliyun.com/pypi/simple/ -r requirements.txt
   # 若pip命令无效，替换为pip3：pip3 install -i https://mirrors.aliyun.com/pypi/simple/ -r requirements.txt
   

方式 2：本机环境安装（不推荐，快速体验）

pip install -i https://mirrors.aliyun.com/pypi/simple/ -r requirements.txt
# pip无效则用pip3

四、运行工具 & 扫码登录 & 爬取说说

1. 依赖安装完成后，在工具根目录终端输入运行命令，启动脚本：
   python main.py
   # python无效则替换为python3 main.py
   
2. 脚本启动后，终端会自动生成QQ 登录二维码（若二维码模糊 / 失效，重新运行命令即可）；
3. 打开手机 QQ，点击右上角「+→扫一扫」，扫描终端中的二维码，在手机上确认授权登录；
4. 授权成功后，脚本将自动开始爬取 QQ 空间历史说说，爬取时间根据说说数量而定（1000 条约 5-10 分钟），爬取过程中请勿关闭终端 / 断网。

五、查看爬取结果（Excel 格式）

1. 爬取完成后，脚本会自动将数据保存到工具目录的resource/result文件夹中；
2. 结果文件为你的 QQ 号.xlsx，用 Excel/WPS 打开即可查看，包含说说发布内容、发布时间等核心信息；
3. 工具其他目录说明（无需手动修改）：
   • resource/config：配置文件目录，默认保存路径无需调整；
   • resource/temp：爬取过程中的缓存目录，可随时删除。

六、高频问题解决（新手必看）

问题 1：终端提示python/pip: 命令未找到

• 原因：Python 未配置环境变量，或系统需用python3/pip3替代；
• 解决：所有命令中将python换为python3，pip换为pip3；若仍无效，重新安装 Python 并勾选「Add Python to PATH」。

问题 2：扫码登录失败 / 二维码无反应

• 解决 1：确保手机 QQ 为最新版本，更新后重新扫码；
• 解决 2：关闭电脑防火墙 / 杀毒软件，重新运行python main.py生成新二维码；
• 解决 3：检查手机和电脑是否连同一网络，切换 Wi-Fi / 热点后重试；
• 解决 4：删除 QQ 昵称中的特殊字符（如 emoji、符号），重新授权。

问题 3：依赖安装报错（红色文字提示）

• 解决 1：更新 pip 到最新版本，再重新安装依赖：
  python -m pip install --upgrade pip
  # python无效换python3
  
• 解决 2：关闭 VPN / 代理软件（网络代理会导致镜像源访问失败）；
• 解决 3：macOS/Linux 系统需安装编译依赖（命令如下），再重新安装：
  # Ubuntu/Debian
  sudo apt install build-essential python3-dev
  # CentOS/RHEL
  sudo yum install gcc gcc-c++ python3-devel
  

问题 4：爬取完成后无 Excel 文件 / 仅获取少量说说

• 原因：工具仅能获取 QQ 空间消息列表中存在的说说，仅自己可见、已删除且无互动记录的说说无法爬取；
• 解决：无额外解决方法，为工具功能固有限制。

问题 5：爬取过程中终端中断 / 报错

• 解决：重新运行python main.py，脚本支持断点续爬，无需重新扫码，会从上次中断位置继续爬取。

七、重要使用注意事项

1. 数据安全：所有爬取操作均在电脑本地完成，数据不上传至任何服务器，爬取完成后可删除 resource/temp 缓存目录，保护隐私；
2. 功能限制：该工具仅支持说说获取，无留言、相册恢复功能，且无法获取仅自己可见 / 消息列表无记录的说说；
3. 版本说明：该仓库分支比原版 LibraHp/GetQzonehistory 落后 59 个提交，若需更多功能，可关注原版仓库更新；
4. 合法使用：工具仅用于个人 QQ 空间数据备份，请勿用于爬取他人 QQ 空间数据、商用等违法违规行为，否则后果自负；
5. 环境退出：使用完虚拟环境后，可在终端输入deactivate退出，避免后续命令受虚拟环境影响。