DeviantArt Downloader

一个可靠、聚焦的 DeviantArt 下载 / 归档命令行工具。

English Documentation

更新日志见 CHANGELOG.md。

核心特性

• 官方 API（OAuth）优先：登录一次即可下载原图，无需导出 Cookie，也无需防封延时。
• URL 优先：devart-dl URL 直接下载作品 / 画廊 / 收藏夹 / 标签 / fav.me 短链。
• 下载可靠：HTTP Range 断点续传、自动重试、429 退避、HTML/空文件校验、原子落盘。
• 下载档案：--archive 用 SQLite 记住已下载内容，跨会话自动跳过。
• 路径模板：--directory / --filename 支持 {id} {title} {author} {published} {ext} 等字段，并做路径安全清洗。
• 元数据：--write-info-json 在每个作品旁写一份 .json 元数据。
• 代理与降级：支持 --proxy 与代理环境变量；未登录 OAuth 时自动回退 Cookie。

快速开始

安装

需要 Python 3.10 或更高版本。

pip install devart-dl

基本用法（URL 优先）

# 单张作品（也支持 fav.me 短链、裸 artwork id）
devart-dl https://www.deviantart.com/username/art/title-123456

# 画廊 / 作者全集
devart-dl https://www.deviantart.com/username/gallery

# 收藏夹
devart-dl https://www.deviantart.com/username/favourites

# 标签
devart-dl https://www.deviantart.com/tag/landscape

登录（推荐 OAuth）

devart-dl login oauth --client-id 你的_PUBLIC_CLIENT_ID
devart-dl whoami     # 验证登录状态
devart-dl logout     # 撤销令牌

在 deviantart.com/developers 注册一个 Public OAuth 应用，把 http://127.0.0.1:8765/callback 加入白名单。登录在浏览器中完成，无需把密码或 client_secret 交给 CLI。完整步骤见 docs/LOGIN.md。

主要功能

下载模式

URL 优先是最简单的方式；也保留显式子命令：

# URL 优先
devart-dl https://www.deviantart.com/username/art/title-123456
devart-dl https://www.deviantart.com/username/gallery
devart-dl https://www.deviantart.com/username/gallery/12345   # 指定文件夹
devart-dl https://www.deviantart.com/username/favourites
devart-dl https://www.deviantart.com/tag/landscape

# 显式子命令
devart-dl url https://www.deviantart.com/username/art/title-123456
devart-dl artist username
devart-dl gallery username [gallery_id]
devart-dl search all "digital art"
devart-dl fav username folder_id

说明：显式子命令沿用旧用法、保持兼容；官方 API 暂不提供搜索端点，search 走 Cookie 回退路径。

登录认证

官方 API（OAuth）优先，Cookie 作为降级方案。

1. OAuth 登录（推荐）

   devart-dl login oauth --client-id 你的_PUBLIC_CLIENT_ID
   

   • 注册 Public OAuth 应用，白名单精确加入 http://127.0.0.1:8765/callback。
   • 登录会在浏览器中完成，令牌保存到 ~/.deviantart_dl/oauth.json（0600），自动续期。
   • 登录后下载命令自动走官方 API，原图来自官方下载接口。

2. Cookie 登录（降级方案）

   devart-dl login interactive   # 交互式输入 Cookie
   

   或创建 cookies.txt、设置 DEVIANTART_COOKIES 环境变量。会话保存于 ~/.deviantart_dl/session.json。

下载档案与断点续传

# 用 SQLite 记住已下载内容，下次运行自动跳过（跨会话、跨目录都有效）
devart-dl https://www.deviantart.com/username/gallery --archive ~/.devart-dl/archive.sqlite

# 中断的下载从 .part 文件续传，无需重新下载整个文件

文件名 / 目录模板

devart-dl URL \
  --directory "{author}/{published:%Y-%m}" \
  --filename "{id}_{title}.{ext}"

可用字段：{id} {title} {author} {username} {published} {filename} {ext} {index}。路径会自动清洗（去除非法字符、Windows 保留名、.. 穿越、超长名），确保结果在下载目录之内。

元数据 sidecar

devart-dl URL --write-info-json
# 生成 artwork.jpg 与 artwork.json（标题、作者、URL、发布时间、mature、媒体地址等）

配置参数

常用选项

输出选项

• -v, --verbose：显示详细运行信息（含跳过原因）。
• -q, --quiet：静默模式，仅显示汇总与错误。

常用命令速查

# URL 优先（推荐）
devart-dl <URL>

# 显式子命令
devart-dl url <artwork_url>
devart-dl artist <username>
devart-dl gallery <username> [gallery_id]
devart-dl search <username|all> <query>
devart-dl fav <username> <folder_id>

# 登录 / 会话
devart-dl login oauth --client-id <ID>   # OAuth 登录（推荐）
devart-dl login interactive             # Cookie 登录（降级）
devart-dl whoami                        # 查看登录状态
devart-dl logout                        # 撤销令牌并清除本地会话

# 其他
devart-dl version

高级用法

代理设置

# 命令行参数
devart-dl URL --proxy http://127.0.0.1:7890

# 环境变量（HTTP/HTTPS 代理）
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
export ALL_PROXY=http://127.0.0.1:7890

Python 脚本调用

from pathlib import Path
from da_downloader import Downloader
from da_downloader.download import build_downloader

downloader = build_downloader(
    destination=Path('downloads'),
    archive=Path('archive.sqlite'),   # 可选：已下载自动跳过
    quality='best',                   # original / best / preview
    write_info_json=True,             # 每个作品旁写一份 metadata .json
)

results = downloader.download('https://www.deviantart.com/username/gallery')
for r in results:
    print(r.status, r.path)

已通过 devart-dl login oauth 登录时自动走官方 API，否则回退到 Cookie。

常见问题

Q: 下载不完整 / 只下了一部分 / 像是跳着下？ A: 请升级到 v3.4.0+。旧版本只下载 Featured（精选）文件夹；v3.3.1 起遍历全部画廊文件夹，v3.4.0 起解析失败与网络失败会明确报错，且中断可 Range 续传。

Q: pip 安装后运行 devart-dl 报 ModuleNotFoundError？ A: 请升级到 v3.4.0+（pip install -U devart-dl），安装入口已修复。

Q: 出现 403 Forbidden？ A: 通常是未登录或 Cookie 过期。优先 devart-dl login oauth（官方 API）；或 devart-dl login interactive 更新 Cookie。

Q: 出现 429 Too Many Requests？ A: 使用官方 API（OAuth 登录）通常不会触发；Cookie 路径下会自动退避重试，若仍频繁 429，请暂停一段时间再试。

Q: 下载速度慢？ A: 建议配置代理（--proxy），或降低画质（--quality preview）。

Q: 如何导出 Cookie？ A: 推荐 Chrome/Edge 开发者工具 (F12) → Application → Cookies，复制 auth 和 auth_secure 字段；或 devart-dl login interactive 按提示粘贴。

许可证与免责声明

本项目基于 MIT License 开源。

注意：本工具仅供个人学习和研究使用。使用者应遵守 DeviantArt 服务条款及版权规定，请勿用于商业用途或大规模抓取导致服务器过载。作者不对任何滥用后果负责。