# Taobao Images

> 批量下载淘宝店铺/商品的主图与详情图,绕过淘宝反爬(x5sec/滑块),并可跨商品剔除通用样板图。适用于把代工厂/供应商淘宝店的图片资源导入独立站(WooCommerce 等)时使用。当用户要"抓取淘宝商品图片""下载淘宝主图/详情图/SKU图""从淘宝店搬商品到独立站"时调用。

- Skill: `chaserr/taobao-images` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add chaserr/taobao-images`
- Raw SKILL.md: https://api.skillmd.com/api/skills/chaserr/taobao-images/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: chaserr (https://skillmd.com/u/chaserr)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/chaserr/taobao-images

---


# 淘宝商品图片批量下载

淘宝对 headless 浏览器、curl、服务端直连一律返回反爬拦截(x5sec / RGV587 / FAIL_SYS_USER_VALIDATE),页面爬取行不通。**可行路径**是用一次人工扫码登录拿到 cookie,再用 cookie 对淘宝 H5 的 `mtop` 接口签名调用 —— 接口返回的图片本体在 `img.alicdn.com` CDN 上,公开可直接下载。

## 核心原理

| 数据 | 接口 | 取值路径 |
|------|------|----------|
| 主图 | `mtop.taobao.detail.getdetail` v6.0,`{"itemNumId": id}` | `data.item.images` |
| 详情图 | `mtop.taobao.detail.getdesc` v6.0,`{"id": id, "type": "1"}` | 富文本里正则匹配 alicdn 图片 URL |

签名:`sign = md5("{token}&{t}&{APPKEY}&{data}")`,其中 `token` = `_m_h5_tk` cookie 的 `_` 前半段,`t` = 毫秒时间戳,`APPKEY=12574478`,`data` = 紧凑 JSON。**首次请求会下发新的 `_m_h5_tk`,脚本自动用它重签名重试**(已内置 4 次重试)。

> SKU 变体图走的是另一套受更强反爬保护的 `pcdetail` 接口,脚本不覆盖。个别商品要 SKU 图时,建议用浏览器扩展逐个抓,不要为它改脚本。

## 使用步骤

### 1. 扫码登录,导出 cookie

```bash
agent-browser --headed open "https://login.taobao.com/"
# 让用户用手机淘宝扫码。登录成功(能看到"我的淘宝")后:
agent-browser state save /path/to/tb_auth.json
```

`tb_auth.json` 含明文会话 cookie —— 放临时目录、用完删除,勿入 git。

### 2. 准备商品 ID 列表

`ids.txt`,每行一个纯数字 `itemId`(商品链接 `item.taobao.com/item.htm?id=XXXX` 里的 id)。
- 整店抓取时,先在店铺页(登录态下)用控制台抠出全部商品链接的 id。典型做法:在商品列表页 evaluate 一段 JS,收集 `a[href*="id="]` 的 id 去重。若店铺分屏懒加载,配合 computer-use 逐屏滚动读取。

### 3. 下载

```bash
python3 ~/.claude/skills/taobao-images/scripts/pipeline.py \
  --auth /path/to/tb_auth.json \
  --ids  /path/to/ids.txt \
  --out  ~/Downloads/店铺图片 \
  --sleep 1.2
```

输出:每个商品一个 `NN_{itemid}_{标题}/` 目录,内含 `主图/` 与 `详情图/`(均连续编号、原图尺寸、去重),并在根目录生成 `_商品图片索引.csv`。

### 4.(可选)剔除通用样板图

详情图里常混入"购前须知/价格声明/工厂合照/政策横幅"等跨商品重复的无关图。用内容 md5 频次识别并清理:

```bash
# 先 dry-run 看命中什么(不改动文件)
python3 ~/.claude/skills/taobao-images/scripts/dedup_boilerplate.py \
  --base ~/Downloads/店铺图片 --min-products 3
# 确认后执行: 每种样板图留一份到 _公司通用详情图/,并从各商品详情图删除+重编号
python3 ~/.claude/skills/taobao-images/scripts/dedup_boilerplate.py \
  --base ~/Downloads/店铺图片 --min-products 3 --apply
```

`--min-products N` = 出现在 ≥N 个不同商品里才算样板图,阈值越低删得越狠。删除前务必先跑一次 dry-run 让用户过目。

## 常见坑

- **cookie 里没有 `_m_h5_tk`** → 未真正登录,或 auth 文件不含淘宝域 cookie。重新扫码。
- **接口返回 `FAIL_SYS_TOKEN_EMPTY / ILLEGAL_ACCESS`** → 请求太快触发风控。调大 `--sleep`,或重新登录换新 cookie。
- **`networkidle` 在淘宝页永久挂起** → 淘宝长连接不空闲。用固定 `wait <ms>` + 截图,别用 networkidle。
- **图片名是 .jpg 但内容是 WebP** → 淘宝常见,后续入库前需按真实格式规范化后缀。

## 合规提醒(务必执行)

搬供应商图入独立站前,按品类做合规过滤,发现下列品类先标记、请用户确认,不要默认上架:
- **武器/军用件**(制导打击模块、发射装置、导弹外形机体)—— 直接排除。
- **两用管制品**(热成像机芯,尤其 640/50fps 以上)—— 需核实出口管制。
- **大功率图传 VTX**(远超欧美民用上限,如 10W)、大载重运输机 —— 核实目的地法规。
- **锂电池** —— 物流受限。

图片版权归原店铺/品牌;仅在获授权(如代工厂明确要求"用店里详情图")时使用。