1. 项目概述一个面向开发者的网页内容检查与结构化工具最近在折腾一个很有意思的小项目起因是团队里经常需要从各种网页上抓取信息然后手动整理成结构化的数据。比如产品经理丢过来一个竞品网站链接让你分析一下他们的功能模块或者运营同学需要批量检查一批落地页的标题、描述、关键词是否合规。这种重复性的“复制-粘贴-整理”工作既枯燥又容易出错效率还低。于是我就琢磨着能不能写个工具让它自动去访问网页然后把我们关心的内容像标题、元描述、所有链接、图片地址、甚至页面结构都给我规规矩矩地提取出来最好是能直接生成一份清晰的报告或者结构化的数据比如JSON方便后续处理。这就是yifanyifan897645/webcheck-mcp这个项目诞生的背景。简单来说它是一个基于现代Web技术栈构建的“网页检查器”。它的核心目标不是做复杂的网络爬虫或数据分析而是聚焦于“检查”和“结构化”。你可以把它理解为一个给开发者用的“网页X光机”或者“格式化剪刀”。输入一个URL它就能帮你把这个网页“拆解”开把各个部件分门别类地摆好让你一目了然并且能方便地集成到你自己的自动化流程里。无论是做SEO初步审计、内容监控、链接检查还是作为其他更复杂数据抓取流程的前置步骤它都能派上用场。这个项目特别适合前端开发者、测试工程师、SEO从业者以及任何需要与网页原始内容打交道的技术人员。2. 核心设计思路与技术选型2.1 为什么选择“检查”而非“爬取”在设计之初我明确区分了“检查”和“爬取”。传统的爬虫Crawler/Spider目标是广度或深度遍历尽可能多地获取页面并处理反爬机制、会话维持、分布式调度等复杂问题。而“检查”工具的目标是深度单点分析对一个给定的页面进行快速、准确、全面的内容解构。因此webcheck-mcp的设计哲学是“轻量、精准、可集成”。轻量它不应该是一个需要复杂配置和庞大依赖的“巨无霸”。启动快资源占用少能够作为微服务或命令行工具轻松部署。精准提取的信息必须准确无误特别是对于动态渲染的现代网页SPA需要能获取到最终呈现在用户浏览器里的真实DOM。可集成输出必须是机器可读的结构化数据如JSON方便被其他系统CI/CD流水线、监控报警、数据分析平台直接调用和处理。基于这个思路技术栈的选型就变得清晰了。2.2 核心技术栈解析Puppeteer Express 结构化处理项目主要采用了 Node.js 生态下的几个核心库Puppeteer这是整个项目的“眼睛”和“手”。Puppeteer 是一个由Chrome团队维护的Node库它提供了一个高级API来控制Headless Chrome或Chromium。为什么选它而不是传统的cheerio或jsdom关键在于动态渲染。很多现代网站React, Vue, Angular构建的其核心内容是在浏览器端通过JavaScript执行后才生成的。cheerio只能解析静态HTML对于这类页面束手无策。Puppeteer可以启动一个真正的浏览器环境执行JS等待网络请求和元素加载从而获取到与用户所见完全一致的最终DOM。这对于“检查”的准确性至关重要。Express作为轻量级的Web应用框架Express负责提供HTTP API接口。这样webcheck-mcp就可以以服务的形式运行通过发送HTTP请求如POST /api/check来触发检查任务。这种设计比纯命令行工具更灵活可以轻松被其他服务远程调用也便于构建Web管理界面。结构化处理逻辑这是项目的“大脑”。在通过Puppeteer获取到完整的页面DOM后需要编写一系列选择器和逻辑来提取目标信息。这部分代码的质量直接决定了工具的输出价值。我们需要考虑容错性不是每个网页都有title标签或规范的meta描述。代码需要处理元素不存在的情况返回空值或默认值而不是崩溃。数据清洗提取的文本可能包含多余的空格、换行符需要统一清理。链接规范化提取到的链接可能是相对路径/about、绝对路径https://example.com/about或锚点#section需要统一处理成完整的绝对URL以便后续分析。性能考量在DOM中执行大量querySelectorAll操作可能较慢需要优化选择器并考虑是否需要分步提取。2.3 架构设计模块化与可扩展性为了让项目清晰且易于维护我采用了模块化的设计核心检查引擎 (core/checker.js)封装了使用Puppeteer打开页面、等待加载、执行检查脚本的核心流程。这是最独立的部分理论上可以脱离Web服务单独作为一个Node模块使用。检查项处理器 (processors/)每个要检查的项目如标题、元标签、链接、图片都有一个独立的处理器文件。例如titleProcessor.js专门负责提取和清洗标题。这种设计使得添加新的检查项比如检查Open Graph标签、查找特定CSS类名变得非常容易只需新建一个处理器并注册即可。API路由层 (routes/api.js)定义RESTful端点接收客户端请求URL、可选配置参数调用核心引擎并返回JSON格式的结果。配置与工具 (utils/)存放配置文件、URL处理工具函数、日志模块等。这种架构确保了关注点分离未来如果想支持并发检查、添加缓存层、或者输出不同格式如HTML报告都可以在相应模块中进行修改而不会牵一发而动全身。3. 核心功能实现与实操要点3.1 启动无头浏览器与页面导航这是所有操作的起点。使用Puppeteer时有几个关键参数和步骤直接影响成功率和性能。const puppeteer require(puppeteer); async function launchBrowser() { // 启动浏览器实例 const browser await puppeteer.launch({ headless: new, // 使用新的Headless模式更稳定 args: [ --no-sandbox, // 在Docker或某些Linux环境下可能需要 --disable-setuid-sandbox, --disable-dev-shm-usage, // 避免共享内存问题 --disable-accelerated-2d-canvas, --disable-gpu // 在无GPU服务器上建议禁用 ], defaultViewport: { width: 1920, height: 1080 } // 设置视口大小影响某些响应式布局 }); return browser; } async function navigateAndCheck(page, url) { // 创建页面实例 const page await browser.newPage(); // 设置User-Agent模拟真实浏览器避免被简单屏蔽 await page.setUserAgent(Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36); // 监听并拦截不必要的资源请求提升速度针对检查任务图片、字体、样式可能非必需 await page.setRequestInterception(true); page.on(request, (req) { const resourceType req.resourceType(); // 只允许文档、xhr/fetch请求通过阻塞图片、样式、字体等 if ([image, stylesheet, font, media].includes(resourceType)) { req.abort(); } else { req.continue(); } }); // 导航到目标URL并等待网络在至少500ms内没有新请求为止 await page.goto(url, { waitUntil: networkidle0, // 等待网络空闲 timeout: 30000 // 30秒超时 }); // 额外等待2秒确保所有客户端渲染完成针对重度SPA await page.waitForTimeout(2000); return page; }注意waitUntil: networkidle0是一个比较严格的等待条件对于某些持续发送心跳请求的页面可能永远无法满足导致超时。在实际项目中我通常会结合waitUntil: domcontentloaded和一个自定义的等待主要内容出现的选择器形成更稳健的策略。3.2 关键信息提取的实现细节获取到加载完成的page对象后我们可以在浏览器上下文中执行JavaScript代码来提取信息。这是各个处理器发挥作用的地方。1. 提取标题和元描述async function extractMeta(page) { return await page.evaluate(() { const getMetaContent (name) { const element document.querySelector(meta[name${name}], meta[property${name}]); return element ? element.getAttribute(content) : null; }; return { title: document.title || null, description: getMetaContent(description), keywords: getMetaContent(keywords), viewport: getMetaContent(viewport), // 也可以提取Open Graph协议标签 ogTitle: getMetaContent(og:title), ogDescription: getMetaContent(og:description), ogImage: getMetaContent(og:image), }; }); }这里使用了page.evaluate()方法它允许我们在浏览器环境中执行函数并返回结果到Node.js环境。注意处理可能为null的情况。2. 提取所有链接并规范化这是检查中比较复杂的部分因为链接形式多样。async function extractLinks(page, baseUrl) { return await page.evaluate((baseUrl) { const links Array.from(document.querySelectorAll(a[href])); const result []; const seen new Set(); // 用于简单去重 links.forEach(link { let href link.getAttribute(href); if (!href || href.startsWith(javascript:) || href #) { return; // 跳过无效链接 } try { // 使用URL构造函数进行规范化自动处理相对路径 const absoluteUrl new URL(href, baseUrl).href; if (!seen.has(absoluteUrl)) { seen.add(absoluteUrl); result.push({ url: absoluteUrl, text: (link.textContent || ).trim().substring(0, 200), // 截取部分锚文本 rel: link.getAttribute(rel) || null, target: link.getAttribute(target) || _self }); } } catch (e) { // 如果URL构造失败如格式极其怪异则忽略或记录 console.warn(Invalid URL skipped: ${href}); } }); return result; }, baseUrl); // 将baseUrl作为参数传入evaluate函数 }使用new URL(href, baseUrl)是规范化URL的最佳实践它比手动拼接字符串更可靠。去重Set可以避免返回大量重复的内部链接。3. 提取图片信息与链接提取类似但关注点不同。async function extractImages(page, baseUrl) { return await page.evaluate((baseUrl) { const images Array.from(document.querySelectorAll(img[src])); return images.map(img { let src img.getAttribute(src); let absoluteSrc src; try { absoluteSrc new URL(src, baseUrl).href; } catch (e) { // 如果规范化失败保留原src } return { src: absoluteSrc, alt: img.getAttribute(alt) || , width: img.naturalWidth || parseInt(img.getAttribute(width)) || null, height: img.naturalHeight || parseInt(img.getAttribute(height)) || null }; }).filter(img img.src); // 过滤掉src为空的图片 }, baseUrl); }这里我们尝试获取图片的自然宽高naturalWidth这只有在图片加载完成后才有效。在Headless模式下如果拦截了图片请求这个值可能为0。因此回退到width/height属性是必要的。3.3 构建API服务与结果封装有了数据提取能力我们需要通过HTTP接口暴露它。使用Express可以快速搭建。// routes/api.js const express require(express); const router express.Router(); const { runWebCheck } require(../core/checker); // 导入核心检查函数 router.post(/check, async (req, res) { const { url, config {} } req.body; // 1. 输入验证 if (!url) { return res.status(400).json({ error: Missing required field: url }); } let parsedUrl; try { parsedUrl new URL(url); // 验证URL格式 } catch (e) { return res.status(400).json({ error: Invalid URL format }); } // 2. 设置超时防止长时间运行的任务阻塞服务 const timeoutPromise new Promise((_, reject) setTimeout(() reject(new Error(Check timeout after 60s)), 60000) ); try { // 3. 执行检查与超时Promise竞速 const result await Promise.race([ runWebCheck(url, config), timeoutPromise ]); // 4. 返回结构化结果 res.json({ success: true, data: { checkedUrl: url, timestamp: new Date().toISOString(), meta: result.meta, links: { count: result.links.length, items: result.links }, images: { count: result.images.length, items: result.images }, // 可以加入状态码、最终重定向URL等信息 status: result.status, finalUrl: result.finalUrl } }); } catch (error) { // 5. 统一错误处理 console.error(Web check failed for ${url}:, error); res.status(500).json({ success: false, error: error.message || Internal server error during web check }); } }); module.exports router;这个API端点做了几件重要的事输入验证、超时控制、统一响应格式和错误处理。返回的JSON结构清晰包含了所有检查项目的汇总和详情方便客户端解析。4. 部署、配置与性能优化实战4.1 本地开发与快速测试对于本地开发package.json中配置好脚本是关键。{ scripts: { start: node server.js, dev: nodemon server.js, check:single: node scripts/check-cli.js --url https://example.com } }你可以使用npm run dev启动开发服务器配合nodemon实现热重载并使用Postman或curl测试APIcurl -X POST http://localhost:3000/api/check \ -H Content-Type: application/json \ -d {url:https://github.com}4.2 生产环境部署考量将webcheck-mcp部署到生产环境如云服务器、Docker容器时会遇到一些在本地没有的问题Puppeteer的依赖Puppeteer需要Chromium。在Linux服务器上可能需要安装额外的系统库。解决方案使用Docker是最佳实践。可以基于node:18-slim镜像并运行安装Chromium依赖的脚本。或者直接使用Puppeteer团队维护的ghcr.io/puppeteer/puppeteer镜像它包含了所有依赖。# Dockerfile 示例 FROM node:18-slim RUN apt-get update apt-get install -y \ wget \ chromium \ # ... 其他依赖 rm -rf /var/lib/apt/lists/* WORKDIR /app COPY package*.json ./ RUN npm ci --onlyproduction COPY . . USER node EXPOSE 3000 CMD [node, server.js]注意以非root用户运行应用并确保该用户有足够的权限访问/tmp等目录这是Puppeteer运行所必需的。资源管理与并发每个检查任务都会启动一个浏览器实例或页面非常消耗内存和CPU。如果API被频繁调用服务器可能很快崩溃。解决方案实现一个浏览器池Browser Pool。在服务启动时预先创建有限数量如5个的浏览器实例放入池中。当有检查请求到来时从池中借用borrow一个浏览器实例来创建页面执行任务任务完成后关闭页面将浏览器实例归还release给池。这避免了频繁启动/关闭浏览器的开销并控制了资源上限。可以使用generic-pool或tarn.js这类库来实现。配置管理生产环境的API端口、超时时间、并发数、日志级别等都应通过环境变量或配置文件管理而不是硬编码。// config.js module.exports { port: process.env.PORT || 3000, puppeteer: { headless: process.env.NODE_ENV production ? new : false, args: process.env.PUPPETEER_ARGS ? JSON.parse(process.env.PUPPETEER_ARGS) : [--no-sandbox, --disable-setuid-sandbox], }, checkTimeout: parseInt(process.env.CHECK_TIMEOUT_MS) || 60000, maxConcurrentChecks: parseInt(process.env.MAX_CONCURRENT_CHECKS) || 3 };4.3 性能优化技巧请求拦截如前所述在检查任务中拦截图片、样式表、字体等资源可以极大提升页面加载速度。但要注意如果检查目标包括图片的naturalWidth等属性则不能拦截图片请求。禁用不必要的功能在启动浏览器时可以添加更多args来提升性能。args: [ --disable-featuresIsolateOrigins,site-per-process, // 可选的沙箱隔离有时影响性能 --blink-settingsimagesEnabledfalse, // 全局禁用图片加载 --disable-notifications, --disable-geolocation, --disable-sync ]复用浏览器上下文如果使用浏览器池尽量复用同一个浏览器上下文BrowserContext来创建多个页面这比每次都创建新的上下文要快。设置合理的超时page.goto、page.waitForSelector等操作都必须设置超时防止因某些页面加载异常而永远阻塞。全局超时和每个操作的超时要配合使用。5. 常见问题排查与实战心得在实际使用和开发webcheck-mcp的过程中我踩过不少坑也总结了一些经验。5.1 典型问题与解决方案速查表问题现象可能原因排查步骤与解决方案页面超时无法加载完成1. 页面有无限循环的AJAX请求或WebSocket。2.networkidle0条件过于严格。3. 网络环境差或目标站点响应慢。1. 改用waitUntil: domcontentloaded或load。2. 使用page.waitForSelector(‘#main-content’)等待特定关键元素出现。3. 增加page.goto的timeout值如60000ms。4. 检查并优化请求拦截规则避免阻塞了关键资源。提取到的数据为空或不全1. 页面是客户端渲染SPAPuppeteer执行提取脚本时DOM还未更新。2. 选择器写错了或页面结构非常规。3. 页面有反爬机制检测到Headless浏览器。1. 在page.goto后增加page.waitForTimeout(2000-5000)等待渲染。2. 使用page.waitForSelector确保目标元素已存在。3. 在浏览器开发者工具中测试选择器是否正确。4. 尝试设置更真实的User-Agent和Viewport或启用headless: false调试。Puppeteer启动失败报错缺少库在Linux服务器上缺少Chromium的系统依赖。1. 根据Puppeteer官方文档安装缺失的包如ca-certificates,libnss3等。2.强烈推荐使用Docker部署彻底解决环境一致性问题。服务运行一段时间后内存泄漏1. 浏览器实例或页面未正确关闭。2. 事件监听器未移除。1. 确保每个检查任务完成后都执行await page.close()。2. 如果使用浏览器池确保归还实例前清理页面。3. 使用--max-old-space-size限制Node进程内存并配合PM2等进程管理工具自动重启。返回的链接URL格式混乱相对路径未正确转换为绝对路径。使用new URL(href, baseUrl)进行规范化这是最标准的方法。确保传入的baseUrl是页面最终的URL考虑重定向。并发请求时服务崩溃同时创建了太多浏览器实例耗尽内存。实现浏览器池限制并发实例数。将无状态的API服务转为队列处理请求先进入队列由有限的工作进程逐个处理。5.2 从实战中获得的几点深刻体会“网络空闲”是个相对概念waitUntil: networkidle0在理论上是完美的但在实际中特别是面对大量使用前端监控、实时通信的网站时它可能永远达不到。我的经验是组合策略更可靠先等domcontentloaded再等一个能代表主要内容加载完成的关键选择器如#app,.product-detail最后加一个固定的短时间等待如2秒来容错。这比死等网络空闲要稳健得多。错误处理要细致入微Puppeteer操作可能会在多个环节失败启动浏览器、导航、选择元素、执行脚本。错误处理不能只包裹最外层的函数。要在每个可能失败的异步操作goto,waitForSelector,evaluate上进行try-catch并记录足够的上文信息如当前URL、操作步骤这样在排查问题时才能快速定位。将错误信息结构化地返回给API调用方也非常重要。性能与准确性的权衡为了速度我们拦截了图片和样式表。但这意味着img.naturalWidth会为0一些通过CSS:before伪元素生成的内容也无法被准确识别。没有银弹。你需要根据检查任务的核心目标来配置。如果核心是检查链接和文本可以大胆拦截如果需要分析页面视觉布局或图片信息则不能拦截甚至需要等待图片加载完成await page.waitForSelector(img[src])。可观测性是运维的生命线在生产环境一定要给服务加上完善的日志和监控。记录每个检查任务的开始时间、结束时间、目标URL、成功与否、耗时、提取到的条目数量。这不仅能帮你发现性能瓶颈比如哪个网站特别慢还能在出现问题时比如突然所有检查都失败提供追溯线索。可以考虑集成像Winston这样的日志库并输出结构化日志JSON格式方便被ELK等日志系统收集。设计一个友好的CLI工具虽然核心是API服务但一个配套的命令行工具能极大提升开发调试效率。这个CLI工具可以直接调用核心的runWebCheck函数支持参数化输入URL、指定输出格式JSON、控制台表格、HTML文件还可以支持从文件批量读取URL列表。这让你在开发新功能或验证问题时无需启动整个Web服务。