🎨 PixivFlow

📖 项目介绍

PixivFlow 是一个完全独立运行的 Pixiv 作品批量下载工具，专为自动化设计。无需浏览器扩展，可在命令行或服务器上自动化运行，支持定时任务、智能去重、断点续传等功能。

为什么选择 PixivFlow？

✨ 功能特性

核心功能

🚀 快速开始

环境要求

• Node.js 18+ 和 npm 9+（推荐使用 LTS 版本）
• Pixiv 账号
• Windows 用户：推荐使用 WSL 或 Git Bash

安装方式

方式 1：从 npm 安装（推荐 ⭐）

# 全局安装
npm install -g pixivflow

# 验证安装
pixivflow --help

# 登录账号
pixivflow login

# 开始下载
pixivflow download

方式 2：从源码安装

# 1. 克隆仓库
git clone https://github.com/zoidberg-xgd/pixivflow.git
cd pixivflow

# 2. 安装依赖
npm install

# 3. 登录账号
npm run login

# 4. 开始下载
npm run download

📚 第一章：入门教程

学习目标：通过本章节，你将学会如何安装、登录和进行基础的下载操作。

1.1 基础使用

1. 登录账号

   pixivflow login

   在终端输入 Pixiv 用户名和密码，程序会自动完成登录流程并保存 refresh token。

2. 配置下载目标

   编辑配置文件 config/standalone.config.json：

   {
     "targets": [
       {
         "type": "illustration",
         "tag": "風景",
         "limit": 20
       }
     ]
   }

3. 执行下载

   方式 1：通过 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"

   这是最简单快捷的方式，无需修改配置文件，直接输入 URL 即可下载。

   支持的 URL 类型：

   • 插画：https://www.pixiv.net/artworks/{id}
   • 小说：https://www.pixiv.net/novel/show.php?id={id}
   • 小说系列：https://www.pixiv.net/novel/series/{id}
   • 用户作品：https://www.pixiv.net/users/{userId} ⭐

   方式 2：使用配置文件下载

   # 执行一次下载
   pixivflow download
   
   # 随机下载一个作品（快速体验）
   pixivflow random
   
   # 启动定时任务
   pixivflow scheduler

1.2 常用命令参考

以下是 PixivFlow 的核心命令，建议收藏备用：

📚 第二章：高级功能详解

学习目标：掌握多标签搜索、排行榜下载、小说下载等高级功能的使用方法。

2.1 多标签搜索

支持 AND 和 OR 两种标签关系：

AND 关系（默认）：作品必须同时包含所有标签

{
  "targets": [
    {
      "type": "illustration",
      "tag": "明日方舟 アークナイツ アーミヤ",
      "tagRelation": "and",
      "limit": 30,
      "searchTarget": "partial_match_for_tags"
    }
  ]
}

OR 关系：作品包含任意一个标签即可（结果会合并去重）

{
  "targets": [
    {
      "type": "illustration",
      "tag": "風景 イラスト オリジナル",
      "tagRelation": "or",
      "limit": 50,
      "searchTarget": "partial_match_for_tags",
      "sort": "popular_desc"
    }
  ],
  "download": {
    "requestDelay": 2000  // OR 模式建议增加延迟
  }
}

2.2 排行榜下载

支持多种排行榜模式，可下载日榜、周榜、月榜等：

{
  "targets": [
    {
      "type": "illustration",
      "mode": "ranking",
      "rankingMode": "day",           // 日榜
      "rankingDate": "YESTERDAY",     // 昨天（支持日期占位符）
      "limit": 100
    }
  ]
}

支持的排行榜模式：

日期占位符：支持 YESTERDAY、TODAY、LAST_7_DAYS、LAST_30_DAYS 等

2.3 单作品下载

支持通过作品ID直接下载单个插画或小说，无需搜索：

单插画下载：

{
  "targets": [
    {
      "type": "illustration",
      "tag": "single",
      "illustId": 12345678
    }
  ]
}

从 URL https://www.pixiv.net/artworks/12345678 中提取插画ID

单篇小说下载：

{
  "targets": [
    {
      "type": "novel",
      "tag": "single",
      "novelId": 26132156
    }
  ]
}

从 URL https://www.pixiv.net/novel/show.php?id=26132156 中提取小说ID

小说系列下载：

{
  "targets": [
    {
      "type": "novel",
      "seriesId": 14690617,
      "limit": 50
    }
  ]
}

从 URL https://www.pixiv.net/novel/series/14690617 中提取系列ID

下载用户的所有作品：

{
  "targets": [
    {
      "type": "illustration",
      "tag": "user",
      "userId": "123456",
      "limit": 100
    }
  ]
}

从 URL https://www.pixiv.net/users/123456 中提取用户ID

2.4 小说下载

支持小说系列、语言过滤等功能：

语言过滤（仅中文小说）：

{
  "targets": [
    {
      "type": "novel",
      "tag": "原神",
      "limit": 20,
      "languageFilter": "chinese",    // 仅中文
      "detectLanguage": true          // 启用语言检测
    }
  ]
}

