gallery-dl 本地部署指南：一行命令从数百个图床批量扒图

一、项目介绍

在做素材收集、数据集构建、画师作品归档时，你大概率遇到过这样的麻烦：某个图站的相册有几百张图，网页上却只能一张张右键另存；换个站点，登录态、分页、反爬又各不一样。gallery-dl 就是为解决这类问题而生的命令行工具。

根据官方 README 的定义，gallery-dl 是一个命令行程序，用于从多个图片托管站点下载图库、相册与合集（支持站点清单见官方文档的 Supported Sites）。它是跨平台工具，提供了大量命令行参数与配置选项，以及强大的文件命名能力。无论是 Pixiv、Twitter/X、Instagram、DeviantArt，还是各类小众图床，只要在支持列表内，都可以用统一的方式把整个相册拉到本地。

值得注意的是，官方 README 在开头注明：项目的活跃开发已经迁移到 Codeberg，GitHub 仓库更多承担镜像与发布的作用。这并不影响普通用户使用——PyPI 上的包、预编译的可执行文件都在持续更新。

和图形化的下载器（如 IDM、迅雷）相比，gallery-dl 的优势在于"可脚本化、可批量、可复现"。你把一条命令写进脚本，下次只要运行脚本就能重新同步整个相册；而图形工具很难做到无人值守。它的配置文件还是一份可版本控制的文本——团队里每个人用同一份 gallery-dl.conf，下载目录结构、命名规则、限速策略就完全一致。对做素材站、数据采集、个人归档的人来说，这种确定性非常有价值。

二、官方信息

如果你受够了一张张右键保存，或者想把关注的画师新作品自动同步到本地，本文将带你把 gallery-dl 装好、配好，并跑出第一次批量下载。

三、项目结构与核心特性

gallery-dl 的核心思路是"一个可执行文件 + 一份配置 + 站点适配模块"。每个支持的站点背后都有一个 Python 适配器，负责解析页面、处理登录态、组织下载链接；对用户而言，这些都被隐藏在统一的命令行后面。

核心特性包括：

• 广泛的站点支持：覆盖国内外数百个图床与内容站点，新站点由社区持续补充。
• 强大的命名模板：可以用 {artist}、{title}、{num} 等占位符自由组织下载后的文件路径与文件名，例如按画师、按专辑自动分文件夹。
• 配置文件驱动：通过 gallery-dl.conf（JSON 或 YAML）持久化登录 Cookie、下载目录、限速、重试策略，避免每次都敲一长串参数。
• 可选的视频与压缩支持：配合 yt-dlp 可下载 HLS/DASH 视频流，配合 FFmpeg 可转换 Pixiv 动图（ugoira）。
• 多种安装形态：除 pip 外，还提供 Windows/Linux 独立可执行文件、Snap、Chocolatey、Docker 等，没有 Python 环境也能用。

适用场景

gallery-dl 适合三类人。第一类是创作者与素材收集者：画师、设计师需要把参考图、灵感素材按作者归档，避免网盘里一团乱。第二类是数据集构建者：做图像生成模型的人需要批量抓取公开图片集，配合命名模板可以直接得到整理好的训练目录。第三类是个人归档爱好者：把自己在各个平台发布的内容、关注的创作者的新作定期同步到本地，避免平台改版或关停丢失资料。无论哪种场景，核心都是"用一份配置长期自动同步"，而不是一次性下载。

与同类工具对比

比起通用爬虫框架，gallery-dl 把"登录、分页、解析、命名"这些麻烦事都做成了现成的站点适配器，你不必为每个站重写代码；比起浏览器插件类下载器，它能无人值守、能接定时任务、能批量处理整个用户页。它的局限也很明显：只支持已适配的站点，对完全自定义的页面无能为力。但在它支持的范围内，它是同类工具中最省心、最可复现的一个。

四、环境与版本要求

• 运行环境：Python 3.8 及以上（官方 README 明确写出的依赖项）。
• 核心依赖：Requests，pip 安装时会自动装好。
• 可选依赖（按需）：
• yt-dlp 或 youtube-dl：用于 HLS/DASH 视频下载与 ytdl 集成；
• FFmpeg：Pixiv ugoira 动图转换；
• mkvmerge：更精确的 ugoira 时间码；
• PySocks：SOCKS 代理支持；
• brotli 或 brotlicffi：Brotli 压缩响应；
• zstandard：Zstandard 压缩响应；
• PyYAML：YAML 配置文件支持；
• Jinja：Jinja 模板命名支持。

