如何使用 Scrapeless Scraping 浏览器构建 Etsy 爬虫：2026 年综合指南（Node.js）

mkdir etsy-scrapeless-browserless && cd etsy-scrapeless-browserless
npm init -y
npm install puppeteer-core dotenv cheerio
npm install -D tsx typescript @types/node @types/cheerio

SCRAPELESS_API_KEY=your_key_here

import "dotenv/config";
import puppeteer, { type Browser, type Page } from "puppeteer-core";
import * as cheerio from "cheerio";

// 助手 — 拉取页面的完整 HTML 并使用 cheerio 解析。调用者
// 负责首先运行任何浏览器端的滚动 / waitForFunction
// 以便懒加载区域能够被填充。之后，解析保持在 Node 中：
// 类型化，无需字符串化评估主体，无需 `__name` tsx 陷阱，易于
// 针对保存的 HTML 夹具单元测试。
async function parseWithCheerio(page: Page): Promise<cheerio.CheerioAPI> {
  const html = await page.content();
  return cheerio.load(html);
}

type ScraperInput = {
  proxyCountry: string;   // 例如 "US", "GB", "DE"
  sessionTTL: number;     // 秒，允许 60–900；600 是安全的默认值
};

function connectionURL(sessionName: string, cfg: ScraperInput): string {
  const token = process.env.SCRAPELESS_API_KEY;
  if (!token) throw new Error("SCRAPELESS_API_KEY 未在 .env 中设置");
  // 默认情况下，Scrapeless 在会话期间固定住宅 IP，
  // 因此在一次 puppeteer.connect 内部的每次页面导航使用相同的出站 IP。
  // 打开一个新会话（新连接）会分配一个新 IP，
  // 这正是重试循环依赖于此以绕过被标记的 IP。
  const qs = new URLSearchParams({
    token,
    proxyCountry: cfg.proxyCountry,
    sessionTTL: String(cfg.sessionTTL),
    sessionName,
    sessionRecording: "true",
    // 让 Scrapeless 控制整个桌面指纹 — UA、屏幕、时区
    // 和语言。无需手动设置视口 / 设置用户代理。
    fingerprint: JSON.stringify({ platform: "Windows" }),
  });
  return `wss://browser.scrapeless.com/api/v2/browser?${qs.toString()}`;
}

async function openBrowser(sessionName: string, cfg: ScraperInput): Promise<Browser> {
  return puppeteer.connect({
    browserWSEndpoint: connectionURL(sessionName, cfg),
    defaultViewport: null,
  });
}

async function prepPage(page: Page): Promise<void> {
  // 存根tsx注入的__name助手，以便page.evaluate函数体
  // 不会在浏览器上下文中崩溃，提示"__name未定义"。
  await page.evaluateOnNewDocument(
    "(function(){ globalThis.__name = function(f){ return f; }; })()",
  );
}

const ETSY_COUNTRY_PATHS: Record<string, string> = {
  US: "", DE: "de/", GB: "uk/", FR: "fr/", IT: "it/", ES: "es/",
  NL: "nl/", CA: "ca/", AU: "au/", JP: "jp/", IN: "in/",
};

async function warmUpSession(page: Page, proxyCountry: string): Promise<void> {
  const path = ETSY_COUNTRY_PATHS[proxyCountry] ?? "";
  try {
    await page.goto(`https://www.etsy.com/${path}`, {
      waitUntil: "domcontentloaded",
      timeout: 30000,
    });
  } catch {
    // 超时或网络错误都没关系——到那时Cookies已经设置好了。
  }
  await dismissEtsyConsent(page);
  await delay(1500);
}

const CONFIG: ScraperInput = {
  startUrls: [
    "https://www.etsy.com/listing/547491922/leather-walletwalletman-leather",
    "https://www.etsy.com/listing/1022283131/personalized-slim-wallet-fathers-day",
  ],
  maxProducts: 2,
  // ...其他默认设置
};

const CONFIG: ScraperInput = {
  categoryUrl: "https://www.etsy.com/c/bags-and-purses/wallets-and-money-clips/wallets",
  filters: {
    onSale: true,
    freeShipping: true,
    minPrice: 20,
    maxPrice: 60,
    orderBy: "most_relevant",
  },
  maxPagesPerQuery: 2,
  maxProducts: 20,
};

