E-Hentai Downloader：用户脚本实现画廊批量打包下载

1. 项目缘起与整体设计思路E-Hentai 作为一个老牌的同人志、画集与图库聚合站点很多人在浏览时都会遇到同一个痛点网页端一页一页翻着看还行但一旦想把自己喜欢的画廊保存到本地慢慢看手动右键另存为就变成了纯粹的体力活。一个几百页的画廊靠手动保存不仅耗时还容易漏页、错序文件名也乱成一团。E-Hentai Downloader 这个用户脚本就是冲着这个场景来的——它把画廊页面里的图片地址批量抓出来按顺序打包成压缩包一次性下载到本地。这个项目的核心价值可以用一句话概括把“逐页保存”变成“一键打包”。它适合三类人一是经常在 E-Hentai 上收藏画廊、希望本地留档的普通用户二是需要批量整理图集、做素材归档的内容整理者三是对用户脚本开发感兴趣、想研究“如何从网页里批量提取资源并打包”的技术爱好者。哪怕你完全不懂代码只要会装浏览器扩展、会点几下按钮也能用起来。从技术路线来看这个方案选择的是用户脚本UserScript 浏览器扩展管理器Tampermonkey 前端打包库的组合。为什么是这条路而不是写一个独立的桌面下载器或者命令行工具原因很实际E-Hentai 的图片地址是动态生成的很多画廊还带有登录态、Cookie 校验和分页加载逻辑脱离浏览器环境去抓取光是处理会话和反爬就要花掉大量精力。而用户脚本直接跑在已经登录、已经加载好页面的浏览器里天然复用了当前的会话状态省掉了最麻烦的一环。Tampermonkey 负责脚本的注入和生命周期管理打包环节则交给前端成熟的 ZIP 库在浏览器内存里完成最后触发一次 Blob 下载。整条链路都在浏览器内闭环不需要额外装服务端也不需要配置复杂的运行环境。这个设计还有一个隐性优势跨平台。不管你是 Windows、macOS 还是 Linux只要浏览器能装 Tampermonkey脚本就能跑。对比那些需要单独编译、依赖特定运行时的桌面工具用户脚本的分发和更新成本低得多——作者改一版用户下次打开页面自动就是最新的。提示用户脚本运行在浏览器沙箱里权限受浏览器管控安装前务必确认脚本来源可信避免引入来路不明的第三方修改版。2. 核心细节解析与实操要点2.1 用户脚本到底做了什么很多人以为“下载器”就是简单地把图片链接列出来其实远不止。一个能用的 E-Hentai 下载脚本内部至少要完成四件事解析画廊页面结构、提取每一页的真实图片地址、按页序请求图片数据、把二进制数据打包成 ZIP。这四步里第一步和第二步是最容易出问题的因为 E-Hentai 的页面结构会变缩略图地址和原图地址也不是一回事。脚本通常会在页面上注入一个操作面板里面有几个关键选项下载范围全部页还是指定区间、图片质量原图还是重新采样、并发数量、是否保留原始文件名。这些选项背后对应的是不同的请求策略。比如选“原图”脚本就要去请求每张图的原始地址流量大、耗时长选“重新采样”地址规则不同速度更快但画质有损。并发数量则直接决定了下载速度和对站点的压力设太高容易被限流设太低又慢得让人抓狂。2.2 Tampermonkey 的安装与脚本注入Tampermonkey 是这一切的地基。它本质上是一个浏览器扩展负责识别网页、匹配脚本的match规则、在页面加载时把脚本代码注入进去。安装流程本身不复杂但有几个细节值得说清楚。在 Chrome 或 Edge 上从官方扩展商店搜索 Tampermonkey 安装即可。装完之后浏览器工具栏会出现一个图标点开能看到“添加新脚本”的入口。这时候你有两种方式引入 E-Hentai Downloader一种是从脚本托管平台直接点“安装”Tampermonkey 会自动识别并弹出安装确认页另一种是手动把脚本代码复制进“添加新脚本”的编辑器里保存。前者更省事后者适合你想自己改代码的情况。安装确认页会列出脚本申请的权限比如grant、connect这些。connect尤其要注意它声明了脚本可以请求哪些域名。如果脚本需要从图片服务器拉数据就必须在connect里列出对应域名否则浏览器的跨域策略会直接拦掉请求。这是新手最容易踩的坑之一——脚本装上了面板也出来了但一点下载就报错八成就是connect没配对。2.3 关于 git clone 与本地部署的取舍热词里出现了git clone、git clone 断点续传、git clone怎么继续这些说明有一部分用户走的是“把脚本源码克隆到本地再自己构建”的路线。这条路适合想深度定制或者参与开发的人但对普通用户来说其实没必要。如果你确实要克隆仓库标准命令是git clone https://github.com/xxx/E-Hentai-Downloader.git网络不稳定导致中断时可以进到已经克隆了一半的目录里执行git fetch --all git reset --hard origin/main或者用浅克隆减少数据量git clone --depth 1 https://github.com/xxx/E-Hentai-Downloader.git--depth 1只拉最近一次提交速度会快很多代价是看不到完整历史。对于只想拿最新代码用的人来说这个取舍完全值得。至于热词里提到的post-checkout hook found during git clone报错通常是本地 Git 配置里残留了钩子脚本检查.git/hooks/目录把可疑的post-checkout文件清掉再重试即可。注意克隆下来的源码往往需要构建比如打包成单文件用户脚本才能用直接拿源码当脚本装进 Tampermonkey 可能跑不起来。普通用户建议直接用发布好的成品脚本。2.4 ZIP 打包与密码移除的常见困惑热词里zip密码移除、zip伪加密、base64 加密zip、jpg文件怎么改成zip这些词扎堆出现说明很多人在下载完成后卡在了“压缩包打不开”这一步。这里要分几种情况说。第一种是伪加密。有些 ZIP 文件在文件头里标记了“已加密”但实际上数据段并没有真正加密用普通解压工具会提示要密码。这种情况可以用十六进制编辑器把加密标志位改回去或者用支持忽略伪加密的工具直接解。第二种是真加密那就必须拿到密码没有捷径。第三种是文件扩展名被改过比如把.jpg改成.zip想骗过某些检测这种改回来就行但要注意文件本身是否完整。E-Hentai Downloader 生成的压缩包默认是不加密的如果你下下来的包提示要密码先确认是不是下载过程中被中间环节动过手脚或者是不是下到了别人二次打包的版本。3. 实操过程与核心环节实现3.1 从零开始的完整操作流程假设你现在什么都没装我们从头走一遍。第一步装 Tampermonkey。打开浏览器扩展商店搜索安装装完确认工具栏图标出现。第二步获取 E-Hentai Downloader 脚本。从可信的脚本发布页点击安装Tampermonkey 弹出确认页后点“安装”。第三步打开任意一个 E-Hentai 画廊页面。如果脚本生效页面侧边或顶部会出现一个下载面板。第四步在面板里设置参数选择下载范围、图片质量、并发数然后点“开始下载”。第五步等待脚本逐页抓取并打包完成后浏览器会自动弹出保存对话框选个目录存下来即可。整个过程听起来简单但每一步都有变量。比如第三步面板没出现可能是脚本的match规则没覆盖你当前访问的域名变体第四步点了没反应可能是connect缺了图片服务器域名第五步卡在打包阶段可能是画廊页数太多、内存吃紧。3.2 关键参数的选择与计算并发数是最值得展开讲的参数。假设一个画廊有 200 页每张图平均 500KB总数据量约 100MB。如果并发数是 1也就是一张一张顺序下载按每张图请求加传输 1 秒算总共要 200 秒。如果并发数提到 5理论上能压到 40 秒左右但实际不会这么线性因为站点有速率限制浏览器也有单域名并发连接数上限通常是 6 个左右。所以并发数设到 4 到 6 之间是比较稳妥的区间。再高收益递减不说还容易触发站点的限流机制导致部分请求返回错误最后打包出来的压缩包里缺页。我自己的习惯是设 4牺牲一点速度换稳定性。如果你网络环境好、站点响应快可以试 6但一定要检查下载完成后的页数是否和画廊总页数一致。图片质量的选择则是个权衡。原图体积大、清晰度高适合收藏重新采样体积小、速度快适合快速浏览。如果你只是想过一遍内容选重新采样能省下大量时间和流量。3.3 打包环节的内部逻辑脚本把图片数据抓下来之后并不是直接丢给浏览器下载而是先在内存里组装成一个 ZIP 结构。ZIP 格式的本质是一系列“本地文件头 文件数据 中央目录”的拼接。脚本会为每张图片创建一个条目写入文件名通常是页码加扩展名、压缩方式图片本身已经是压缩格式所以一般用“存储”模式不再二次压缩、以及数据本身。所有条目写完后再写中央目录最后整体作为一个 Blob 交给浏览器。这里有个细节图片用“存储”模式而不是“压缩”模式是因为 JPEG、PNG 这些格式本身已经压缩过了再用 DEFLATE 压一遍几乎不会变小反而白白消耗 CPU 时间。一个几百页的包如果每张图都走一遍压缩算法打包阶段能多花好几分钟。所以成熟的脚本都会对图片类文件跳过压缩。3.4 下载后的文件整理下载下来的 ZIP 解压后文件名通常是页码序列比如001.jpg、002.jpg。如果你要长期归档建议按“画廊标题/页码”的层级整理方便以后检索。有些脚本支持自定义文件名模板比如带上画廊标题和页码这样解压出来就是可读的名字省去手动重命名的功夫。提示解压时如果遇到文件名乱码多半是 ZIP 里的文件名编码和系统默认编码不一致。用支持指定编码的解压工具比如 7-Zip 里手动选 UTF-8通常能解决。4. 常见问题与排查技巧实录4.1 脚本不生效的排查顺序面板不出现是最常见的问题。排查要按顺序来别乱试。先确认 Tampermonkey 图标上有没有数字角标有角标说明当前页面匹配到了脚本。如果没有角标说明match规则没覆盖当前页面可能是域名变了或者路径规则太严。如果有角标但面板没出来打开浏览器控制台看有没有报错常见的是脚本依赖的某个库没加载成功或者被其他扩展拦截了。还有一种情况是浏览器版本太新Tampermonkey 的某些 API 行为变了导致脚本注入时机不对。这时候可以试试在 Tampermonkey 设置里调整脚本的运行时机run-at从document-idle改成document-end或者反过来。4.2 下载中断与缺页处理下载到一半断了或者打包出来的包页数不对原因通常有三类网络波动、站点限流、内存不足。网络波动导致的失败重试往往就能过站点限流的话把并发数降下来、加长请求间隔内存不足则出现在超大画廊上浏览器标签页的内存被撑爆这时候只能分批下载比如先下前 100 页再下后 100 页。判断是不是限流可以看控制台里的请求状态码。如果大量出现 429 或者 503基本就是被限了。这时候别硬刚停一会儿再继续或者把并发降到 2 以下慢慢磨。4.3 常见问题速查表问题现象可能原因解决方向面板不出现match未覆盖 / 脚本未注入检查角标、控制台报错点击下载无反应connect缺域名 / 跨域被拦补全connect配置下载中途报错网络波动 / 站点限流降并发、重试、分批压缩包提示要密码伪加密 / 二次打包换解压工具、核对来源解压后文件名乱码编码不一致指定 UTF-8 解压页数对不上部分请求失败核对总页数、重下缺失部分打包阶段卡死内存不足分批下载、关闭其他标签页4.4 几个我踩过的坑第一个坑是盲目追求高并发。刚开始用的时候觉得并发拉满才爽结果下到一半一堆请求失败最后包里缺了十几页还得重新对页码补。后来老老实实设 4反而一次过。第二个坑是忽略connect。有次换了个脚本版本作者更新了图片服务器域名但没在说明里写清楚我装上一跑就报跨域错误。打开脚本源码一看connect里还是旧域名手动补上新的就好了。所以装脚本前扫一眼connect列表是个好习惯。第三个坑是拿源码直接当脚本用。有次图省事把克隆下来的源码文件直接拖进 Tampermonkey结果各种模块导入报错。后来才明白源码是模块化的得先构建打包成单文件才能用。普通用户真没必要折腾这一步直接用发布版最省心。4.5 关于安全与合规的提醒用户脚本的权限不小它能读取你当前页面的内容、能发起网络请求。所以来源一定要认准别随便装来路不明的修改版。装之前看看脚本的权限声明如果一个小下载脚本申请了一堆跟下载无关的权限那就得警惕。另外下载下来的内容请自行妥善保管和使用遵守相关平台的使用条款。5. 进阶玩法与效率提升5.1 批量处理多个画廊单个画廊下载熟练之后自然会想批量处理。有些脚本支持“队列”模式你可以把多个画廊页面依次加入队列脚本按顺序一个个下。这个功能的实现思路是维护一个任务列表每个任务记录画廊地址和参数然后串行执行。串行而不是并行是为了避免同时打开太多标签页把内存吃光。如果你用的脚本没有队列功能也可以手动来开几个标签页每个页面都触发下载但注意别同时开太多浏览器扛不住。5.2 自定义文件名与目录结构默认的页码命名在画廊多了之后很难管理。进阶做法是改脚本里的文件名生成逻辑把画廊标题、作者、页码组合成有意义的路径。比如作者名/画廊标题/001.jpg。这样解压出来直接就是整理好的目录树省去后期归类的时间。改的时候注意文件名里不能包含系统不允许的字符比如 Windows 下的\ / : * ? |脚本一般会做替换处理你自己改的话别忘了这一步。5.3 与其他工具的配合下载只是第一步后续可能还涉及格式转换、去重、生成缩略图索引等。这些可以交给专门的工具做。比如用图片管理软件建立图库索引用去重工具清理重复下载的内容。把下载和整理拆成两个独立环节各用各的专长工具整体效率比指望一个脚本包办所有事要高得多。5.4 脚本更新与维护E-Hentai 的页面结构不是一成不变的站点改版之后脚本往往需要跟着更新。Tampermonkey 支持自动检查脚本更新建议保持开启。如果某天突然不好用了先去脚本发布页看看有没有新版本八成是作者已经跟进修复了。自己改过代码的话更新前记得备份免得覆盖掉你的定制逻辑。6. 我个人在实际操作中的几点体会用了这么久最大的体会是工具的价值在于稳定而不是功能多。一个并发设 4、老老实实顺序抓取、打包不压缩的“笨”脚本实际体验往往比那些堆了一堆花哨功能、动不动就崩的脚本好得多。下载这种事一次成功比十次炫技重要。另外别把下载和整理混在一起做。下载的时候专心下载下完再统一整理。边下边整理注意力被切来切去反而容易出错。我现在的流程就是脚本下完解压到一个临时目录确认页数完整再按自己的归档规则挪到正式目录。多这一步确认能省掉后面很多返工的麻烦。最后分享一个小技巧如果你经常下同一类型的画廊可以把常用的参数组合存成脚本里的预设省得每次都要重新调。改一次代码后面每次打开都是你习惯的配置这种一次投入长期受益的事值得花那十分钟。