提示：如果只是下载普通图片，装好核心包即可；上述可选依赖在用到对应功能时再补。

五、本地部署步骤

方式一：pip 安装（推荐）

稳定版本发布在 PyPI，安装与升级同一条命令：

# Linux / macOS
python -m pip install -U gallery-dl

# Windows（官方建议用 py 启动器）
py -m pip install -U gallery-dl

官方还建议先升级基础打包工具，以避免兼容性问题：

python -m pip install --upgrade pip setuptools wheel

验证安装：

gallery-dl --version

方式二：独立可执行文件（无需 Python）

如果机器上没有 Python，官方提供了打包好的可执行文件（已内嵌解释器与依赖）：

• Windows：gallery-dl.exe（需安装 Microsoft Visual C++ Redistributable）；
• Linux：gallery-dl.bin。

下载地址见 Codeberg 的 Releases 页面；从 GitHub 上的 gdl-org/builds 还能拿到基于最新提交的 nightly 构建。

方式三：系统包管理器

Linux 用户可以用 Snap：

sudo snap install gallery-dl

Windows 用户若装了 Chocolatey，也可以用对应的命令安装。

下载第一个相册

最基本的用法是直接给一个相册/帖子 URL：

# 下载某个 Pixiv 作品或相册
gallery-dl "https://www.pixiv.net/en/artworks/123456789"

默认会下载到当前目录下按站点组织的文件夹里。指定输出目录：

gallery-dl --dest "./downloads/pixiv" "https://www.pixiv.net/en/users/100000"

很多站点需要登录态才能看到完整内容，这时可以通过浏览器 Cookie 导入：

# 从当前浏览器读取 Cookie
gallery-dl --cookies-from-browser chrome "https://instagram.com/某账号"

如果一切正常，终端会逐行打印正在下载的文件，最后进入目标目录即可看到按模板命名的图片。

排错思路

下载失败时，先分清是"登录态问题"还是"网络问题"。如果换浏览器手动打开同一页面能看到图，而 gallery-dl 报 403，基本就是 Cookie 没带上——重新执行 --cookies-from-browser，注意它会读取你当前浏览器的 Cookie，确保那个浏览器确实登录过目标站点。如果是部分图片 404，多半是该站点对登录用户才开放原图，配置好账号即可。

其次是命名冲突与重复下载。gallery-dl 默认跳过已存在文件，但如果命名模板里用到了可能重名的字段（例如多个作品同名），建议加上 {filename} 或 {id} 保证唯一。长期同步时，把日志输出到文件，定期查看哪些站点频繁失败，单独调整它们的限速与重试参数，能让整套归档系统稳定运行。

六、API 用法与示例

gallery-dl 本身是命令行工具，但它暴露了极为丰富的参数，可视为"可脚本化的下载 API"。

自定义命名模板：

gallery-dl \
  --dest "./素材库" \
  --filename "{artist}/{title}_{num}.{extension}" \
  "https://某个图站/album/98765"

限速与并发控制，避免被站点封 IP：

gallery-dl --limit-rate 2M --retries 5 "https://站点/相册"

把常用偏好写进配置文件 ~/.config/gallery-dl/config.json（Windows 下位于用户目录），例如：

{
  "extractor": {
    "base-directory": "./downloads",
    "destination": ["{category}"],
    "download": true
  },
  "downloader": {
    "retries": 5,
    "timeout": 30
  }
}

配合 shell 脚本或 cron，就能定期把关注的画师、账号新作品自动同步到本地，作为个人素材库或图像数据集的冷存储。完整参数与配置项见官方文档的 options 与 configuration 页面。

长期归档与防封实践

把 gallery-dl 用成"个人素材冷存储"时，有几个经验值得一提。首先是限速与并发：多数站点对高频请求不友好，建议在配置里给每个站点设置合理的限速（例如每秒 1~2 张），并把重试次数与超时调大；其次是Cookie 轮换：对需要登录的站点，定期重新导入浏览器 Cookie，避免会话过期导致批量失败。

