Node.js 网页解析神器：cheerio 模块实战指南，像 jQuery 一样玩转 HTML

在 Node.js 开发中，我们经常需要处理网页内容------比如爬取网站数据、解析 HTML 模板、提取页面关键信息等。但原生 Node.js 处理 HTML 既繁琐又低效，而 cheerio 模块的出现，让我们能在服务端用熟悉的 jQuery 语法操作 HTML，彻底解决了网页解析的痛点。今天就带大家全面掌握这个"服务端 jQuery"，轻松应对各类 HTML 处理场景。

一、cheerio 是什么？为什么推荐它？

cheerio 是一款专为 Node.js 设计的轻量级 HTML 解析库，核心定位是"服务端的 jQuery"。它剥离了 jQuery 中与浏览器相关的 DOM 操作（如事件绑定、动画），仅保留了核心的 HTML 选择器和遍历、修改 API，同时兼容大部分 jQuery 语法，让前端开发者能零成本上手。

它能成为 Node.js 生态中网页解析的"首选工具"，主要得益于三大优势：

语法友好 ：完全兼容 jQuery 选择器（如 $('.class')、$('#id')、$('div > p')），前端开发者无需学习新语法，开箱即用。
性能高效 ：基于 htmlparser2 构建（比原生 DOMParser 快 8 倍以上），解析大型 HTML 页面也能保持流畅，内存占用仅为 PhantomJS 等工具的 1/10。
功能灵活：支持 HTML 解析、节点遍历、内容修改、属性操作等全流程需求，同时支持自定义解析配置（如忽略注释、保留空格），适配不同场景。

无论是爬虫开发、静态页面生成，还是 HTML 模板处理，cheerio 都能大幅提升开发效率，目前每周下载量超 300 万次，被 axios 爬虫生态、hexo 静态博客等众多工具依赖。

二、安装与快速上手：3 步解析 HTML

1. 安装模块

cheerio 无复杂依赖，只需一行命令即可安装：

bash 复制代码

# npm 安装
npm install cheerio

# yarn 安装
yarn add cheerio

2. 核心使用流程

cheerio 的使用逻辑非常清晰：加载 HTML → 选择节点 → 操作节点，我们用一个简单示例演示如何解析"博客列表页"并提取标题和链接：

javascript 复制代码

// 1. 引入 cheerio
const cheerio = require('cheerio');

// 2. 模拟需要解析的 HTML（实际场景可能来自 axios 爬取、文件读取等）
const blogHtml = `
  <div class="blog-list">
    <div class="blog-item">
      <h3 class="blog-title"><a href="/blog/1">Node.js 异步编程详解</a></h3>
      <p class="blog-date">2024-05-01</p>
    </div>
    <div class="blog-item">
      <h3 class="blog-title"><a href="/blog/2">cheerio 实战教程</a></h3>
      <p class="blog-date">2024-05-10</p>
    </div>
  </div>
`;

// 3. 加载 HTML，生成可操作的 $ 对象（类似 jQuery 的 $）
const $ = cheerio.load(blogHtml);

// 4. 解析数据：提取所有博客的标题和链接
const blogList = [];
// 选择所有 .blog-item 节点，遍历处理
$('.blog-item').each((index, element) => {
  // 从当前节点内选择子节点（注意：这里的 $(element) 是当前 .blog-item 节点）
  const title = $(element).find('.blog-title').text().trim(); // 提取标题文本
  const url = $(element).find('.blog-title a').attr('href'); // 提取链接属性
  const date = $(element).find('.blog-date').text(); // 提取日期
  
  blogList.push({ index: index + 1, title, url, date });
});

// 输出解析结果
console.log('解析的博客列表：', blogList);

运行代码后，会得到结构化的博客数据：

javascript 复制代码

[
  { index: 1, title: 'Node.js 异步编程详解', url: '/blog/1', date: '2024-05-01' },
  { index: 2, title: 'cheerio 实战教程', url: '/blog/2', date: '2024-05-10' }
]

3. 关键 API 说明

