مقدمه
در این راهنمای عملی یاد میگیرید چگونه با Cheerio در محیط Node.js صفحات HTML را بارگذاری، پرسوجو و دادهها را استخراج کنید؛ از نصب و خواندن فایلهای محلی یا درخواست HTTP گرفته تا نمونهی کامل یک اسکریپر که خروجی JSON تولید میکند. مخاطب فرضی این مقاله توسعهدهندهی پایتون/Node در سطح متوسط است که دنبال جزئیات پیادهسازی، مدیریت خطا و نکات عملی برای تولید اسکریپر پایدار است.
چرا از Cheerio برای وب اسکریپینگ استفاده کنیم
- سینتکس آشنا و شبیه jQuery که انتخاب با CSS selector را ساده میکند.
- کار بر روی سرور: اجرا در محیط Node.js بدون نیاز به مرورگرِ واقعی (سرعت و سبکی).
- مناسب برای صفحات ایستا (static HTML) و پردازش سریع چند صد یا چند هزار صفحه کوچک.
- قابل گسترش: میتوانید منطق سفارشی جاوااسکریپت را روی درخت پارسشده پیاده کنید.
نکته: Cheerio جاوااسکریپتِ سمت کلاینت را اجرا نمیکند؛ برای صفحات داینامیک باید از راهکارهای جایگزین استفاده کنید.
نصب و راهاندازی
مراحل پایهای برای شروع:
mkdir web-scraping
cd web-scraping
npm init -y
npm install cheerio axiosتوضیح: با npm init -y یک package.json پایه ساخته میشود. اگر میخواهید از import/export استفاده کنید، مقدار "type":"module" را در فایل package.json قرار دهید.
بارگذاری HTML — از وب و از فایل
دو منبع اصلی HTML عبارتند از درخواست HTTP و فایل محلی. در هر دو حالت خروجی یک رشته HTML است که به cheerio.load پاس میدهیم تا تابع انتخابگر $ را بدست آوریم.
مثال: گرفتن HTML از وب با axios (با مدیریت خطا و هدر)
import * as cheerio from 'cheerio'
import axios from 'axios'
async function fetchHtml(url) {
try {
const response = await axios.get(url, {
headers: { 'User-Agent': 'Mozilla/5.0 (compatible; MyScraper/1.0)'} ,
timeout: 10000
})
const html = response.data // خروجی: رشتهٔ HTML
return cheerio.load(html) // بازگشت: تابع انتخابگر $
} catch (err) {
console.error('fetchHtml error:', err.message)
throw err
}
}
توضیح خطبهخط: ورودی تابع fetchHtml یک url است؛ خروجی تابع یک تابع انتخابگر $ است که روی آن میتوان عملیات جستجو/تغییر انجام داد. ما هدر User-Agent و timeout تعیین کردیم تا رفتار قابلپیشبینیتری داشته باشیم.
خواندن از فایل محلی با fs/promises:
import * as cheerio from 'cheerio'
import fs from 'fs/promises'
async function loadFromFile(path) {
const html = await fs.readFile(path, 'utf8') // ورودی: مسیر فایل، خروجی: رشتهٔ HTML
return cheerio.load(html)
}
پرسوجو و انتخاب عناصر (Querying DOM)
پس از بارگذاری HTML، از تابع $ مانند jQuery استفاده میکنیم. روشهای رایج: text(), attr(), each().
const $ = cheerio.load('Example ')
const title = $('title').text() // خروجی: متن داخل تگ title
// پیمایش لینکها
$('a').each((i, el) => {
const href = $(el).attr('href') // آدرس
const text = $(el).text() // متن لینک
console.log(i, text, href)
})
نکته: each آرگومانهای index و element را میگیرد؛ برای دسترسی دوباره به متدهای Cheerio باید عنصر را با $(element) بستهبندی کنید.
پیمایش درخت DOM (Traversing)
برای جابجایی در ساختار از متدهایی مثل find, children, parent, parents, next, prev استفاده کنید. این متدها ترکیبپذیرند و انعطاف بالایی در استخراج ساختار پیچیده میدهند.
// پیدا کردن همهٔ های داخل یک کانتِینر
const $container = $('.container')
const paragraphs = $container.find('p')
paragraphs.each((i, p) => console.log($(p).text()))
// گرفتن والد مستقیم
const parentClass = $('.some-child').parent().attr('class')
مثالهای بالا ورودی را میگیرند (انتخابگر یا عنصر) و خروجی معمولاً یک مجموعهٔ Cheerio است که میتوانید روی آن each اجرا کرده و دادهها را جمعآوری کنید.
استخراج با Regex و فیلتر عناصر
برای استخراج الگوهای متنی مانند ایمیل یا شماره تلفن میتوانید از regex در ترکیب با text() یا html() استفاده کنید.
const emails = []
$('li').each((i, el) => {
const text = $(el).text()
const m = text.match(/\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/)
if (m) emails.push(m[0])
})
برای فیلتر کردن مجموعهها از filter() و برای معکوس کردن شرطها از not() استفاده کنید.
دستکاری DOM (Manipulation)
Cheerio علاوه بر خواندن میتواند DOM را بهصورت برنامهای تغییر دهد: صفتها، کلاسها، متن یا ساختار HTML را ویرایش کنید.
const $ = cheerio.load('link')
const $a = $('a')
$a.attr('href', 'https://nodejs.org') // تغییر attribute
$a.prop('target', '_self') // تغییر property
$a.text('Node.js') // تغییر متن
خروجی این تغییرات را میتوانید با prop('outerHTML') یا html() مشاهده کنید.
نمونه پروژه: اسکرپر Quotes (خروجی JSON)
مثال کامل که همهٔ مفاهیم بالا را جمع میکند: دریافت صفحه، انتخاب بلوکهای نقلقول، استخراج متن، نویسنده و تگها، و تولید آرایهٔ JSON.
import * as cheerio from 'cheerio'
import axios from 'axios'
async function scrapeQuotes(url) {
// ورودی: url (رشته)، خروجی: آرایهٔ اشیاء
const res = await axios.get(url, { timeout: 10000 })
const $ = cheerio.load(res.data)
const quotes = []
$('div.quote').each((i, block) => {
const quoteText = $(block).find('span.text').text().trim()
const author = $(block).find('small.author').text().trim()
const tags = []
$(block).find('a.tag').each((j, t) => tags.push($(t).text().trim()))
quotes.push({ No: i + 1, Quote: quoteText, Author: author, tags })
})
return quotes // خروجی: [{No, Quote, Author, tags}, ...]
}
// استفاده
scrapeQuotes('https://quotes.toscrape.com')
.then(data => console.log(JSON.stringify(data, null, 2)))
.catch(err => console.error('scrape error', err.message))
توضیح: تابع scrapeQuotes یک درخواست HTTP انجام میدهد، درخت DOM را با Cheerio میسازد و سپس بهصورت مرحلهای بلوکهای div.quote را پردازش میکند. خروجی مناسب برای ذخیره در فایل JSON یا تبدیل به CSV است.
ملاحظات فنی و بهترینروشها
- مدیریت خطا: همیشه try/catch یا promise.catch داشته باشید و برای خطاهای قابل بازگشت (retryable) مکانیزم تکرار (exponential backoff) پیاده کنید.
- هدرها و زمانبندی: هدر User-Agent، کوکیهای لازم و محدودیت نرخ (rate limit) را رعایت کنید.
- مصرف حافظه: Cheerio کل HTML را در حافظه میسازد؛ برای صفحات بسیار بزرگ یا تعداد زیاد صفحات از صفبندی (queue) با محدودیت concurrency استفاده کنید.
- همزمانی: از محدودیت همزمانی (مثلاً پکیجهایی مثل p-limit یا یک worker pool ساده) برای جلوگیری از مصرف بیش از حد منابع و بلاک شدن استفاده کنید.
- امنیت و اخلاق: قانون مالکیت داده، robots.txt و قوانین API سایتها را رعایت کنید؛ از جمعآوری دادههای حساس خودداری کنید.
- مقابله با بلاک: برای عبور از مکانیزمهای سادهٔ بلاکینگ از پراکسی، گردش IP، و تغییر User-Agent استفاده کنید، اما از روشهای غیرقانونی یا دورزدن قوانین سایت استفاده نکنید.
محدودیتها و جایگزینها
محدودیت اصلی Cheerio این است که جاوااسکریپت اجرا نمیشود؛ اگر نیاز به رندر یا تعامل (کلیک، اسکرول) دارید از ابزارهای زیر استفاده کنید:
- Puppeteer / Playwright: مرورگر واقعی برای صفحات داینامیک و تعاملات پیچیده.
- jsdom: شبیهسازی محیط DOM با امکان اجرای بعضی از اسکریپتها.
- htmlparser2 و parse5: کتابخانههای پارسینگ سبک و سریع برای نیازهای سفارشی.
جمعبندی
Cheerio ابزار قدرتمندی برای وب اسکریپینگ صفحات ایستا در Node.js است: سبک، سریع و با API آشنا. در عین حال باید محدودیتها (عدم اجرای JS، حافظه) را در طراحی اسکریپر در نظر بگیرید و بهترینروشها مانند مدیریت خطا، محدودسازی نرخ و رعایت اصول اخلاقی را اعمال کنید. با ترکیب Cheerio با ابزارهای شبکهای مانند axios و الگوهای مانند صفبندی و retry میتوانید اسکریپرهای قابلاعتماد و مقیاسپذیر بسازید.