支持 "chinese"（仅中文）或 "non-chinese"（仅非中文）

2.5 智能筛选

支持按收藏数、日期范围、作品类型等多维度筛选：

{
  "targets": [
    {
      "type": "illustration",
      "tag": "風景",
      "limit": 50,
      "minBookmarks": 1000,          // 最低收藏数
      "startDate": "2024-01-01",     // 开始日期
      "endDate": "2024-12-31",       // 结束日期
      "sort": "popular_desc"         // 按收藏数降序
    }
  ]
}

2.6 实际应用场景

场景 1：每日自动收集灵感素材

每天自动下载风景、插画类高质量作品作为设计素材：

{
  "targets": [
    {
      "type": "illustration",
      "tag": "風景",
      "limit": 50,
      "minBookmarks": 1000,
      "sort": "popular_desc"
    },
    {
      "type": "illustration",
      "tag": "イラスト",
      "limit": 30,
      "minBookmarks": 5000
    }
  ],
  "scheduler": {
    "enabled": true,
    "cron": "0 2 * * *",
    "timezone": "Asia/Shanghai"
  }
}

场景 2：服务器定时收集特定标签

在服务器上每周收集特定标签的热门作品：

{
  "targets": [
    {
      "type": "illustration",
      "tag": "原神",
      "limit": 100,
      "searchTarget": "partial_match_for_tags",
      "sort": "popular_desc"
    }
  ],
  "scheduler": {
    "enabled": true,
    "cron": "0 0 * * 0",
    "timezone": "Asia/Shanghai"
  }
}

场景 3：多标签 OR 搜索

从多个标签中收集作品（任意一个标签即可）：

{
  "targets": [
    {
      "type": "novel",
      "tag": "風景 イラスト オリジナル",
      "tagRelation": "or",
      "limit": 10,
      "mode": "search",
      "searchTarget": "partial_match_for_tags",
      "sort": "popular_desc"
    }
  ],
  "download": {
    "requestDelay": 2000  // OR 模式建议增加延迟
  }
}

场景 4：排行榜批量下载

每天自动下载昨天的排行榜作品：

{
  "targets": [
    {
      "type": "illustration",
      "mode": "ranking",
      "rankingMode": "day",
      "rankingDate": "YESTERDAY",
      "limit": 100
    }
  ],
  "scheduler": {
    "enabled": true,
    "cron": "0 1 * * *"  // 每天凌晨1点执行
  }
}

📚 第三章：配置详解

学习目标：深入了解所有配置选项，掌握如何优化下载性能和管理文件存储。

3.1 核心配置项

认证配置

{
  "pixiv": {
    "refreshToken": "your_refresh_token_here",
    "clientId": "MOBrBDS8blbauoSck0ZfDbtuzpyT",
    "clientSecret": "lsACyCD94FhDUtGTXi3QzcFE2uU1hqtDaKeqrdwj"
  }
}

下载目标配置

这是最重要的配置部分，定义了要下载的内容和筛选条件：

{
  "targets": [
    {
      "type": "illustration",        // illustration 或 novel
      "tag": "風景",                 // 搜索标签
      "limit": 20,                   // 下载数量限制
      "mode": "search",               // search 或 ranking
      "minBookmarks": 500,           // 最低收藏数（可选）
      "sort": "popular_desc"         // 排序方式（可选）
    }
  ]
}

3.2 定时任务配置

{
  "scheduler": {
    "enabled": true,
    "cron": "0 3 * * *",           // Cron 表达式
    "timezone": "Asia/Shanghai"     // 时区
  }
}

Cron 表达式速查

3.3 存储配置

{
  "storage": {
    "databasePath": "./data/pixiv-downloader.db",
    "downloadDirectory": "./downloads",
    "illustrationDirectory": "./downloads/illustrations",
    "novelDirectory": "./downloads/novels",
    "illustrationOrganization": "byAuthorAndTag",
    "novelOrganization": "byDateAndAuthor"
  }
}

目录组织方式：

3.4 下载性能配置

{
  "download": {
    "concurrency": 3,                    // 并发下载数（建议 1-5）
    "dynamicConcurrency": true,          // 动态并发调整（推荐启用）
    "minConcurrency": 1,                 // 最小并发数
    "requestDelay": 1000,                // 请求延迟（毫秒）
    "retries": 3,                        // 重试次数
    "timeout": 30000                     // 超时时间（毫秒）
  }
}

3.5 网络配置

{
  "network": {
    "timeoutMs": 30000,
    "retries": 3,
    "retryDelay": 1000,
    "proxy": {
      "enabled": false,
      "host": "127.0.0.1",
      "port": 7890,
      "protocol": "http"  // http, https, socks4, socks5
    }
  }
}

代理设置方式：

• 配置文件：在 network.proxy 中配置
• 环境变量：export all_proxy=socks5://127.0.0.1:6153（优先级更高）

3.6 命令行配置管理

使用命令行快速管理配置，无需手动编辑文件：

# 查看配置
pixivflow config show

# 设置配置项（会自动备份原配置）
pixivflow config set storage.downloadDirectory ./my-downloads
pixivflow config set download.concurrency 2