cheerio.load(html)：核心方法，将 HTML 字符串转换为可操作的 DOM 对象，返回的 $ 与 jQuery 的 $ 用法完全一致。
$(selector)：选择器，支持 ID、类、标签、属性等所有 jQuery 选择器语法（如 $('#id')、$('a[href^="/blog"]')）。
.each((index, element) => {})：遍历选中的节点，element 是原生 DOM 节点，需用 $(element) 包装后才能使用 cheerio 方法。
.text()：获取节点内的文本内容（不含 HTML 标签），传参则修改文本（如 .text('新标题')）。
.attr(name)：获取节点的属性值，传第二个参数则修改属性（如 .attr('href', '/new-url')）。

三、核心功能实战：从解析到修改全场景覆盖

cheerio 不仅能"读"HTML，还能"改"HTML，下面结合实际场景讲解高频功能。

1. 精准选择节点：掌握 jQuery 选择器

选择器是 cheerio 的核心，掌握以下常用语法，能应对 90% 以上的解析需求：

选择器语法	作用说明	示例
`#id`	按 ID 选择节点	`$('#header')` 选择 ID 为 header 的节点
`.class`	按类名选择节点	`$('.blog-item')` 选择所有 blog-item 类节点
`tag`	按标签名选择节点	`$('h3')` 选择所有 h3 标签
`parent > child`	选择父节点下的直接子节点	`$('.blog-list > .blog-item')`
`prev + next`	选择 prev 节点后的相邻 next 节点	`$('.blog-title + .blog-date')`
`[attr]`	选择包含指定属性的节点	`$('a[target]')` 选择有 target 属性的 a 标签
`[attr^=value]`	选择属性值以 value 开头的节点	`$('a[href^="/blog"]')` 选择链接以 /blog 开头的 a 标签
`:contains(text)`	选择包含指定文本的节点	`$('h3:contains("cheerio")')` 选择包含 cheerio 文本的 h3 标签

示例：提取"2024 年 5 月发布的博客"：

javascript 复制代码

// 选择文本包含 2024-05 的 .blog-date 节点，再找到其父节点 .blog-item
const mayBlogs = [];
$('.blog-date:contains("2024-05")').parent('.blog-item').each((i, el) => {
  mayBlogs.push({
    title: $(el).find('.blog-title').text(),
    date: $(el).find('.blog-date').text()
  });
});

2. 修改 HTML 内容：动态调整页面结构

在静态页面生成、模板处理场景中，常需要修改 HTML 内容，cheerio 提供了丰富的修改方法：

（1）修改文本与属性

javascript 复制代码

// 1. 修改单个节点的文本
$('.blog-title').first().text('cheerio 进阶教程'); // 将第一个博客标题改为"cheerio 进阶教程"

// 2. 修改属性（批量给 a 标签添加 target="_blank"）
$('a[href^="/blog"]').attr('target', '_blank');

// 3. 移除属性（删除所有 img 标签的 srcset 属性）
$('img').removeAttr('srcset');

（2）添加/删除节点

javascript 复制代码

// 1. 向 .blog-list 末尾添加新的博客节点
const newBlog = `
  <div class="blog-item">
    <h3 class="blog-title"><a href="/blog/3">cheerio 性能优化技巧</a></h3>
    <p class="blog-date">2024-05-15</p>
  </div>
`;
$('.blog-list').append(newBlog); // 追加到末尾（prepend 追加到开头）

// 2. 删除所有 class 为 old 的节点
$('.old').remove();

// 3. 替换节点（将所有 p 标签替换为 span 标签）
$('p').replaceWith((i, el) => `<span class="new-p">${$(el).text()}</span>`);

（3）获取修改后的完整 HTML

修改完成后，可通过以下方法获取完整的 HTML 字符串：

javascript 复制代码

// 获取完整 HTML（包括 <!DOCTYPE>、<html> 等根节点）
const fullHtml = $.html();

// 获取指定节点的 HTML（如只获取 .blog-list 部分的 HTML）
const blogListHtml = $('.blog-list').html();

3. 处理复杂场景：解析动态渲染页面与编码问题

实际开发中，会遇到"动态渲染的 HTML"（如 Vue/React 页面）或"编码乱码"问题，cheerio 需配合其他工具解决：

（1）解析动态渲染页面

cheerio 只能解析静态 HTML，若页面内容由 JavaScript 动态生成（如点击按钮加载列表），需先用 puppeteer（无头浏览器）获取渲染后的 HTML，再用 cheerio 解析：

bash 复制代码

# 安装 puppeteer
npm install puppeteer

javascript 复制代码

const puppeteer = require('puppeteer');
const cheerio = require('cheerio');

