智能的 Pixiv 自动化下载工具 | Intelligent Pixiv Automation Downloader
让 Pixiv 作品收集变得优雅而高效 | Make Pixiv artwork collection elegant and efficient
🎯 PixivFlow 是一个专业的 Pixiv 批量下载工具，支持插画和小说下载、定时任务、Docker 部署。适用于个人用户和服务器自动化场景。
📖 查看完整教程文档 - 包含详细的使用教程、配置说明、部署指南和最佳实践
功能特性 • 快速开始 • 使用指南 • 配置说明 • 完整文档
PixivFlow 是一个完全独立运行的 Pixiv 作品批量下载工具，专为自动化设计。无需浏览器扩展，可在命令行或服务器上自动化运行，支持定时任务、智能去重、断点续传等功能。
作为一款专业的 Pixiv 下载器，PixivFlow 提供批量下载、URL 直接下载、定时任务、Docker 部署等核心功能，无论是个人使用还是服务器部署，都能帮助你高效地收集和管理 Pixiv 作品。
与其他 Pixiv 下载工具相比，PixivFlow 专注于自动化和服务器部署场景：
| 优势 | 说明 |
|---|---|
| 完全独立运行 | 无需浏览器扩展，纯命令行工具，可在任何环境运行（服务器、Docker、CI/CD） |
| 真正的自动化 | 设置一次，永久运行。支持 Cron 定时任务，无需人工干预 |
| 服务器友好 | 专为服务器设计，支持后台运行、进程管理、日志轮转 |
| 安全可靠 | 采用 OAuth 2.0 PKCE 标准流程，保障账号安全，避免密码泄露风险 |
| 轻量级部署 | 资源占用低，无需额外服务（如数据库、Redis），SQLite 即可 |
| 开箱即用 | 丰富的脚本工具和配置向导，3 步即可开始使用 |
- 自动化优先：设置一次，自动运行，无需人工干预
- 智能化管理：自动去重、断点续传、错误重试
- 简单易用：3 步开始使用，配置向导引导完成
- 开箱即用：丰富的脚本工具，无需记忆复杂命令
| 功能 | 说明 |
|---|---|
| 批量下载 | 支持插画和小说批量下载，可配置下载数量、筛选条件 |
| 标签搜索 | 按标签搜索作品，支持精确匹配、部分匹配等多种模式 |
| 随机下载 | 一键下载随机热门标签作品，快速体验工具功能 |
| 定时任务 | Cron 表达式配置，支持每天、每周、每月定时自动下载 |
| 智能筛选 | 按收藏数、日期范围、作品类型等多维度筛选 |
| 语言检测 | 自动检测小说语言，支持按语言过滤（仅中文/仅非中文） |
| 自动去重 | SQLite 数据库记录历史，自动跳过已下载作品 |
| 断点续传 | 下载中断后自动恢复，无需重新开始 |
| 错误处理 | 自动重试、错误恢复、智能跳过已删除/私有作品 |
| 统计报告 | 详细的运行日志和下载统计报告 |
- 完全独立：无需浏览器，纯命令行工具
- 跨平台支持：Windows / macOS / Linux，可在任何环境运行
- 轻量级：资源占用低，适合服务器长期运行
- 开源免费：GPL-3.0 许可证，可自由定制和分发
- 类型安全：TypeScript 编写，类型提示完善
- 文档完善：详细的中文文档和教程
- Node.js 18+ 和 npm 9+（推荐使用 LTS 版本：18.x, 20.x, 22.x 或 24.x）
- Pixiv 账号
- Windows 用户：推荐使用 WSL（
wsl --install）或 Git Bash - Android/Termux 用户：需要安装构建工具，详见 Termux 安装指南
Node.js 版本说明：
- 推荐使用 LTS（长期支持）版本：18.x, 20.x, 22.x 或 24.x
- 避免使用奇数版本（如 19.x, 21.x, 23.x），这些版本可能不被所有依赖包支持
- 如果看到
EBADENGINE警告，建议切换到 LTS 版本登录说明：项目默认使用 Node.js 库进行登录，无需 Python。Python gppt 仅作为后备方案（可选）。
详细指南：查看 快速开始指南
# 全局安装
npm install -g pixivflow
# 验证安装
pixivflow --help
# 登录账号
pixivflow login
# 开始下载
pixivflow download👇 也可以直接指定配置文件路径运行：
# 使用 --config 指定配置
pixivflow download --config "$(pwd)/config/standalone.config.json"
# 或使用环境变量（对所有命令生效）
export PIXIV_DOWNLOADER_CONFIG="$(pwd)/config/standalone.config.json"
pixivflow download# 1. 克隆仓库
git clone https://github.com/zoidberg-xgd/pixivflow.git
cd pixivflow
# 2. 安装依赖
npm install
# 3. 登录账号
npm run login
# 4. 开始下载
npm run download或使用一键脚本（自动完成所有设置）：
./scripts/quick-start.sh提示：
PixivFlow 提供了 WebUI 后端 API 服务，支持通过 RESTful API 和 WebSocket 进行管理：
# 启动 WebUI 后端 API 服务
pixivflow webui # 默认端口 3000
# 或使用环境变量指定端口
PORT=8080 pixivflow webui主要功能：
- 认证 API：登录、登出、Token 管理
- 配置管理 API：查看、编辑、备份、恢复配置
- 下载管理 API：启动/停止下载、查看任务状态
- 统计 API：下载统计、文件列表
- 日志 API：查看运行日志（支持 WebSocket 实时推送）
- 文件管理 API：文件列表、预览、操作
说明：
- PixivFlow 只提供后端 API，不包含前端界面
- 前端项目：现代化的 React 前端界面请查看 pixivflow-webui
- 可以通过 API 直接调用，或连接其他前端项目
- API 文档：查看 使用指南 了解详细的 API 使用方法
Docker 部署无需安装 Node.js 环境：
# 快速开始
cp config/standalone.config.example.json config/standalone.config.json
npm run login # 在主机上登录
docker-compose up -d # 启动服务详细说明：查看 Docker 使用指南 了解完整的部署方法和常见问题
推荐使用：全局安装后可直接使用
pixivflow命令，无需依赖项目目录中的脚本。
# 全局安装后使用
pixivflow login # 登录 Pixiv 账号
pixivflow download # 执行下载
pixivflow download --url <url> # 通过 URL 直接下载（支持插画/小说/系列）
pixivflow random # 随机下载
pixivflow scheduler # 启动定时任务
pixivflow normalize # 整理文件
pixivflow migrate-config # 迁移配置
pixivflow health # 健康检查（推荐）
pixivflow status # 查看下载统计和最近记录
pixivflow logs # 查看运行日志
pixivflow setup # 交互式配置向导（首次使用）
pixivflow dirs # 查看目录信息（文件保存位置）URL 下载示例：
# 下载插画
pixivflow download --url "https://www.pixiv.net/artworks/12345678"
# 下载小说
pixivflow download --url "https://www.pixiv.net/novel/show.php?id=26132156"
# 下载小说系列
pixivflow download --url "https://www.pixiv.net/novel/series/14690617"
# 下载用户的所有作品
pixivflow download --url "https://www.pixiv.net/users/123456"# 直接使用 refresh token 登录（会自动写入配置文件）
pixivflow refresh <your_refresh_token>
# 等价别名：
pixivflow login-token <your_refresh_token>
pixivflow set-token <your_refresh_token>适用于没有图形浏览器的服务器；若没有 token，可在本地运行
pixivflow login获取后复制到服务器。
pixivflow config # 配置管理（查看/编辑/备份/恢复）
pixivflow config show # 查看配置
pixivflow config set <key> <value> # 设置配置项（如：storage.downloadDirectory）
pixivflow config backup # 备份配置
pixivflow config restore # 恢复配置
pixivflow config validate # 验证配置
pixivflow config edit # 编辑配置配置设置示例：
# 设置下载目录
pixivflow config set storage.downloadDirectory ./my-downloads
# 设置插画目录
pixivflow config set storage.illustrationDirectory ./my-illustrations
# 设置小说目录
pixivflow config set storage.novelDirectory ./my-novelspixivflow monitor # 实时监控进程状态和性能指标
pixivflow maintain # 自动维护（清理日志、优化数据库等）
pixivflow backup # 自动备份配置和数据📖 详细说明：查看 脚本使用指南
PixivFlow 提供了丰富的脚本工具，所有脚本直接调用内置 CLI，性能更好、响应更快。
说明：PixivFlow 完全独立，可在任何环境运行（服务器、Docker、CI/CD）。所有功能都可通过命令行使用。
./scripts/pixiv.sh <command>| 命令 | 说明 |
|---|---|
setup |
交互式配置向导（首次必须运行） |
login |
登录 Pixiv 账号（交互式，直接调用内置CLI） |
test |
测试下载（下载少量作品验证配置） |
once |
执行一次下载 |
random |
随机下载一个热门标签作品（支持 --novel 下载小说） |
run |
启动定时任务（后台持续运行） |
stop |
停止运行的定时任务 |
status |
查看当前运行状态 |
check |
环境检查（支持 --fix 自动修复） |
update |
一键更新和修复（更新代码、依赖、修复错误） |
health |
健康检查（检查配置、网络等） 全局安装后使用: pixivflow health |
status |
查看下载统计和最近记录 全局安装后使用: pixivflow status |
logs |
查看运行日志 全局安装后使用: pixivflow logs |
config |
配置管理工具（查看/编辑/备份/恢复） 全局安装后使用: pixivflow config |
backup |
自动备份配置和数据 全局安装后使用: pixivflow backup |
maintain |
自动维护（清理日志、优化数据库等） 全局安装后使用: pixivflow maintain |
monitor |
实时监控进程状态和性能指标 全局安装后使用: pixivflow monitor |
setup |
交互式配置向导（首次使用） 全局安装后使用: pixivflow setup |
# 环境检查和修复
./scripts/pixiv.sh check --fix # 自动修复环境问题
./scripts/pixiv.sh update # 一键更新和修复📖 详细说明：查看 脚本使用指南
完整文档索引: 查看 文档导航 获取所有文档的完整列表和分类
| 文档 | 说明 |
|---|---|
| QUICKSTART | 3 分钟快速上手 - 最快开始使用 |
| LOGIN | 登录流程详解 - 登录问题解决方案 |
| USAGE | 使用指南 - 功能使用说明 |
| 文档 | 说明 |
|---|---|
| CONFIG | 配置文件使用指南 - 所有配置选项详解 |
| SCRIPTS | 脚本使用指南 - 所有脚本详细说明 |
| 文档 | 说明 |
|---|---|
| DOCKER | Docker 使用指南 - Docker 部署和使用（包含常见问题解决方案） |
| TERMUX | Termux/Android 安装指南 - Android 设备上的安装和使用 |
| 文档 | 说明 |
|---|---|
| ARCHITECTURE | 架构说明 - 项目架构和技术实现细节 |
| CLI_MIGRATION | CLI 命令移植总结 - CLI 命令迁移和功能对照 |
| CHANGELOG | 版本更新日志 |
| CONTRIBUTING | 贡献指南 |
| 场景 | 命令 | 说明 |
|---|---|---|
| 快速体验 | pixivflow random |
随机下载热门作品，快速上手 |
| 一次性下载 | pixivflow download |
按配置文件执行一次下载 |
| 定时自动化 | pixivflow scheduler |
启动定时任务，自动化收集 |
| URL 下载 | pixivflow download --url <url> |
直接下载指定作品或用户 |
💡 详细配置示例：查看 配置文件使用指南 了解各种使用场景的完整配置方法
# 首次使用 - 交互式配置向导
pixivflow setup
# 或手动编辑配置文件
pixivflow config edit{
"targets": [
{
"type": "illustration", // 内容类型：illustration 或 novel
"tag": "風景", // 搜索标签
"limit": 20, // 下载数量
"minBookmarks": 500 // 最低收藏数（可选）
}
],
"scheduler": {
"enabled": true, // 启用定时任务
"cron": "0 2 * * *" // 每天 2:00 执行
}
}📚 完整配置说明：查看 配置文件使用指南 了解所有配置选项和详细示例
- 首次使用运行
pixivflow setup进行配置 - 使用
pixivflow health检查配置和网络状态 - 定期使用
pixivflow backup备份数据
遇到问题？试试这些快速解决方案：
| 问题 | 解决方法 |
|---|---|
| 登录失败 | pixivflow login 重新登录 |
| 找不到作品 | 检查标签拼写，降低 minBookmarks 值 |
| 下载失败 | pixivflow health 检查网络和配置 |
| 定时任务异常 | pixivflow status 查看运行状态 |
📖 详细故障排除：查看 使用指南 了解完整的问题解决方案
需要服务器部署、代理配置、多任务管理等高级功能？
📖 完整指南：查看 使用指南 和 Docker 部署指南 了解详细的进阶使用方法
本项目采用 GPL-3.0-or-later 许可证开源。
这意味着：
- ✅ 可以自由使用、修改和分发
- ✅ 修改后的代码也必须开源
- ✅ 需要保留原作者信息和许可证声明
- PixivBatchDownloader - 浏览器扩展版本
- get-pixivpy-token - OAuth 认证实现参考
| 类型 | 渠道 | 说明 |
|---|---|---|
| 🐛 Bug 反馈 | GitHub Issues | 报告问题和错误 |
| 💡 功能建议 | GitHub Discussions | 提出新功能想法 |
| 📖 使用问题 | 查看文档 | 查阅完整文档 |
| ✅ 环境检查 | ./scripts/pixiv.sh health |
运行健康检查 |
| 💬 社区交流 | Discussions | 与其他用户交流 |
提问前请先：
- 🔍 查看 常见问题 章节
- 📖 阅读相关文档
- ✅ 运行健康检查
./scripts/pixiv.sh health - 📋 查看运行日志
./scripts/pixiv.sh logs
- ⚡ 启动速度：< 2 秒
- 📦 包大小：< 5 MB（不含依赖）
- 💾 内存占用：< 100 MB（运行时）
- 🔄 下载速度：支持并发下载，智能限流和动态并发调整
- 📊 数据库：SQLite，轻量级，无需额外服务
我们欢迎所有形式的贡献！无论是报告 Bug、提出功能建议，还是提交代码，都非常感谢。
- Fork 项目
- 创建特性分支 (
git checkout -b feature/AmazingFeature) - 提交更改 (
git commit -m 'Add some AmazingFeature') - 推送到分支 (
git push origin feature/AmazingFeature) - 开启 Pull Request
详细的贡献指南请查看 CONTRIBUTING.md，包含：
- 行为准则
- 开发环境设置
- 代码规范
- 提交规范
- Pull Request 流程
查看 CHANGELOG.md 了解详细的版本更新记录。
如果这个项目对你有帮助，请考虑：
- ⭐ 给项目一个 Star - 让更多人发现这个项目
- 🍴 Fork 项目 - 创建你自己的版本
- 🐛 报告 Bug - 帮助我们改进
- 💡 提出建议 - 分享你的想法
- 📢 分享给更多人 - 让更多人受益
- 💻 贡献代码 - 参与项目开发
⭐ Star on GitHub - 让更多人发现 PixivFlow！
Made with ❤️ by zoidberg-xgd
PixivFlow - 让 Pixiv 作品收集变得优雅而高效
相关链接：