其次是命名模板的设计。初次使用可以先跑一次 --write-info-json，把每个作品的元数据（作者、标题、日期、标签）落成 JSON，之后再调整 --filename 模板就能精确控制目录结构。例如 {category}/{artist[username]}/{filename}.{extension} 这样的模板，可以让几百个画师的作品自动分文件夹，不会混在一起。

最后是增量同步。gallery-dl 默认会跳过本地已存在的文件，配合定时任务（cron 或 Windows 计划任务）每天跑一次关注列表，就能实现"关注即自动归档"。注意遵守目标站点的服务条款，只下载自己有权获取的内容，并在公开分享前检查版权。

七、常见问题 FAQ

Q1：下载某些站点时提示需要登录或返回 403？
A：多数站点的完整内容需要登录态。使用 --cookies-from-browser <浏览器名> 从已登录的浏览器导入 Cookie，或在配置文件中为该站点填写会话 Cookie 即可；注意不要把含登录态的配置文件分享出去。

Q2：Pixiv 动图（ugoira）下载下来是一堆帧，不是动图？
A：这是因为缺少 FFmpeg。安装 FFmpeg 并确保其在 PATH 中，gallery-dl 会自动把这些帧合成动画；若要精确控制帧时间码，可再安装 mkvmerge。

Q3：下载速度很慢或经常断连？
A：使用 --limit-rate 不解决慢的问题，但配合 --retries 与超时参数可以减少中断。若网络需要代理，可通过 --proxy 或环境变量设置；安装 PySocks 后还支持 SOCKS 代理。

Q4：GitHub 上的代码还在更新吗？为什么 README 说迁移到 Codeberg？
A：活跃开发已迁至 Codeberg，GitHub 仓库更多是镜像与发版入口。普通用户无需关心代码托管在哪，直接从 PyPI 安装稳定版即可；想跑最新特性可以从 Codeberg 的 master 分支或 gdl-org/builds 的 nightly 获取。

Q5：能批量下载整个关注列表或订阅账号的所有作品吗？
A：可以。把账号主页或用户列表 URL 直接传给 gallery-dl，它会自动分页抓取；配合配置文件里的命名模板与定时任务，就能实现"关注即归档"。注意控制频率，遵守目标站点的服务条款。

小结

gallery-dl 的价值在于"一次配置、长期复用"。第一次使用时多花点时间把命名模板、Cookie、限速策略写进配置文件，之后每次同步几乎零思考。它不是那种装完即用、点一下就完事的图形软件，而是一套可以融进你自动化工作流的命令行工具——把它和定时任务、网盘同步脚本结合，就能搭出属于自己的素材归档系统。遇到不支持的站点或下载失败，先看官方文档的站点说明与 FAQ，绝大多数问题都能通过调整配置解决。把常用账号、命名模板、限速值都沉淀到版本控制的配置文件里，换机器时一条命令即可恢复整套归档环境，这正是它区别于一次性下载工具的长期价值。对需要定期备份的人来说，把它接进定时任务后，几乎可以做到"一次配置、长期自动运行"，维护成本远低于任何图形化方案。

部署后的日常使用

装好之后，gallery-dl 最常见的用法是"维护一份关注列表"。把你常逛的画师主页、专辑链接写进一个文本文件，再用 --input-file 批量喂给它，一次就能同步所有更新。配合 --dest 指定统一的素材库根目录，时间一长你就有了一个按站点、按作者自动分好类的庞大图库。日常使用中，建议把 Cookie 过期检查、失败日志汇总也写进同一个脚本，让它在后台稳定运行而不用每次手动干预。长期用下来，这份图库会成为你最可靠的灵感与素材来源。

长期使用建议

把 gallery-dl 真正用顺手的关键，是把它从"一次性工具"变成"常驻的归档服务"。建议你维护一份文本清单，把经常需要更新的画师主页、相册链接按站点分类写好，再用定时任务每天或每周跑一次；配合统一的目标目录与命名模板，几个月之后你就会拥有一个结构清晰、无需人工干预的私人图库。遇到站点改版导致下载失败时，先查官方文档对应站点的说明，多数情况更新配置或升级版本即可解决，不必重装。

相关链接

• GitHub 仓库：github.com/mikf/gallery-dl
• Codeberg 开发地：codeberg.org/mikf/gallery-dl
• 官方文档：gdl-org.github.io/docs
• 支持站点清单：gdl-org.github.io/docs/supportedsites.html
• PyPI：pypi.org/project/gallery-dl