📖 完整教程:从安装到全自动挂机

1 · 认识 PixivFlow#

PixivFlow 做一件事:把你挑图、存图、整理、重下的循环交给程序。它是一个 npm 包,提供两种形态:

• CLI——命令行里执行下载、调度定时任务、体检维护;
• WebUI——浏览器里看统计、管任务、改配置,实时日志滚动。

底层是 Pixiv 官方 App 的 API(不是爬网页),所以需要用你的账号登录一次换取访问令牌;下载行为全部由一份 JSON 配置驱动,改需求不改代码。三种典型用法:

2 · 安装#

前置只有一样:Node.js 18+(推荐 LTS)。确认 node -v 后二选一:

# 方式 A:全局安装(推荐)
npm install -g pixivflow
pixivflow --help

# 方式 B:从源码运行
git clone https://github.com/redtidev1918/PixivFlow.git
cd PixivFlow && npm install && npm run build
node dist/index.js --help

Windows / macOS / Linux 均可;Android 用 Termux,见部署指南。

3 · 登录一次账号#

pixivflow login     # 桌面环境:弹出浏览器授权

登录成功后 refresh token 自动写入 config/standalone.config.json,之后所有命令复用,无需重复登录。没有浏览器的环境:

pixivflow login-headless -u 用户名 -p 密码   # 服务器
pixivflow refresh <refresh_token>           # 已有 token 直接注入

4 · 第一次下载#

pixivflow download --url https://www.pixiv.net/artworks/123456789

链接可以是你在 Pixiv 上复制的任何作品地址——插画、小说、小说系列、用户主页都会被自动识别并选择对应策略,甚至支持旧版短链 pixiv.net/i/{id} 和裸 ID。跑完后:

pixivflow dirs      # 查看文件实际保存位置
pixivflow status    # 看下载记录

默认布局:./downloads/illustrations(插画)、./downloads/novels(小说)、./data/(SQLite 数据库)。同一幅图重复下载会被数据库记录拦下——放心反复执行。

5 · 定义你的下载目标#

真正的生产力来自配置文件里的 targets。打开 config/standalone.config.json,从最简形态开始:

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

pixivflow download

然后按需加过滤器——每加一项都在缩小范围:

"targets": [
  {
    "type": "illustration",
    "tag": "風景",
    "limit": 20,
    "minBookmarks": 500,          # 只要有人气的
    "sort": "popular_desc",       # 按收藏数排序
    "startDate": "2025-01-01"     # 只要今年的
  }
]

字段语义与全部取值见配置参考;不想手写 JSON 就跑 pixivflow setup 向导。

6 · 进阶组合#

多标签「任一命中」

{
  "type": "illustration",
  "tag": "水彩 厚涂",
  "tagRelation": "or",      # 默认 and,要求同时含全部标签
  "limit": 30
}

排行榜模式

{
  "type": "illustration",
  "mode": "ranking",
  "rankingMode": "day",
  "rankingDate": "YESTERDAY",
  "filterTag": "オリジナル",
  "limit": 15
}

抓取昨天发布的「オリジナル」标签作品，并在本地按热度排序。不设置 filterTag 时直接使用 Pixiv 榜单，rankingMode 可选 day / week / month / R18 系列等取值。

随机与单发

pixivflow random                                   # 热门标签随机一张
pixivflow download --url "123456789"               # 裸 ID 当插画下
pixivflow download --targets '[{"type":"novel","seriesId":14690617}]'  # 临时收一部系列

小说还有整系列(seriesId)与语言过滤(languageFilter: "chinese")两个专属能力。

7 · 定时挂机#

{
  "scheduler": {
    "enabled": true,
    "cron": "0 3 * * *",
    "timezone": "Asia/Shanghai",
    "maxConsecutiveFailures": 5,
    "timeout": 3600000
  },
  "targets": [
    {
      "type": "illustration",
      "tag": "風景",
      "limit": 30,
      "startDate": "YESTERDAY",
      "endDate": "YESTERDAY"
    }
  ]
}

pixivflow scheduler

上面的组合含义:每天 03:00 收一遍「昨天发布的風景插画」。占位符 YESTERDAY / TODAY 在每次执行时替换成真实日期,所以这份配置可以永远不改。调度细节(限次、最小间隔、失败熔断)见配置参考。

8 · 文件与数据管理#

目录组织由 storage.*Organization 决定,12 种模式按画师、标签、创建日、下载日等维度归档。个人收藏推荐 byAuthor(按画师找图直觉);按时间轴欣赏选 byDownloadDay。

{
  "storage": {
    "downloadDirectory": "/data/pixiv",
    "illustrationOrganization": "byAuthorAndTag"
  }
}

• 改组织方式后:pixivflow normalize 把已有文件搬进新结构;
• 不确定文件在哪:pixivflow dirs;
• 改配置前手动备份:pixivflow backup;
• 挂机数月后:pixivflow maintain 清日志、优化数据库。

9 · WebUI 上手#

pixivflow webui     # http://localhost:3000

页面地图:

• 仪表盘——累计下载、插画/小说占比、最近动态;
• 下载——启动/停止任务、URL 直链输入框(支持批量粘贴)、断点任务恢复;
• 文件——网格预览已收作品,直接预览插画与小说文本;
• 历史——下载记录检索与导出;
• 日志——WebSocket 实时滚动;
• 配置——表单编辑器 + JSON 视图 + 历史版本回滚。

接口全部有据可查:REST 52 个端点 + logs 实时事件,见API 文档。

10 · 部署到服务器(Docker)#

git clone https://github.com/redtidev1918/PixivFlow.git && cd PixivFlow
# 前端代码需先就位(构建镜像需要 webui-frontend/)
git clone https://github.com/redtidev1918/pixivflow-webui.git webui-frontend
cp docker-env.example .env
# 编辑 .env:时区、代理;凭据二选一:
#   a) 宿主机登录后把 refreshToken 写进 config/standalone.config.json
#   b) .env 里 PIXIV_REFRESH_TOKEN=...
docker compose up -d pixivflow pixivflow-webui
docker compose logs -f pixivflow

得到:一个跑 Cron 的容器 + 一个 3000 端口的 WebUI,共享 ./downloads 与 ./data。完整的环境变量表、升级方法与排查表见部署指南。

11 · 故障排查速查#

更完整的 Q&A 在常见问题页。

12 · 下一步#

祝收藏愉快——理性下载,尊重每一位创作者。