# 验证配置
pixivflow config validate

# 备份配置
pixivflow config backup

# 恢复配置
pixivflow config restore

# 查看目录信息
pixivflow dirs
pixivflow dirs --verbose

❓ 常见问题

登录失败？

重新运行登录命令：

pixivflow login

检查项：确认用户名密码正确、网络连接正常、代理设置正确

认证失败或 Token 过期？

pixivflow login  # 重新登录获取新 token

找不到匹配的作品？

可能原因：标签拼写错误、筛选条件过严、网络问题

解决方法：

• 尝试常见标签：イラスト、風景、art
• 降低 minBookmarks 值
• 检查网络和代理设置
• 使用 partial_match_for_tags 搜索模式，提高匹配率

下载速度慢或经常失败？

解决方法：

• 调整配置：减少 download.concurrency（1-2），增加 download.requestDelay（1000-2000ms）
• 保持 download.dynamicConcurrency: true（默认启用），系统会自动调整并发数
• 检查网络连接，必要时使用代理

定时任务没有运行？

pixivflow status    # 查看状态
pixivflow logs      # 查看日志

确保程序持续运行：

pm2 start "pixivflow scheduler" --name pixivflow
pm2 save && pm2 startup

遇到已删除或私有的作品？

这是正常现象。PixivFlow 会自动跳过这些作品并继续下载其他作品。在下载完成后会显示跳过的作品数量。

• ✅ 自动跳过已删除作品
• ✅ 自动跳过私有作品
• ✅ 自动跳过无法访问的作品
• ✅ 不会中断整个下载流程

📚 第四章：部署指南

学习目标：学会在服务器上部署 PixivFlow，实现 7x24 小时自动化运行。

4.1 Docker 部署（推荐）

使用 Docker 部署无需安装 Node.js 环境，适合服务器和生产环境：

快速开始

# 1. 准备配置文件
cp config/standalone.config.example.json config/standalone.config.json

# 2. 登录账号（在主机上）
npm run login

# 3. 启动定时任务服务
docker-compose up -d pixivflow

# 4. 查看日志
docker-compose logs -f pixivflow

使用脚本工具

# 初始化 Docker 环境
./scripts/pixiv.sh docker setup

# 登录账号
./scripts/pixiv.sh docker login

# 构建并部署
./scripts/pixiv.sh docker deploy

# 查看状态
./scripts/pixiv.sh docker status

Docker 服务说明

docker-compose.yml 提供了两个服务：

• pixivflow：定时任务服务（自动执行定时下载任务）
• pixivflow-webui：API 服务器（提供 RESTful API，可选）

4.2 服务器部署

方式 1：使用 PM2 管理（推荐）

# 安装 PM2
npm install -g pm2

# 启动定时任务
pm2 start "pixivflow scheduler" --name pixivflow

# 保存 PM2 配置
pm2 save

# 设置开机自启
pm2 startup

方式 2：使用 systemd

创建服务文件 /etc/systemd/system/pixivflow.service：

[Unit]
Description=PixivFlow Automation Downloader
After=network.target

[Service]
Type=simple
User=your-username
WorkingDirectory=/path/to/pixivflow
ExecStart=/usr/bin/node dist/index.js scheduler
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

启动服务：

sudo systemctl enable pixivflow
sudo systemctl start pixivflow
sudo systemctl status pixivflow

📚 第五章：最佳实践

学习目标：掌握 PixivFlow 的最佳使用方式，避免常见错误，提高下载效率。

5.1 配置最佳实践

• 明确配置路径：优先使用 --config <绝对路径>，或设置环境变量 PIXIV_DOWNLOADER_CONFIG
• 排行榜 + 标签的替代方案：若想"按标签抓取热门"，优先用 mode: "search" + sort: "popular_desc"
• 多标签组合：tagRelation: "and"（默认，必须同时包含所有标签）或 "or"（任意一个标签即可）
• 时间与时区：定时任务指定 timezone（如 Asia/Shanghai），避免跨时区偏差
• 登录与凭据：使用 pixivflow login --config <path> 写入 refreshToken，勿手动粘贴到仓库
• 运行前检查：执行 pixivflow health 或 pixivflow config validate，提前发现配置或网络问题
• 数据与备份：关注 storage.databasePath 与下载目录，定期备份或使用 pixivflow backup

5.2 性能优化建议

• 并发数设置：根据网络情况调整 download.concurrency，建议范围 1-5
• 启用动态并发：保持 download.dynamicConcurrency: true，自动应对速率限制
• 请求延迟：OR 模式或多标签搜索时，建议将 download.requestDelay 设置为 1500-3000ms
• 代理使用：如果遇到网络问题，配置代理可以提高下载稳定性

5.3 安全建议

• 不要分享配置文件：config/standalone.config.json 包含敏感认证信息
• 不要提交到 Git：确保配置文件在 .gitignore 中（已默认排除）
• 定期备份：使用 pixivflow backup 备份配置和数据
• 定期更新 Token：定期重新运行配置向导更新认证信息

🔗 相关链接