const CONFIG: ScraperInput = {
  searchQuery: "leather wallet",
  expandStrategy: "keywords",                   // "none" | "keywords" | "prices"
  expandKeywords: ["mens", "womens", "vintage"], // 在扩展为关键词时附加到基础上
  maxProducts: 20,
};

const CONFIG: ScraperInput = {
  shopUrl: "https://www.etsy.com/shop/TexasValleyLeather",
  maxPagesPerQuery: 5,
  maxProducts: 40,
};

function searchUrlForQuery(query: string, page = 1, priceMin?: number, priceMax?: number) {
  const params = new URLSearchParams({ q: query });
  if (page > 1) params.set("page", String(page));
  if (priceMin !== undefined) params.set("min", String(priceMin));
  if (priceMax !== undefined) params.set("max", String(priceMax));
  return `https://www.etsy.com/search?${params.toString()}`;
}

type ExpandStrategy = "keywords" | "prices" | "none";

function multiQueryExpand(
  base: string,
  cfg: { expandStrategy: ExpandStrategy; expandKeywords: string[]; priceBuckets: [number, number][] }
) {
  if (cfg.expandStrategy === "keywords") {
    const queries = [base, ...cfg.expandKeywords.map((k) => `${k} ${base}`)];
    return queries.map((q) => searchUrlForQuery(q));
  }
  if (cfg.expandStrategy === "prices") {
    return cfg.priceBuckets.map(([min, max]) => searchUrlForQuery(base, 1, min, max));
  }
  return [searchUrlForQuery(base)];
}

type SearchHit = { listingId: string | null; url: string; title: string | null; rank: number };
const delay = (ms: number) => new Promise((r) => setTimeout(r, ms));

async function collectSearchResults(page: Page, searchUrl: string, target: number, pageTimeoutMs = 60000): Promise<SearchHit[]> {
  await page.goto(searchUrl, { waitUntil: "domcontentloaded", timeout: 60000 });
  await dismissEtsyConsent(page);
  await delay(2000);

  // 滚动几次以触发懒加载的卡片。每次滚动都进行一次
  // cheerio 快照，以计算卡片数量 — 一旦我们
  // 拥有足够多的卡片，就停止滚动。
  for (let i = 0; i < 6; i++) {
    const $peek = await parseWithCheerio(page);
    if ($peek("[data-listing-id], div.listing-link").length >= target) break;
    await page.evaluate(() => window.scrollBy(0, 1200));
    await delay(900);
  }

  // 使用 cheerio 解析稳定的 DOM — 没有 `page.evaluate` 回合，
  // 没有字符串化的函数体，只是直接的选择器遍历。
  const $ = await parseWithCheerio(page);
  let cards = $("div.listing-link");
  if (cards.length === 0) cards = $("[data-listing-id]");
  const hits: SearchHit[] = [];
  const seen = new Set<string>();
  cards.each((_, card) => {
    const link = $(card).find('a[href*="/listing/"]').first();
    if (!link.length) return;
    const href = link.attr("href") || "";
    const absolute = href.startsWith("http") ? href : `https://www.etsy.com${href.startsWith("/") ? "" : "/"}${href}`;
    const url = absolute.split("?")[0];
    if (!url || seen.has(url)) return;
    seen.add(url);
    const titleEl = $(card).find("h3").first();
    const title = titleEl.length ? titleEl.text().trim() : (link.attr("title") || null);
    const idMatch = url.match(/\/listing\/(\d+)/);
    const listingId = idMatch ? idMatch[1] : null;
    hits.push({ listingId, url, title, rank: hits.length + 1 });
  });
  return hits;
}

const resp = await page.goto(hit.url, { waitUntil: "domcontentloaded", timeout: 60000 });
const status = resp?.status() ?? 0;
if (status === 403 || status === 429) {
  throw new Error(`被阻止: HTTP ${status} 在 ${hit.url}`);
}
await dismissEtsyConsent(page);
try {
  await page.waitForSelector("h1", { timeout: 15000 });
} catch {
  // 15秒后没有 h1 几乎总是意味着 DataDome 挑战或重定向页面。
  // 抛出异常使重试循环打开一个新会话（= 新的住宅 IP）。
  throw new Error(`在 ${hit.url} 没有 h1 — 可能是机器人挑战页面`);
}
await delay(1500);