// 用 puppeteer 获取动态渲染后的 HTML
async function getDynamicHtml(url) {
  const browser = await puppeteer.launch(); // 启动无头浏览器
  const page = await browser.newPage();
  await page.goto(url, { waitUntil: 'networkidle2' }); // 等待页面加载完成
  
  const html = await page.content(); // 获取渲染后的 HTML
  await browser.close();
  
  return html;
}

// 解析动态页面
getDynamicHtml('https://example.com/dynamic-blog').then(html => {
  const $ = cheerio.load(html);
  // 后续解析逻辑与静态 HTML 一致
  const dynamicBlogs = $('.blog-item').map((i, el) => $(el).find('.blog-title').text()).get();
  console.log('动态页面解析的博客：', dynamicBlogs);
});

（2）解决 HTML 编码乱码

若爬取的 HTML 存在中文乱码（如 GBK 编码），需先用 iconv-lite 转换编码为 UTF-8，再交给 cheerio 解析：

bash 复制代码

# 安装 iconv-lite
npm install iconv-lite

javascript 复制代码

const fs = require('fs');
const iconv = require('iconv-lite');
const cheerio = require('cheerio');

// 读取 GBK 编码的 HTML 文件
const gbkBuffer = fs.readFileSync('./gbk-blog.html');
// 转换为 UTF-8 字符串
const utf8Html = iconv.decode(gbkBuffer, 'gbk');

// 正常解析
const $ = cheerio.load(utf8Html);
console.log('解决乱码后的标题：', $('.blog-title').text());

四、性能优化与最佳实践

1. 性能优化技巧

减少选择器调用次数 ：频繁调用 $(selector) 会重复解析 DOM，建议将常用节点缓存：

javascript 复制代码

// 不推荐：多次调用 $('.blog-item')
$('.blog-item').find('.title').text();
$('.blog-item').find('.date').text();

// 推荐：缓存节点
const $blogItems = $('.blog-item');
$blogItems.find('.title').text();
$blogItems.find('.date').text();

解析时忽略不必要内容 ：通过 cheerio.load 的配置项，跳过注释、空白节点，提升解析速度：

javascript 复制代码

const $ = cheerio.load(html, {
  ignoreWhitespace: true, // 忽略空白节点
  xmlMode: false, // 关闭 XML 模式（默认 HTML 模式）
  decodeEntities: true // 自动解码 HTML 实体（如 &amp; → &）
});

避免解析超大 HTML ：若 HTML 超过 10MB，建议先按标签分割（如只提取 <div class="content"> 部分），再进行解析。

2. 最佳实践

爬虫合规性 ：使用 cheerio 爬取数据时，需遵守网站的 robots.txt 协议，设置合理的请求间隔（如用 setTimeout 或 p-limit 控制并发），避免给服务器造成压力。

错误处理 ：解析前检查 HTML 是否为空，选择节点后判断是否存在，避免报错：

javascript 复制代码

if (!html) {
  console.error('HTML 内容为空');
  return;
}
const $title = $('.blog-title');
if ($title.length === 0) {
  console.warn('未找到博客标题节点');
  return;
}

TypeScript 支持 ：若使用 TypeScript，可安装 @types/cheerio 获取类型提示：
bash 复制代码
```
npm install -D @types/cheerio
```

五、总结：cheerio 适合谁？能解决什么问题？

cheerio 不是万能的，但在"服务端 HTML 处理"领域几乎无可替代：

如果你是前端开发者，想快速上手 Node.js 网页解析，它的 jQuery 语法能让你零成本过渡；
如果你需要开发轻量级爬虫，它比 PhantomJS 更高效，比原生 DOM 解析更易用；
如果你在做静态页面生成 （如 Hexo 插件）或HTML 模板处理，它的节点修改能力能大幅简化逻辑。

当然，它也有局限性------无法处理动态渲染的 JavaScript 逻辑，需配合 puppeteer 等工具；但在其擅长的静态 HTML 领域，cheerio 绝对是效率最高、学习成本最低的选择。

如果你还在为 Node.js 解析 HTML 而烦恼，不妨试试 cheerio，用熟悉的 jQuery 语法玩转服务端网页处理，让代码更简洁，效率翻倍！

欢迎在留言区分享你的 cheerio 使用场景，或提出解析过程中遇到的问题，我们一起探讨解决方案～