Pixiv Crawler Desktop Edition

面向 Windows 的 Pixiv 图片管理与下载桌面工具。项目使用 Electron 提供图形界面， 通过 Python 执行下载、TAG 补全、TAG 筛选和相似图片分析。

本仓库是 CWHer/PixivCrawler 的衍生版本， 基于上游提交 cd80acc 继续开发。当前默认分支为 main；上游更新不会自动合并， 而是经过兼容性审查后按需手工整合。

项目状态

• 当前提供源码运行版，尚未提供安装程序、便携包或打包后的可执行文件。
• 桌面 GUI 主要面向 Windows 10/11；Cookie 加密和文件操作使用 Electron 的 Windows 系统能力。
• GUI 当前提供个人收藏下载和指定画师下载，不提供排行榜或关键词搜索入口。
• Python 模块中保留的其他爬虫类不属于当前 GUI 的主要验证范围。

GUI 功能

爬虫任务

• 下载当前 Pixiv 账号的公开收藏，可设置最大作品数量。
• 下载指定画师的所有可访问作品。
• 为每个任务设置流量上限；达到上限后停止继续下载。
• 最多同时运行 3 个普通爬虫任务，其余任务自动排队。
• 显示任务状态、进度和最多 2,000 行会话日志。
• 支持取消排队任务、停止运行任务，以及移除已经结束的任务记录。

TAG 筛选

• 根据中央 SQLite TAG 元数据库或图片目录内的兼容 tags.json 筛选图片。
• 支持 TAG 精确匹配和模糊匹配。
• 默认将匹配图片移动到输出目录；勾选“仅预览，不移动图片”后只显示结果。
• TAG 筛选是本地文件任务，不占用爬虫任务槽位。

TAG 补全

• 从 作品ID_p页码.扩展名 格式的文件名识别 Pixiv 作品，例如 144431180_p0.png。
• 请求 Pixiv TAG 信息并写入所有图片目录共用的中央 SQLite 元数据库。
• 同步维护图片目录内的 tags.json，兼容旧版本工作流。
• 已存在于中央元数据库的作品会直接复用，不重复请求 Pixiv。
• 默认使用 2 个工作线程，但全局限制为每 1.5 秒启动一个请求。
• 每处理 100 个作品保存一次检查点并暂停 30 秒，可在中断后重新运行续接。
• 连续遇到 3 次 HTTP 429，或收到 401/403 时停止任务，避免继续触发限流或认证错误。
• TAG 补全运行期间独占全部 3 个网络任务槽位，普通下载任务会继续排队。

TAG 统计与图片浏览

• 按所选目录内实际存在的图片页统计 TAG 数量，并按数量降序显示。
• 同一作品的多页图片分别计数，同时显示对应作品数量。
• 点击 TAG 可在独立窗口中浏览该 TAG 对应的全部本地图片。
• 旧目录中的 tags.json 会按需导入中央元数据库，已有 TAG 只合并、不静默删除。
• 图片移动到其他目录后，只要文件名仍保留作品 ID，仍可从中央元数据库找回 TAG。

相似图片

• 使用 64 位感知哈希扫描 JPG、JPEG、PNG、WebP、BMP 和 GIF。
• 相似阈值范围为 0–64，默认值为 6；数值越大，匹配范围越宽。
• 默认递归扫描子目录，也可关闭递归。
• 自动忽略同一 Pixiv 作品中页码不同的图片，减少正常多页作品的误报。
• 首次扫描在图片目录生成 .pixivcrawler-image-fingerprints.sqlite3 指纹缓存； 后续只重新计算新增或发生变化的文件。
• 支持图片预览、使用默认应用打开、在资源管理器中定位、复制路径，以及确认后移入回收站。
• 删除指纹缓存文件可强制重新计算全部图片。

应用设置