async function extractOverview(page: Page): Promise<Partial<EtsyProduct>> {
  // 浏览器端：分块滚动以便描述 / 材料 / 运输
  // 延迟加载，然后等待购买框超出“加载”占位符后再激活。
  await page.evaluate(`(function() {
    var step = 500, total = document.body.scrollHeight, current = 0;
    var iv = setInterval(function() {
      current += step;
      window.scrollTo(0, current);
      if (current >= total) clearInterval(iv);
    }, 200);
  })()`);
  await delay(3500);

  try {
    await page.waitForFunction(
      // 等待任何合理的价格包装包含数值
      // （不是 Etsy 短暂显示的“加载”占位符）。比仅依赖购买框包装
      // 更广泛的选择网可以提高在价格首先渲染为 .currency-value
      // 的慢速商品中的命中率。
      `(function(){
        var sels = [
          "[data-selector='price-only'] span.currency-value",
          "div[data-buy-box-region='price'] span.currency-value",
          "p[class*='price'] span.currency-value",
          "span.currency-value"
        ];
        for (var i = 0; i < sels.length; i++) {
          var el = document.querySelector(sels[i]);
          if (el && /^\\s*\\$?\\d/.test((el.textContent || '').trim())) return true;
        }
        return false;
      })()`,
      { timeout: 15000 },
    );
  } catch { /* 提取器仍然尝试其下面的最好 */ }

  // Node 端：一次性拉取渲染的 HTML，并使用 cheerio 解析。
  const $ = await parseWithCheerio(page);

  const title = $("h1").first().text().trim() || null;

  // 价格 — 三步级联。 (1) 首选 Etsy 标记为当前价格的显式 `[data-selector='price-only']`
  // 子树; (2) 退而求其次，选择第一个祖先不是删除线 / 原价
  // 包装的 `span.currency-value`; (3) 最后退路，使用正文文本正则表达式。
  const isOriginalPriceWrapper = (el: any) =>
    $(el).closest("[class*='strikethrough'], [class*='original'], s, .wt-text-strikethrough").length > 0;
  let price: string | null = null;
  const priceOnly = $("[data-selector='price-only'] span.currency-value").first();
  if (priceOnly.length && /^\d/.test(priceOnly.text().trim())) {
    price = priceOnly.text().trim();
  }
  if (!price) {
    $("span.currency-value").each((_, el) => {
      if (price) return false;
      if (isOriginalPriceWrapper(el)) return;
      const t = $(el).text().trim();
      if (t && /^\d/.test(t)) price = t;
    });
  }
  if (!price) {
    const bodyPriceMatch = $("body").text().match(/(?:现在\s+)?价格:?\s*([$£€]?[\d.,]+)/i);
    if (bodyPriceMatch) price = bodyPriceMatch[1].trim();
  }

  // 评分 — 任何提到“星星”、“评分”或“满分”的 aria-label。
  let rating: number | null = null;
  $("[aria-label*='star' i], [aria-label*='rating' i]").each((_, n) => {
    if (rating !== null) return false;
    const a = $(n).attr("aria-label") || "";
    const rm = a.match(/(\d+(?:\.\d+)?)\s*(?:out|star|rating)/i);
    if (rm) rating = parseFloat(rm[1]);
  });

// 状态徽章 — 正则表达式处理页面主体。
  const bodyText = $("body").text();
  const isBestseller = /畅销书/i.test(bodyText);
  const isFreeShipping = /免运费/i.test(bodyText);
  const isStarSeller = /星级卖家/i.test(bodyText);
  const inStock = !/缺货|售罄/i.test(bodyText);

  // 商店边栏。
  const shopLink = $("a[href*='/shop/']").first();
  const shopName = shopLink.text().trim() || null;
  const shopUrl = (shopLink.attr("href") || "").split("?")[0] || null;

  return { title, _price_raw: price, rating, isBestseller, isFreeShipping, isStarSeller, inStock,
    shop: { name: shopName, url: shopUrl } } as Partial<EtsyProduct>;
}

