文件位置与优先级#
默认配置文件:config/standalone.config.json。实际查找顺序:
- 命令行参数
--config <path> - 环境变量
PIXIV_DOWNLOADER_CONFIG - 自动检测配置目录中的第一个可用文件
- 回退默认路径
pixivflow config # 查看/编辑/备份/恢复,不用手找文件
pixivflow setup # 交互式向导生成配置安全配置文件含 refreshToken 等认证信息,等同密码:不要提交进公开仓库,不要截图分享。JSON 里带
_ 前缀的键会被忽略,可当注释用。最小可用配置#
{
"logLevel": "info",
"scheduler": { "enabled": false },
"targets": [
{ "type": "illustration", "tag": "風景", "limit": 20 }
]
}pixiv 认证段由 login / refresh 命令自动写入,通常无需手改。
targets 下载目标#
数组,每项是一类要收集的内容,同一项内条件为 AND。按模式分组:
公共字段
| 字段 | 类型 | 说明 |
|---|---|---|
type | 必填 | illustration(插画)或 novel(小说) |
limit | number | 单次执行最多下载多少个 |
minBookmarks | number | 最低收藏数门槛 |
startDate / endDate | string | 发布日期范围 YYYY-MM-DD,支持占位符(见文末) |
搜索模式(mode: "search",默认)
| 字段 | 取值 | 说明 |
|---|---|---|
tag | string | 搜索标签;空格分隔即多标签 |
tagRelation | and / or | 多标签要求全部包含(默认)或任一命中 |
searchTarget | partial_match_for_tags / exact_match_for_tags / title_and_caption | 匹配方式 |
sort | date_desc / date_asc / popular_desc | 结果排序 |
restrict | public / private | 作品可见性范围 |
random | boolean | 从搜索结果中随机选一个下载 |
排行榜模式(mode: "ranking")
| 字段 | 说明 |
|---|---|
rankingMode | day · week · month · day_male · day_female · day_ai · week_original · week_rookie · day_r18 · day_male_r18 · day_female_r18 |
rankingDate | 日期 YYYY-MM-DD,缺省为今天;支持 YESTERDAY 占位符 |
filterTag | 设置后搜索该日期发布的 tag 作品，并在本地按热度排序；不设置时直接使用 Pixiv 榜单 |
定向 ID(跳过搜索,精确下载)
| 字段 | 适用类型 | 含义 |
|---|---|---|
illustId | illustration | 单幅插画,如 artworks/12345678 中的数字 |
novelId | novel | 单本小说,如 novel/show.php?id=26132156 |
seriesId | novel | 整个小说系列 novel/series/{id} |
userId | 两者 | 该用户的全部插画或小说 |
与 URL 直链等价——不确定时用 download --url 最省事。
小说专用
| 字段 | 说明 |
|---|---|
languageFilter | chinese 只收中文小说,non-chinese 反之;不足 50 字符无法可靠判断的作品默认放行 |
detectLanguage | 检测语言并写入元数据,默认 true |
storage 存储与目录#
| 字段 | 默认值 | 说明 |
|---|---|---|
databasePath | ./data/pixiv-downloader.db | SQLite 数据库位置 |
downloadDirectory | ./downloads | 下载根目录 |
illustrationDirectory | {根}/illustrations | 插画目录(相对或绝对路径) |
novelDirectory | {根}/novels | 小说目录 |
illustrationOrganization | flat | 插画目录组织方式,见下表 |
novelOrganization | flat | 小说目录组织方式 |
12 种目录组织模式
| 模式 | 目录结构 | 模式 | 目录结构 |
|---|---|---|---|
flat | 平铺一层 | byAuthorAndTag | 画师 → 标签 |
byAuthor | 按画师 | byDateAndAuthor | 创建月 → 画师 |
byTag | 按首个标签 | byDayAndAuthor | 创建日 → 画师 |
byDate | 按作品创建月 YYYY-MM | byDownloadDateAndAuthor | 下载月 → 画师 |
byDay | 按作品创建日 | byDownloadDayAndAuthor | 下载日 → 画师 |
byDownloadDate | 按下载月 | byDownloadDay | 按下载日 |
换组织方式后已有文件不会自动搬家。执行
pixivflow normalize 按新规则归位;pixivflow dirs 随时查看真实落盘路径。scheduler 定时任务#
| 字段 | 默认 | 说明 |
|---|---|---|
enabled | false | true 时,裸命令 pixivflow 直接进入调度器 |
cron | 0 3 * * * | 标准 cron 表达式 |
timezone | Asia/Shanghai | IANA 时区名 |
maxExecutions | 不限 | 总执行次数上限,达到即退出 |
minInterval | 0 | 两次执行最小间隔(ms),触发过密则跳过 |
timeout | 不限 | 单次任务超时(ms) |
maxConsecutiveFailures | 不限 | 连续失败 N 次后停止调度器 |
failureRetryDelay | 0 | 失败后的等待间隔(ms) |
| 常用 cron | 含义 | 常用 cron | 含义 |
|---|---|---|---|
0 3 * * * | 每天 03:00 | 0 */6 * * * | 每 6 小时 |
30 21 * * * | 每天 21:30 | 0 9 * * 1 | 每周一 09:00 |
network 网络与代理#
| 字段 | 默认 | 说明 |
|---|---|---|
timeoutMs | 30000 | API 请求超时(ms) |
retries | 3 | 失败重试次数 |
retryDelay | 1000 | 重试间隔(ms) |
proxy.* | — | enabled / host / port / protocol(http·https·socks4·socks5) / username / password |
环境变量代理未显式启用
network.proxy 时,程序自动读取 ALL_PROXY / all_proxy > HTTPS_PROXY > HTTP_PROXY(取第一个非空值),支持 http 与 socks 协议。Docker 场景下用 host.docker.internal 指向宿主机代理(Linux 用 172.17.0.1),详见部署指南。download 性能调优#
| 字段 | 默认 | 说明 |
|---|---|---|
concurrency | 3 | 并发下载数 |
requestDelay | 500 | 相邻 API 请求最小间隔(ms),防限流 |
dynamicConcurrency | true | 触发限流自动降并发 |
minConcurrency | 1 | 动态调整下限 |
maxRetries | 3 | 单文件最大重试 |
retryDelay | 2000 | 文件级重试间隔(ms) |
timeout | 60000 | 单文件下载超时(ms) |
调优建议遇到大量 429 限流时,优先加大
requestDelay 而不是堆并发——Pixiv 服务端对高频请求很敏感。环境变量覆盖#
同名环境变量优先级高于 JSON,容器部署正是基于这套机制:
| 变量 | 覆盖目标 |
|---|---|
PIXIV_REFRESH_TOKEN | pixiv.refreshToken |
PIXIV_CLIENT_ID / PIXIV_CLIENT_SECRET | OAuth 凭据 |
PIXIV_DOWNLOAD_DIR | storage.downloadDirectory |
PIXIV_DATABASE_PATH | storage.databasePath |
PIXIV_ILLUSTRATION_DIR / PIXIV_NOVEL_DIR | 类型子目录 |
PIXIV_LOG_LEVEL | logLevel(debug/info/warn/error) |
PIXIV_SCHEDULER_ENABLED | scheduler.enabled(true/false) |
PIXIV_DOWNLOADER_CONFIG | 直接指定配置文件路径 |
日期占位符#
startDate、endDate、rankingDate 支持两个占位符,每次执行时替换为实际日期:
"YESTERDAY"— 昨天(「每天收昨日新作」的推荐写法)"TODAY"— 今天
{
"type": "illustration",
"tag": "風景",
"startDate": "YESTERDAY",
"endDate": "YESTERDAY",
"limit": 30
}配合 scheduler 每天执行,「昨天的日榜 / 昨日新作」无需改配置。
更多完整组合直接抄 config/examples/:多标签 OR、中文小说过滤、昨日排行、定向下载等场景都有现成文件。