⌨️ 使用教程

从「下第一张图」到「每天自动收图」,每个场景一段可复制的配置。命令与字段的完整定义见功能文档与配置手册。

准备:登录
URL 直链下载
标签搜索
排行榜与随机
小说收集
定时挂机
检查与维护
全部命令速查

准备:登录一次账号#

桌面环境(推荐) `pixivflow login`	弹出浏览器完成授权;也可以 `-u -p` 直接带账号参数。
无图形界面的服务器 `pixivflow login-headless -u 用户名 -p 密码`	两参数必填;加 `-j` 输出 JSON 方便脚本处理。
已有 refresh token `pixivflow refresh <token>`	把 token 直接写入当前配置并刷新访问令牌。

凭据写入 config/standalone.config.json 的 pixiv.refreshToken,不要提交或分享。细节见登录指南。

URL 直链下载#

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

类型自动识别,支持这十种写法:

格式	示例
插画页	`https://www.pixiv.net/artworks/{id}`
带语言前缀	`https://www.pixiv.net/en/artworks/{id}`
短链	`https://www.pixiv.net/i/{id}`
旧版插画页	`https://www.pixiv.net/member_illust.php?illust_id={id}`
小说	`https://www.pixiv.net/novel/show.php?id={id}`
小说系列	`https://www.pixiv.net/novel/series/{id}`(整部收)
用户主页	`https://www.pixiv.net/users/{uid}`(全量作品)
用户的插画 / 小说	`/users/{uid}/artworks/{id}` · `/users/{uid}/novels/{id}`
裸 ID	`123456789`(按插画处理)

临时目标不想改配置文件时,用 --targets '[{"type":"novel","tag":"アークナイツ","limit":5}]' 在命令行直接表达一个目标,仅本次执行生效。

标签搜索#

编辑 config/standalone.config.json:每日收 20 张「風景」、收藏 ≥500 的插画:

{
  "targets": [
    {
      "type": "illustration",
      "tag": "風景",
      "limit": 20,
      "minBookmarks": 500,
      "sort": "popular_desc"
    }
  ]
}

pixivflow download

进阶玩法:

多标签任一命中:"tag": "水彩厚涂" + "tagRelation": "or"(默认要求同时包含);
精确匹配标签:"searchTarget": "exact_match_for_tags",减少部分匹配带来的噪音;
日期窗口:"startDate": "2025-01-01";想永远收「昨天」,直接写占位符 "YESTERDAY"(见下一节)。

排行榜与随机#

按发布日期取候选、再在本地按热度排序——比如昨天发布的「風景」标签作品前 10 张:

{
  "type": "illustration",
  "mode": "ranking",
  "rankingMode": "day",
  "rankingDate": "YESTERDAY",
  "filterTag": "風景",
  "limit": 10
}

不设 filterTag 时才直接使用 Pixiv 榜单，此时 rankingMode 支持 day / week / month / day_male / day_female / day_ai / week_original / week_rookie 及对应 R18 榜。

换个口味——从热门结果中随机挑一张,保持每天的新鲜感:

{
  "type": "illustration",
  "tag": "オリジナル",
  "random": true
}

或者一条命令立刻来一张:pixivflow random。

小说收集#

{
  "targets": [
    { "type": "novel", "seriesId": 14690617 },
    {
      "type": "novel",
      "tag": "ファンタジー",
      "limit": 10,
      "languageFilter": "chinese"
    }
  ]
}

seriesId 收整个系列;languageFilter 为 chinese 只收中文小说(non-chinese 反之)。不足 50 字符、无法可靠判断语言的作品默认放行,避免误杀短篇。

定时挂机#

pixivflow scheduler

调度参数在配置的 scheduler 段:

{
  "scheduler": {
    "enabled": true,
    "cron": "0 3 * * *",
    "timezone": "Asia/Shanghai",
    "maxConsecutiveFailures": 5
  }
}

表达式	含义	表达式	含义
`0 3 * * *`	每天 03:00	`0 /6 * *`	每 6 小时
`30 21 * * *`	每天 21:30	`0 9 * * 1`	每周一 09:00

小技巧日期字段里的 YESTERDAY / TODAY 占位符在每次执行时替换为实际日期——配合 cron 写成「每天 03:00 收昨日新作」,配置一次永不改。服务器长期运行请交给 Docker Compose 托管。

检查与维护#

命令	用途	什么时候用
`pixivflow health`	配置完整性、目录可写性、连通性体检	部署完先跑一次;排查问题时第一步
`pixivflow status`	累计统计 + 最近下载记录	看看最近收到了什么
`pixivflow dirs`	各类文件的实际保存路径	「我的图去哪了」
`pixivflow logs`	翻最近的运行日志	定位失败原因
`pixivflow backup`	备份配置与数据库	改大配置之前手动来一发
`pixivflow maintain`	清理旧日志、优化数据库	挂机几个月后的例行保养
`pixivflow normalize`	按当前组织规则重排已有文件	换了 `*Organization` 模式之后

全部命令速查(20 个)#

分类	命令	说明
认证	`login [-u -p]`	交互式登录(浏览器授权)
	`login-headless -u -p`	无图形界面环境登录
	`refresh <token>`	注入 refresh token(别名 login-token / set-token)
下载	`download [--url\|--targets\|--config]`	执行一次下载(别名 d)
	`random`	热门标签随机一张
	`scheduler`	启动定时任务常驻进程
配置	`config`	查看 / 编辑 / 备份 / 恢复配置
	`setup`	交互式向导,首次推荐
	`migrate-config`	v1 配置路径迁移(--dry-run 可预览)
监控	`status`	统计与最近记录
	`health`	健康体检
	`logs`	查看日志
	`monitor`	实时进程监控
维护	`backup`	备份配置与数据
	`maintain`	自动清理与优化
	`normalize`	按规则归位文件
	`dirs`	显示保存位置
工具	`help [cmd]`	帮助信息
	`version`	版本号
	`webui`	启动 WebUI(:3000)

Tip不带子命令直接运行 pixivflow:配置了 scheduler.enabled=true 就启动调度器,否则执行一次下载。

↑ 回到顶部