async function extractReviews(page: Page, max: number): Promise<EtsyReview[]> {
  // 浏览器端：滚动到评论区域，以便懒加载的评论卡片能渲染出来。
  for (let i = 0; i < 8; i++) {
    const found = await page.evaluate(
      `!!document.querySelector('[data-reviews-section], div#reviews, div[class*="reviews"]')`,
    );
    if (found) break;
    await page.evaluate(() => window.scrollBy(0, 700));
    await delay(700);
  }
  await delay(1500);

  // 节点端：使用 cheerio 解析现在已经加载的页面。
  const $ = await parseWithCheerio(page);
  const out: EtsyReview[] = [];

  $(
    "div[data-review-region], div[class*='review-card'], div[class*='review-item'], li[class*='review']",
  ).each((_, card) => {
    if (out.length >= max) return false;
    const $card = $(card);
    const cardText = $card.text();
    // 跳过包含许多评论的聚合容器。
    if (cardText.length > 6000) return;

    const author = $card.find("a[href*='/people/'], strong, p[class*='name']").first().text().trim() || null;

    // 评分：首先是 `data-rating` 属性，然后是 aria-label。
    let rating: number | null = null;
    const $starEl = $card.find("[aria-label*='星' i], [data-rating]").first();
    if ($starEl.length) {
      const dr = $starEl.attr("data-rating");
      if (dr) rating = parseFloat(dr);
      else {
        const rm = ($starEl.attr("aria-label") || "").match(/(\d+(?:\.\d+)?)/);
        if (rm) rating = parseFloat(rm[1]);
      }
    }

    // 文本：专用选择器，然后卡片中的最长段落。
    let text: string | null =
      $card.find("p[class*='review-text'], div[class*='review-text'], div[id*='review-content']")
        .first().text().trim() || null;
    if (!text) {
      let longest = "";
      $card.find("p").each((_, p) => {
        const pt = $(p).text().trim();
        if (pt.length > longest.length && pt.length > 20) longest = pt;
      });
      text = longest || null;
    }

    // 日期：首先是专用元素，然后是月份名称或数字正则表达式。
    let date: string | null =
      $card.find("span[class*='date'], time, p[class*='date']").first().text().trim() || null;
    if (!date) {
      const dm = cardText.match(/(\w{3,9}\s+\d{1,2},?\s+\d{4}|\d{1,2}\/\d{1,2}\/\d{2,4})/);
      if (dm) date = dm[1];
    }

    // 子评分 — 卡片内部标记的行。匹配标签，解析相邻数字。
    const subRating = (label: string): number | null => {
      let val: number | null = null;
      $card.find("span, div, li").each((_, row) => {
        if (val !== null) return false;
        const t = $(row).text().toLowerCase();
        if (t.includes(label) && t.length < 60) {
          const sm = t.match(/(\d+(?:\.\d+)?)/);
          if (sm) val = parseFloat(sm[1]);
        }
      });
      return val;
    };

    // 评论者上传的照片 — 与商品图片相同的 `il_fullxfull` 升级。
    const photos: string[] = [];
    const photoSeen = new Set<string>();
    $card.find("img[src*='etsystatic'], img[data-src*='etsystatic']").each((_, img) => {
      if (photos.length >= 6) return false;
      let psrc = $(img).attr("src") || $(img).attr("data-src") || "";
      if (!psrc) return;

out.push({
  author, rating, text, date,
  itemQuality: subRating("物品质量"),
  shipping: subRating("运输"),
  customerService: subRating("客户服务"),
  photos,
});

四个卡片选择器的替代方案涵盖了 Etsy 正在进行的 A/B 修订 — `[data-review-region]` 是当前热门选择器；`[class*='review-card']`、`[class*='review-item']` 和 `li[class*='review']` 是旧的和新的变体，仍会根据帐户和列表出现。顶部的 cardText 长度保护跳过意外匹配的包裹元素，这些元素会将一批评论连接为一体并返回。

**图片。** Etsy 默认提供缩略图。通过替换 URL 中的大小后缀将其升级为全分辨率：`il_75x75` → `il_fullxfull`，或 `_300x300.jpg` → `_1024x1024.jpg`。同一图像，分辨率更高，无需额外请求。

```ts
async function extractImages(page: Page, max: number): Promise<string[]> {
  const $ = await parseWithCheerio(page);
  const urls: string[] = [];
  const seen = new Set<string>();
  $("img[src*='etsystatic'], img[data-src*='etsystatic']").each((_, img) => {
    if (urls.length >= max) return false;
    let src = $(img).attr("src") || $(img).attr("data-src") || "";
    if (!src) return;
    // 尽可能将缩略图大小后缀升级到全分辨率。
    src = src.replace(/il_\d+xN/, "il_fullxfull").replace(/_\d+x\d+\./, "_1024x1024.");
    if (!seen.has(src)) { seen.add(src); urls.push(src); }
  });
  return urls;
}

// 在主循环中，对每个搜索结果 h（由 i 索引）执行一次：
const MAX_ATTEMPTS = cfg.maxRetries;   // 默认值 10
let p: EtsyProduct | null = null;
let lastError: ScrapeErrorInfo | null = null;
let attemptsUsed = 0;
for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
  attemptsUsed = attempt;
  let eb;
  try {
    eb = await openBrowser(`etsy-enrich-${i}-${attempt}-${Date.now()}`, cfg);
  } catch (e: any) {
    lastError = categorizeError(new Error(`openBrowser 失败: ${e?.message ?? e}`));
    log(`    尝试 ${attempt}/${MAX_ATTEMPTS} — ${lastError.kind}: ${lastError.message.slice(0, 120)}`);
    if (!lastError.retryable) break;
    if (attempt < MAX_ATTEMPTS) await delay(Math.max(cfg.retryInitialBackoffMs, 3000));
    continue;
  }
  try {
    p = await enrichProduct(eb, h, cfg);
    if (p.title) { lastError = null; break; }
    lastError = categorizeError(new Error(`在 ${h.url} 上没有 h1 — title 为 null`));
  } catch (e: any) {
    lastError = categorizeError(e);
    log(`    尝试 ${attempt}/${MAX_ATTEMPTS} — ${lastError.kind}: ${lastError.message.slice(0, 120)}`);
    if (!lastError.retryable) break;   // 不可重试: 404 等。快速失败。
  } finally {
    await eb.close().catch(() => {});
  }
  if (attempt < MAX_ATTEMPTS) {
    // 可配置的增量退避。默认（3000、1500、500）产生
    // 尝试间隔为 5s、8s、12s、17s、23s、30s、38s、47s、57s。
    const backoff = cfg.retryInitialBackoffMs
      + attempt * (cfg.retryBackoffLinearMs + attempt * cfg.retryBackoffQuadraticMs);
    await delay(backoff);
  }
}
if (!p || !p.title) {
  p = emptyProduct(h.url);
  p.rank = h.rank;
  if (lastError) {
    p.error = { kind: lastError.kind, message: lastError.message.slice(0, 200), attempts: attemptsUsed };
  }
}
products.push(p);
// 产品间暂停（可配置）—— 打破连续的列表
// 导航，以便会话模式不会看起来像数据机器人。
if (i < hits.length - 1) await delay(cfg.interProductDelayMs);

{
  "listingId": "547491922",

const CONFIG: ScraperInput = {
  categoryUrl: "https://www.etsy.com/c/bags-and-purses/wallets-and-money-clips/wallets",
  filters: {
    onSale: true,           // → &is_on_sale=1
    freeShipping: true,     // → &free_shipping=1
    customizable: true,     // → &is_personalizable=1
    shipsTo: "US",          // → &ships_to=US (ISO国家代码)
    minPrice: 20,           // → &min=20
    maxPrice: 60,           // → &max=60
    condition: "vintage",   // "new" | "vintage" (→ &explicit=vintage)
    orderBy: "price_asc",   // "most_relevant" | "date_desc" | "price_asc" | "price_desc" | "highest_reviews"
  },
  // ...
};