E-Hentai Downloader 这类工具其实解决的是一个很实际的痛点当你浏览到某个画师的全套作品集或者一个几千页的图库时靠浏览器一张张右键另存为效率实在太低。手动保存不仅容易漏图还会因为文件命名混乱后期整理时痛不欲生。这个下载器就是用来批量抓取图库页面中的所有原图并按站点规则重命名、分目录保存的。这篇教程面向的是第一次接触这个工具、甚至不太熟悉命令行的新手。我会把环境准备、配置文件、cookies 获取、命令执行和典型报错这整条链路都走一遍。如果你已经用过一段时间可以直接跳到第四节看排查思路那部分内容是我在群里看到新手提问最多的地方。1. 工具认知与环境准备别急着敲命令先理解它怎么工作1.1 这个下载器到底做了什么在开始安装之前先花两分钟搞清楚工具的运行逻辑这能帮你省去后面大量的排查时间。E-Hentai Downloader 本质上是一个基于 Python 的爬虫脚本它做的事情可以拆解为四步你给它一个图库的 URL画廊页面地址不是图片直链它模拟浏览器访问该页面解析 HTML 结构提取出这个图库有多少页、每页包含多少张图片、图片的元数据标签、标题、上传时间等它再次模拟浏览器访问每个分页从分页的 HTML 中解析出原图画廊Full Image的真实图片直链然后并发下载这些直链并按预设规则保存到本地同时生成一个 metadata.json 文件记录图库信息。看清楚这个链路你就会明白工具的核心不是下载这个动作而是解析和会话保持。它需要模拟浏览器是因为 E-Hentai 的图片直链不是静态公开的而是每次访问时由服务器动态生成并且加了时效签名。这就解释了为什么你在浏览器里能直接打开图片但放到下载工具里就 403 Forbidden。1.2 安装 Python 和 Git最稳妥的环境方案这个官方版本的下载器推荐使用 Python 3.12 和 Git。Windows 用户我建议直接去 python.org 下载安装包安装时切记勾选Add Python to PATH这一项否则后面命令行会提示python不是内部或外部命令。项目推荐版本最低版本说明Python3.12.x3.10官方文档标注建议 3.12新版本依赖兼容性更好Git2.4x.x任何可用版本用于克隆仓库和后续更新操作系统Windows 10/11 或 Ubuntu 22.04任意能装 Python 的平台我主要用 Windows 演示macOS 命令同理验证环境是否装好打开终端Windows 用 CMD 或 PowerShell依次输入python --version git --version如果都正常输出了版本号恭喜环境这关过了。很多人卡在这一步是因为装了 Python 但没勾选加入 PATH或者系统里存在多个 Python 版本导致冲突。如果有多个版本建议直接用py -3.12指定版本。1.3 克隆仓库并安装项目依赖接下来把项目代码拉取到本地。找个干净的目录执行git clone https://github.com/fffonion/E-Hentai-Downloader.git cd E-Hentai-Downloader这里特别提醒一句国内网络环境下GitHub 的 clone 速度可能不稳定如果失败就多试几次或者用代理。但这里要明确说的是这篇教程只讲 E-Hentai Downloader 的正常使用流程涉及网络策略的部分请根据你自己的网络环境和当地法规自行把握。进入项目目录后安装依赖。这个项目提供了 requirements.txt直接pip install -r requirements.txt如果你是在 Windows 的 CMD 里遇到 pip 不是内部命令说明你的 Python 环境变量没配置完整。重新运行 Python 安装包选择 Modify勾选 pip 组件即可。1.4 图形界面还是命令行两种启动方式这工具其实有两套入口一个是纯命令行的ehentai.py一个是带图形界面的gui.py。终端用户用命令行就够了脚本执行效率更高配合计划任务也更方便。而图形界面适合不熟悉命令行的新手或者需要频繁查看下载进度、手动操作队列的场景。我个人的建议是不管你有没有图形界面需求先把命令行跑通因为排错、看日志、批量导入全靠命令行。图形界面只是把命令行的参数用弹窗包装了一下底层还是调用同一个核心。如果你在网络受限的服务器上跑下载任务大概率也不会有图形环境学会命令行才是根本。2. 配置文件不是摆设cookies 是下载成功的第一道门槛2.1 为什么没有 cookies 就什么都下不了这个点一定要重视因为至少有一半我明明装了但下载失败的人都是栽在 cookies 上。E-Hentai 网站对未登录访客和已登录用户展示的内容权限是不同的。更重要的是网站的图片分发服务器对未携带有效会话标识的请求会直接返回 403 或 404。E-Hentai Downloader 在下载图片时默认会用浏览器登录后的 cookies 去请求资源这样服务器才认为你是正常用户才会把原图返回给你。也就是说这工具不是一个绕过登录机制的黑客程序它只是帮你把登录后浏览器里能看到的东西批量保存下来。这一点在使用上没什么争议图库内容本身是站点允许用户访问的工具只是优化了访问效率。2.2 如何正确导出登录后的 cookies导出 cookies 这一步很多教程说得含糊我给你一个可复现的完整流程在浏览器推荐 Firefox 或 Chrome里登录 E-Hentai确保是已登录状态按 F12 打开开发者工具切到 Network网络面板刷新一下页面在请求列表里找到任意一个请求拉到请求头区域找到Cookie字段整段复制里面的内容在项目根目录找到config.ini把 cookies 粘贴到cookie 这一行后面。用 Firefox 的话也可以直接右键请求选择复制值这样不会漏字符。Chrome 需要展开请求头后手动选择复制偶尔会遇到复制不全的怪问题。示例配置片段[ehentai] cookie ipb_member_id12345; ipb_pass_hashabcdefg; skabcdef123456;注意这里 cookie 是一整行分号分隔不要换行。配置项里的逗号、分号、引号都要原样保留删掉任何一个字符都会导致后续解析失败。2.3 配置文件里每个参数是什么含义打开 config.ini你会看到不少配置项。我挑几个影响体验的做一下解释基于项目默认配置和常见实践参数作用建议值cookie登录凭证必备项浏览器中复制limit单次任务下载的页数限制0 表示不限wait_time每次请求间隔时间秒3太短容易触发风控threads并发下载线程数5~8original_image是否下载原图而非压缩图Trueuse_exhentai是否从 ExHentai 域名读取Falsesave_as文件保存命名规则保持默认第一次使用我建议就把 cookie 填好其余保持默认。跑通了之后再慢慢调整线程数、路径命名这些避免一开始优化过度反而不知道是哪一环出了问题。2.4 ExHentai 用户需要额外注意的配置有部分图库是仅在 ExHentai 展示了普通的 E-Hentai 域名下看不到。这类用户需要额外设置use_exhentai True并且 cookies 必须包含对应的站点会话。还有个容易踩的坑ExHentai 有时候会弹出“需要登录并能看到里站”的提示页。如果你发现工具下载的是一堆 HTML 而不是图片大概率是 cookies 失效或者你的账号权限本身就不足以访问这些内容。重新登录更新 cookies基本就能解决。3. 命令行操作全流程从单个图库到批量下载3.1 最基本的下载命令环境配好、cookie 填好之后先拿一个公开的小图库试水。打开终端进入项目目录执行python ehentai.py https://e-hentai.org/g/123456/abcdef/如果一切正常你会看到控制台开始输出分页解析信息、图片 URL、下载进度。等全部跑完打开项目目录下的download文件夹就能看到以图库标题命名的文件夹里面每张图片都以三位数的序号开头比如001.jpg、002.jpg。第一次运行成功后最好去检查一下文件数量和原图体积。如果文件数量明显少于图库页面标称的页数说明哪里出问题了别急着庆祝。3.2 在命令中覆盖配置文件参数配置文件是通用的但实际下载时你可能会想临时调整某些参数比如这次下载要更快一点线程调高到 16或者某个图库你只想要前 30 页。E-Hentai Downloader 支持在命令行直接覆盖配置项python ehentai.py --threads 16 --limit 30 https://e-hentai.org/g/223344/abcdef/这里的参数优先级高于 config.ini只会对本次任务生效。我经常用这种方式在批量下载时对个别图库做特殊处理不用频繁改动配置文件。常用参数还包括--download-dir E:\galleries # 指定下载目录 --wait-time 5 # 覆盖请求间隔 --original-image False # 关闭原图下载省流量3.3 批量下载的三种可行方式单本下载适合试手和一次性需求但使用下载器的人通常都有好几页收藏夹要处理。批量下载有三种思路第一种是循环命令。如果你下载地址不多可以直接在终端里连续执行python ehentai.py https://e-hentai.org/g/111/aaa/ python ehentai.py https://e-hentai.org/g/222/bbb/ python ehentai.py https://e-hentai.org/g/333/ccc/简单直接但每次都要等前一个跑完才能开始下一个效率不高。第二种是文件列表模式。很多人不知道这工具支持从文本文件读取 URL 列表。先把所有要下载的图库地址逐行存到 urls.txt 文件里然后python ehentai.py --from-file urls.txt这个模式适合几十个图库的场景脚本会按顺序逐个处理。第三种是图形界面排队。启动 GUI 版本把多个 URL 粘贴到输入框它会自动解析并加入队列。GUI 的好处是你可以看到每个任务的进度条也可以随时暂停或取消某个任务。3.4 图形界面的简单上手如果你还是觉得命令行不够友好运行一下python gui.py。界面打开后顶部有一个文本框粘贴图库链接点击 Add 就会开始解析。左侧是任务列表右侧是日志输出。GUI 适合交互但稳定性上我自己用下来还是命令行更稳。图形界面偶尔会因为系统缩放比例问题导致控件显示不全或者在高并发下载时界面卡顿。所以我通常会把 GUI 当成一个任务管理器来用真正的批量下载还是交给命令行脚本。4. 403错误、空白页与中断下载我实际踩过的坑与完整排查链路4.1 现象复现第一次批量下载就翻车以前我刚开始用这个工具时一次性往 urls.txt 里塞了 80 个图库地址启动后前两个图库下载得很顺利到第三个图库就开始大量刷 403 错误。最初以为是图库本身挂了但我用浏览器打开同一个链接图片显示正常。这个反差很气人。浏览器能开脚本却下不动。不仅 403还有一部分页面解析出来是 HTML 而不是图片链接控制台输出的全是乱码标签。当时我的第一反应是工具坏了或者版本不兼容但翻遍项目 issues 后才发现根因是我请求频率太高被服务器限流了。4.2 完整排查链路从日志到定位的思考顺序遇到问题不要急着改参数、重装环境。我先讲一个任何爬虫类工具通用的排查顺序再结合这个工具具体展开。第一步确认返回内容。不要只看报错信息要看脚本实际收到了什么。如果是 403说明服务器拒绝响应如果是 200 但内容是 HTML说明你可能拿到了一个登录页或提示页而非图片数据流。第二步检查会话状态。把 config.ini 里的 cookies 再检查一遍看是否因为清理浏览器缓存导致会话过期。这类工具的 cookie 通常有效期不长因为网站会轮换会话 ID。第三步分析请求频率。E-Hentai 对爬虫有明确的频率限制。以前社区里的经验值是普通浏览模式下单 IP 每秒请求量不要超过 1~2 次下载模式下并发线程数过高会立刻触发限流。默认线程数是 5但我实测在批量任务里线程数调到 8 以上连续跑半小时后就容易触发风控回到主页会要求输入验证码。第四步判断图库受限等级。E-Hentai 有些图库是受限内容Panda 状态访问时需要账号有相应权限且必须从 ExHentai 域名读取。你用普通域名解析时服务器会返回一个假缩略图页面或者空白页。这时候工具解析不出正确图片链接就会表现为下载失败或者文件全是 HTML。我把排查步骤整理成一张表方便对照现象直接原因深入原因处理方式报 403 Forbidden请求被拒绝cookies 失效或请求头异常重新登录网站更新 cookies大量 403 且之前正常触发频率限制线程数过高或等待时间太短降低线程数wait_time 调大到 5下载到的是 HTML 文件拿到的是页面而非图片会话不存在或图库受限、域名错误检查 use_exhentai更新 cookies下载中途中断且无报错网络波动或服务器断连读取超时调大超时参数重新运行任务下载完成但缺页分页解析漏了部分页网络延迟导致部分请求失败使用 --retry 参数或者在原目录重新运行4.3 降低频率不一定等于变慢实测线程与等待时间的平衡被限流之后我一度把所有线程数调成 1等待时间拉长到 10 秒。这样确实不会再触发风控但下载速度慢得让人崩溃一个 3000 页的图库要跑好几个小时。后来我做了几组对比测试得出一个针对普通家庭宽带的经验值线程数控制在 5 到 6 之间wait_time 设置在 3 秒左右单图库下载基本不会触发限流速度和稳定性的平衡比较理想。如果是批量下载建议把 wait_time 增加到 5并且每下载完 20 个图库暂停 1 到 2 分钟让服务器缓一缓。用配置文件表示就是threads 5 wait_time 3如果是网络环境比较差的时段比如晚高峰我偶尔也会把线程降到 3。稳是第一位的断了之后重新下载浪费的时间远大于限速省下来的时间。4.4 下载中断后别慌断点续传的机制说明E-Hentai Downloader 是有断点续传能力的但它的实现方式比较笨不是按字节断点而是按文件判断。脚本会在图库目录里建一个.download状态文件记录哪些图片已经下载成功。你重新运行同一个 URL 时它会跳过已存在的图片只补充缺失的部分。这个机制的实际体验是这样的假设一个图库 1000 页下载到第 700 页时网络断了。你直接重复执行一次下载命令它会扫描已有文件跳过前 700 页接着下载剩余 300 页。所以遇到下载中断不用清空目录重新执行一次原命令即可。唯一的坑是如果你修改了save_as命名规则会导致脚本无法识别已有的文件然后重新下载所有图片。因此中途不要更改命名规则宁可先下载完再统一用工具改名。4.5 我目前用的一个稳妥下载配置踩了一轮坑之后目前我长期使用的配置是这样的仅供参考[ehentai] cookie 每次用前都会检查是否失效 limit 0 wait_time 5 threads 6 original_image True use_exhentai False save_as 配合这个配置我从来没有再遇到过大规模 403 问题。下载 3000 页左右的大图库大概需要 1 到 1.5 小时而且全程不需要人工干预。速度虽然不是极限但我更看重睡觉时能挂机下载的稳定性。5. 下载之后的整理从原图校验到元数据管理5.1 图片完整性校验的土办法下载完成后第一步不是打开欣赏而是校验文件数量。图库详情页会显示Total Pages和Total Images对照本地文件夹里的文件数如果不一致说明有漏网的图片。最直接的命令行校验方式是ls -1 download/图库文件夹 | wc -lWindows 用户在 PowerShell 里可以用(Get-ChildItem download\图库文件夹 -File).Count如果数量对不上先用断点续传机制补漏。补了一次还缺再去检查那些缺失的序号附近是否有 403 记录针对性单独下载。5.2 metadata.json 到底有什么用每个图库下载成功后目录里会生成一个metadata.json里面记录了图库标题、标签、上传者、原图 URL 列表等信息。这个东西别删因为它是未来做图库管理的最佳信息来源。你可以在后期写个小脚本遍历所有图库目录读取 metadata.json然后生成一份总索引表格标题、页数、标签、下载时间这样成千上万个图库也有条有理。没有这个文件你只能靠文件夹名硬猜内容整理成本高得多。5.3 批量重命名的思路下载器的默认命名规则是三位数字序号加扩展名。如果你希望文件名包含更多信息比如图库标题-序号.jpg可以通过修改save_as配置实现。不过我更推荐保持默认的数字命名因为在文件夹层面已经有图库标题了文件名保持纯序号排序最清晰也方便后续用外部软件做比对去重。如果你确实依赖文件名管理收藏建议下载完成后用 PowerShell 或 Total Commander 批量重命名别在下载过程中搞得太复杂。命名规则一旦设置错误脚本解析和文件覆盖时会出现不可预期的问题。6. 站在维护者视角你不可不知的更新策略与替代方案6.1 用 Git 保持工具最新这个项目本身更新频率不算特别高但网站前端结构偶尔会调整导致解析规则失效、下载报错。如果你长时间不更新突然某天发现工具批量下载全部失败不用急着大改配置先更新仓库版本。更新命令很简单git pull origin main pip install -r requirements.txt --upgrade我建议每次大规模下载前都执行一次三条命令的时间成本很低但能避免大量无用功。6.2 如果下载器已经不能用临时替代方案说实话这个下载器也不是唯一选择。有些人直接把图库页面保存成 PDF 或使用浏览器扩展有些人用通用爬虫框架比如 Scrapy自己搭任务还有些人用脚本批量调用站点的 RSS 订阅功能来追踪更新。但论易用性和稳定性E-Hentai Downloader 在小白快速上手这个级别上仍然是最省事的。它不需要你自己写解析规则也不需要理解 HTML 结构填好 cookies 就能跑。如果你有一定爬虫基础也可以在这个项目基础上做二次开发比如自动监控收藏夹更新、下载完成后自动压缩归档。6.3 下载频率维护与服务端负载的自觉最后说点工具之外的题外话。这类下载器本质上是把站点的公开资源镜像到本地。使用它时尽量控制频率不要让脚本高并发地打扰服务器。这不仅是避免自己的 IP 被限制也是维护这个网站长期可持续运行的一种间接支持。很多人只在意能不能下却忽略了别下太猛这层。你能舒服地用这个工具是因为服务器还能正常提供服务大家都在同一个共享环境里。批量任务前先测 2 个小图库大批量任务错峰执行遇到验证码时就停一停。这些小习惯能让你和你的工具都活得久一点。