• Pixiv 用户 UID。
• 可选代理，例如 127.0.0.1:1080；非本机代理请填写完整的 http://主机:端口 地址。
• Pixiv Cookie。
• 图片保存目录。
• Python 命令或解释器绝对路径。
• 中央 TAG 元数据库路径。

设置会保存在 Electron 的用户数据目录。Cookie 使用 Electron safeStorage 调用 Windows 系统加密后保存，不会写入 pixiv_crawler/config.py；再次保存设置时， Cookie 输入框留空会保留已经加密保存的值。

安装要求

必需环境

组件	要求	当前验证版本
操作系统	Windows 10/11 64 位	Windows
Conda	Miniconda 或 Anaconda	Conda 24.11.3
Python	Python 3.11，推荐环境名 pixiv_py311	Python 3.11.13
Node.js	用于安装依赖和启动 Electron	Node.js 22.14.0
npm	随 Node.js 安装	npm 10.9.2
Electron	由项目依赖自动安装	Electron 42.3.3

还需要：

• 能够访问 Pixiv；如网络环境需要代理，请先准备可用的 HTTP 代理。
• 执行下载或 TAG 补全时需要有效的 Pixiv Cookie 和用户 UID。
• Python 依赖包括 Beautiful Soup、NumPy、Pillow、python-dotenv、Requests 和 tqdm， 具体固定版本以 requirements.txt 为准。

首次安装

1. 获取代码

git clone https://github.com/CCP101/PixivCrawler.git
Set-Location PixivCrawler

2. 创建 Conda 环境

应用会优先自动查找名为 pixiv_py311 的 Conda 环境，因此推荐使用这个名称：

conda create -n pixiv_py311 python=3.11 -y
conda activate pixiv_py311
python -m pip install -r requirements.txt

如果环境已经存在，只需重新对齐依赖：

conda activate pixiv_py311
python -m pip install --upgrade -r requirements.txt
python -m pip check

3. 安装 Electron 依赖

仓库包含 package-lock.json，首次安装推荐使用可复现的 npm ci：

npm ci

4. 启动 GUI

npm start

启动时应用按以下顺序选择 Python：

1. 当前已经激活的 pixiv_py311。
2. 从 Conda 安装目录、CONDA_EXE、PATH 和常见用户目录查找 pixiv_py311。
3. 调用 conda run -n pixiv_py311 查询解释器路径。
4. 找不到该环境时回退到系统 PATH 中的 python。

也可以在“应用设置”中填写其他 Python 3.11 解释器的绝对路径进行覆盖。

首次配置

启动后先打开“应用设置”，填写：

1. Pixiv 用户 UID：登录账号的数字 UID。
2. 代理：可选；本机代理可写成 127.0.0.1:1080。
3. Pixiv Cookie：从浏览器开发者工具中复制已登录 Pixiv 请求的完整 Cookie 请求头值。
4. 图片保存目录：收藏和画师下载任务的输出位置。
5. Python 命令或路径：通常保持自动识别结果即可。
6. TAG 元数据库：建议保留默认路径，或选择一个长期不会移动的 SQLite 文件。

保存设置时 UID、Cookie、图片目录、Python 和元数据库路径不能为空。 如果 Windows 系统加密不可用，应用会拒绝明文保存 Cookie。

使用说明

下载收藏或画师作品

1. 完成应用设置。
2. 进入“爬虫任务”。
3. 选择“个人收藏”或“指定画师”。
4. 设置最大作品数量或画师 UID，并填写流量上限。
5. 点击“加入任务队列”。

任务记录和日志只在本次应用运行期间保存。关闭应用时，排队任务会被取消， 仍在运行的 Python 进程会被终止。

按 TAG 移动图片

1. 进入“TAG 筛选”。
2. 输入 TAG，选择精确或模糊匹配。
3. 选择源图片目录和输出目录。
4. 首次操作建议勾选“仅预览，不移动图片”。
5. 确认结果后取消预览选项，再执行实际移动。

