Установка

Cheerio — это серверная реализация основного функционала jQuery, специально разработанная для Node.js окружений. Это руководство охватывает все способы установки и настройки Cheerio в ваших проектах.

Установка через Package Manager

npm

npm install cheerio

yarn

yarn add cheerio

pnpm

pnpm add cheerio

bun

bun add cheerio

Синтаксис Import

ESM (ES Modules) - Рекомендуется

import * as cheerio from 'cheerio';

// Load HTML and create a Cheerio instance
const $ = cheerio.load('<h2 class="title">Hello world</h2>');

// Manipulate elements
$('h2.title').text('Hello there!');
$('h2').addClass('welcome');

console.log($.html());
// => <html><head></head><body><h2 class="title welcome">Hello there!</h2></body></html>

CommonJS

const cheerio = require('cheerio');

const $ = cheerio.load('<h2 class="title">Hello world</h2>');
$('h2.title').text('Hello there!');

Деструктурирующие Import

// Import specific functions
import { load, contains, merge } from 'cheerio';

const $ = load('<ul><li>Apple</li><li>Orange</li></ul>');

Настройка TypeScript

Cheerio поставляется со встроенными определениями TypeScript. Дополнительный package @types не требуется.

Базовое использование TypeScript

import * as cheerio from 'cheerio';
import type { CheerioAPI, Element } from 'cheerio';

const html = '<div class="container"><p>Hello</p></div>';
const $: CheerioAPI = cheerio.load(html);

// Type-safe element selection
const elements: cheerio.Cheerio<Element> = $('.container p');
const text: string | undefined = elements.text();

Продвинутое использование типов

import type { AnyNode, CheerioOptions } from 'cheerio';

const options: CheerioOptions = {
  xmlMode: true,
  decodeEntities: false
};

const $ = cheerio.load('<xml><item>data</item></xml>', options);

Поддержка окружений

Требования к Node.js

Минимальная версия Node.js: 18.17 или выше
Рекомендуется: Node.js 20+ для лучшей производительности
Cheerio предназначен исключительно для серверного использования

Ограничения браузера

⚠️ Важно: Cheerio не предназначен для браузерных окружений. Это серверная библиотека, которая:

Использует специфичные для Node.js API
Не включает обработку несовместимостей DOM, которую предоставляет jQuery
Оптимизирована для серверного парсинга и манипуляции HTML

Для браузерных окружений используйте jQuery или современные DOM API.

Продвинутые методы загрузки

Загрузка из Buffer

import * as cheerio from 'cheerio';
import * as fs from 'fs';

// Load from buffer with encoding detection
const buffer = fs.readFileSync('index.html');
const $ = cheerio.loadBuffer(buffer);

Загрузка из URL

import * as cheerio from 'cheerio';

// Fetch and parse HTML from a URL
const $ = await cheerio.fromURL('https://example.com');
console.log($('title').text());

Потоковая обработка HTML

import * as cheerio from 'cheerio';
import * as fs from 'fs';

// Parse HTML streams
const writeStream = cheerio.stringStream({}, (err, $) => {
  if (err) {
    console.error('Parse error:', err);
    return;
  }
  
  console.log($('h1').text());
});

fs.createReadStream('document.html', { encoding: 'utf8' })
  .pipe(writeStream);

Опции конфигурации

Опции парсера

import * as cheerio from 'cheerio';

const $ = cheerio.load(html, {
  // Use XML mode for XML documents
  xmlMode: false,
  
  // Decode HTML entities
  decodeEntities: true,
  
  // Set base URI for resolving relative URLs
  baseURI: 'https://example.com',
  
  // Enable/disable scripting
  scriptingEnabled: false
});

Распространенные проблемы установки

Конфликты версий Node.js

Ошибка: Cannot find module 'cheerio' или предупреждения о совместимости

Решение: Убедитесь, что используете Node.js 18.17 или выше:

node --version
# Should show v18.17.0 or higher

# Update Node.js if needed
npm install -g n  # For Unix systems
n latest

Проблемы с модулями ESM/CommonJS

Ошибка: require() of ES Module или операторы import в CommonJS

Решение: Убедитесь, что ваш package.json содержит правильный тип module:

{
  "type": "module"
}

Или используйте подходящий синтаксис import для вашего окружения.

Конфигурация TypeScript

Ошибка: Ошибки компиляции TypeScript с типами Cheerio

Решение: Обновите ваш tsconfig.json:

{
  "compilerOptions": {
    "moduleResolution": "node",
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true,
    "strict": true
  }
}

Проблемы с памятью при работе с большими документами

Ошибка: JavaScript heap out of memory

Решение: Увеличьте лимит памяти Node.js:

node --max-old-space-size=4096 your-script.js

Или обрабатывайте документы меньшими частями, используя потоковые методы.

Проблемы с кодировкой

Ошибка: Неправильная кодировка символов в парсированном HTML

Решение: Используйте loadBuffer() с явными опциями кодировки:

const $ = cheerio.loadBuffer(buffer, {
  encoding: {
    defaultEncoding: 'utf8'
  }
});

Проверка

Убедитесь, что ваша установка работает корректно:

import * as cheerio from 'cheerio';

const $ = cheerio.load('<h1>Test</h1>');
console.log($('h1').text()); // Should output: "Test"

// Check version
console.log('Cheerio version:', cheerio.version || 'Version info not available');

С выполненными шагами установки вы готовы начать парсинг и манипулирование HTML с помощью мощного, похожего на jQuery API Cheerio в ваших Node.js приложениях.

← Overview & Quick Start Core API Reference →