Installation

Cheerio ist eine server-seitige Implementierung des jQuery-Kerns, die speziell für Node.js-Umgebungen entwickelt wurde. Diese Anleitung behandelt alle Möglichkeiten, Cheerio in Ihren Projekten zu installieren und einzurichten.

package Manager Installation

npm

npm install cheerio

yarn

yarn add cheerio

pnpm

pnpm add cheerio

bun

bun add cheerio

Import-Syntax

ESM (ES modules) - Empfohlen

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!');

Destrukturierte Imports

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

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

TypeScript-Einrichtung

Cheerio wird mit integrierten TypeScript-Definitionen geliefert. Es ist kein zusätzliches @types package erforderlich.

Grundlegende TypeScript-Verwendung

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();

Erweiterte Type-Verwendung

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

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

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

Umgebungsunterstützung

Node.js-Anforderungen

Minimale Node.js-Version: 18.17 oder höher
Empfohlen: Node.js 20+ für beste Performance
Cheerio ist ausschließlich für den server-seitigen Einsatz konzipiert

Browser-Einschränkungen

⚠️ Wichtig: Cheerio ist nicht für Browser-Umgebungen konzipiert. Es ist eine server-seitige Bibliothek, die:

Node.js-spezifische APIs verwendet
Keine DOM-Inkonsistenz-Behandlung enthält, die jQuery bietet
Für server-seitiges HTML-Parsing und -Manipulation optimiert ist

Für Browser-Umgebungen verwenden Sie stattdessen jQuery oder moderne DOM APIs.

Erweiterte Lademethoden

Laden aus Buffern

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);

Laden von URLs

import * as cheerio from 'cheerio';

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

Streaming 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);

Konfigurationsoptionen

Parser-Optionen

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
});

Häufige Installationsprobleme

Node.js-Versionskonflikte

Fehler: Cannot find module 'cheerio' oder Kompatibilitätswarnungen

Lösung: Stellen Sie sicher, dass Sie Node.js 18.17 oder höher verwenden:

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 module-Probleme

Fehler: require() of ES Module oder import-Anweisungen in CommonJS

Lösung: Stellen Sie sicher, dass Ihre package.json den korrekten module-Typ hat:

{
  "type": "module"
}

Oder verwenden Sie die entsprechende Import-Syntax für Ihre Umgebung.

TypeScript-Konfiguration

Fehler: TypeScript-Kompilierungsfehler mit Cheerio-Types

Lösung: Aktualisieren Sie Ihre tsconfig.json:

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

Speicherprobleme mit großen Dokumenten

Fehler: JavaScript heap out of memory

Lösung: Erhöhen Sie das Node.js-Speicherlimit:

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

Oder verarbeiten Sie Dokumente in kleineren Blöcken mit Streaming-Methoden.

Kodierungsprobleme

Fehler: Falsche Zeichenkodierung im geparsten HTML

Lösung: Verwenden Sie loadBuffer() mit expliziten Kodierungsoptionen:

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

Überprüfung

Überprüfen Sie, ob Ihre Installation korrekt funktioniert:

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');

Mit diesen Installationsschritten sind Sie bereit, HTML mit Cheerios mächtiger, jQuery-ähnlicher API in Ihren Node.js-Anwendungen zu parsen und zu manipulieren.

← Overview & Quick Start Core API Reference →