如果中央元数据库中没有对应记录，GUI 会尝试读取源目录下的 tags.json。

为旧图片目录补全 TAG

1. 确认文件名包含 Pixiv 作品 ID 和页码。
2. 进入“TAG 补全”并选择图片目录。
3. 启动任务并等待检查点保存。
4. 任务因限流、认证失败或手工停止而中断时，更新 Cookie 或等待后重新运行即可。

不要同时启动外部脚本进行大量 Pixiv 请求；TAG 补全已经内置限速、批处理和重试策略。

查看 TAG 排行或相似图片

• “TAG 统计”只统计所选目录顶层符合 Pixiv 命名规则的图片。
• “相似图片”默认递归扫描，并支持普通图片文件名。
• 相似图片页面的“移到回收站”会先显示确认对话框；其余扫描和预览操作不会自动删除文件。

数据文件与隐私

数据	默认位置或行为
GUI 设置	Electron 用户数据目录中的 settings.json
GUI Cookie	settings.json 内的 Windows 系统加密数据
中央 TAG 元数据库	Electron 用户数据目录中的 pixiv-metadata.sqlite3，可在设置中修改
兼容 TAG 文件	图片目录内的 tags.json
相似图片缓存	扫描目录内的 .pixivcrawler-image-fingerprints.sqlite3
下载图片	“应用设置”指定的图片保存目录
任务和日志	仅保存在当前运行会话

仓库根目录的 .env 仅供直接运行 Python CLI 时使用，并已被 Git 忽略：

Copy-Item .env.example .env

PIXIV_COOKIE=你的完整 Pixiv Cookie

不要把 Cookie 写入源码、命令行历史、截图、Issue 或 Git 提交。Cookie 失效后应及时更新； 如果怀疑泄漏，应先在 Pixiv 端撤销会话，再清理本地或远端历史。

CLI 辅助入口

GUI 通过以下 CLI 执行后台任务：

conda run -n pixiv_py311 python pixiv_crawler/cli.py --help

当前 CLI 子命令为：

• bookmark：下载当前账号的公开收藏。
• artist：下载指定画师作品。
• filter-tag：按 TAG 预览或移动图片。
• collect-tags：为本地图片补充 TAG。
• similar-images：扫描相似图片并输出 JSON。

直接调用需要认证的子命令时，通过环境变量传入 Cookie：

$env:PIXIV_COOKIE = "你的完整 Pixiv Cookie"
conda run -n pixiv_py311 python pixiv_crawler/cli.py bookmark --help

常见问题

GUI 使用了系统 Python，而不是 Conda 环境

确认环境名为 pixiv_py311：

conda env list
conda run -n pixiv_py311 python -c "import sys; print(sys.executable)"

也可以把输出的解释器绝对路径填入“应用设置”。

TAG 补全出现 401 或 403

Cookie 已失效或无权访问目标内容。更新 GUI 中保存的 Cookie 后重新运行。

TAG 补全连续出现 429

任务会在连续 3 次 429 后自动停止。等待 Pixiv 限流恢复后重新运行，已有检查点会被复用。

TAG 筛选提示找不到元数据

先运行“TAG 补全”，或者确认源目录存在有效的 tags.json，并检查“应用设置”中的 中央 TAG 元数据库路径。

相似图片扫描没有复用缓存

文件大小、修改时间或指纹算法版本发生变化时会重新计算。缓存不可用时仍可扫描， 但下次运行无法复用结果。

开发与验证

npm test
conda run -n pixiv_py311 python -m unittest discover -s tests -v
conda run -n pixiv_py311 python -m compileall -q pixiv_crawler image_mix tests
conda run -n pixiv_py311 python -m pip check

上游与许可证

本项目基于原作者 CWHer 的 PixivCrawler 修改， 依照 GNU General Public License v3.0 发布。原项目及其贡献者的著作权归各自权利人所有。