1. 项目概述一个房产数据自动化抓取与分析的实战工具箱最近在帮朋友分析几个目标小区的二手房行情手动在链家、贝壳这些网站上翻页、记录、对比效率实在太低。数据分散在各个页面价格、面积、楼层、朝向等信息需要反复核对做个简单的横向对比都得花上大半天。作为一名习惯了用技术解决重复劳动的程序员我决定自己动手构建一个轻量级但足够强大的自动化工具于是就有了这个House Fetcher项目。本质上它是一个基于 Node.js 的房产网站爬虫技能包核心目标很明确自动化地从主流房产平台如链家、贝壳、安居客抓取结构化的房源信息并自动生成清晰易读的对比报告。它不是为了大规模、高频次的数据采集而设计而是定位为个人或小团队在进行购房决策、市场调研时的“数据助理”将人从繁琐的信息收集和初步整理工作中解放出来。整个工具包围绕几个关键点构建一是对抗现代网站的反爬机制特别是链家、贝壳这类防护严密的平台二是提供端到端的自动化工作流从输入目标网址到生成对比报告一键完成三是输出高度结构化的数据直接生成 Markdown 格式的房源卡片和对比表格方便后续分析和存档。如果你也受困于在多个房产 App 或网页间反复切换、手动记录信息的低效过程希望有一个可靠的工具来提升信息获取和处理的效率那么这个项目或许能给你带来一些直接的启发和可复用的代码。2. 核心设计思路与技术选型解析2.1 为何选择“双引擎”抓取策略Firecrawl 与 Playwright 的互补面对国内房产网站复杂的反爬策略动态渲染、人机验证、请求频率限制单一的抓取方案往往力不从心。因此我采用了Firecrawl 为主Playwright 为辅的“双引擎”架构。这不是简单的冗余而是基于不同场景和成本考虑的针对性设计。Firecrawl 作为主力它是一个商业化的网页抓取 API 服务其核心价值在于“省心”。它内部集成了高级的反反爬虫策略能够自动处理 JavaScript 渲染、验证码挑战如 Cloudflare Turnstile等难题。对于链家、贝壳这类反爬强度极高的网站直接使用传统的请求库如 axios, puppeteer成功率极低往往第一个请求就会触发验证。Firecrawl 相当于一个专业的“爬虫代理”我们只需提供目标 URL 和必要的认证信息如 Cookie它就能返回渲染后的 HTML 或直接提取的结构化数据。这大大降低了开发复杂度和维护成本让我们可以更专注于数据解析和业务逻辑。Playwright 作为轻量备选它是一个由微软开发的浏览器自动化库可以模拟真实用户操作浏览器。在项目中它主要用于对付那些反爬相对较弱、或结构简单的网站如一些信息聚合页或安居客的某些列表页。Playwright 的优势在于完全本地化、可控性强且无需支付 API 调用费用。但它的缺点是运行较慢需要启动浏览器实例且对抗高强度反爬的能力不如专业服务。因此在设计中我将它定位为补充方案用于特定场景或作为 Firecrawl 不可用时的降级选择。注意技术选型的核心是权衡。Firecrawl 用金钱API调用费换取开发时间和稳定性Playwright 用本地计算资源和开发复杂度换取零成本。对于个人、低频的房产数据抓取Firecrawl 的免费额度通常足够其稳定性带来的时间节省价值远超其成本。2.2 数据结构化与对比逻辑的设计考量抓取到原始 HTML 只是第一步如何从中精准提取出“价格”、“面积”、“户型”、“朝向”等关键字段并转化为可比较的数据是项目的另一个核心。基于 CSS 选择器的解析策略房产网站的页面结构虽然时常微调但其核心信息如总价、单价的 DOM 选择器在一段时间内相对稳定。我采用了保守而实用的方法为每个支持的网站链家、贝壳等编写特定的解析函数。这些函数内部使用类似page.locator(.totalPrice).innerText()或正则表达式来定位和提取文本。这种方法虽然需要针对不同网站适配但准确率高且能快速响应单个站点的页面改版。归一化与评分体系提取出的原始数据是字符串如“850万”、“89㎡”、“中楼层/6层”、“南”。为了进行对比必须将它们归一化为数值或可排序的枚举值。例如“850万” - 数值8500000“89㎡” - 数值89“中楼层” - 根据总楼层数计算出一个楼层系数如中楼层0.5高楼层0.8低楼层0.3用于量化楼层优劣。“南” - 朝向得分南向5分东南4分以此类推。基于这些归一化数据我设计了一个简单的加权评分模型。通常单价是衡量性价比的核心指标权重最高楼层和朝向影响居住体验给予中等权重装修和年代作为调整项。最终每个房源会得到一个“综合评分”作为自动化推荐排序的依据。这个模型虽然简单但能快速从一堆房源中筛选出性价比相对突出的选项为人工深度分析提供有力的初筛列表。3. 环境搭建与核心配置详解3.1 Node.js 环境与依赖安装的细节项目要求 Node.js v18 或更高版本我推荐使用 v22 LTS 版本它在性能和模块支持上更为稳定。你可以通过node --version命令进行验证。如果版本不符建议使用nvm(Node Version Manager) 来管理多个 Node.js 版本切换起来非常方便。进入项目的scripts目录后运行npm install。这里有一个关键细节package.json中除了声明playwright作为依赖更重要的是配置了npm run postinstall脚本用于自动安装 Playwright 所需的浏览器内核Chromium, Firefox, WebKit。第一次安装时由于需要下载浏览器耗时可能较长请保持网络通畅。如果安装失败可以尝试以下步骤# 清理 npm 缓存解决因缓存导致的依赖包损坏问题 npm cache clean --force # 删除现有的 node_modules 和锁文件从头开始 rm -rf node_modules package-lock.json # 设置 Playwright 跳过浏览器下载仅安装库后续再单独安装 # 或者使用国内镜像源加速 PLAYWRIGHT_DOWNLOAD_HOSThttps://npmmirror.com/mirrors/playwright npm install3.2 Firecrawl API Key 的申请与安全配置Firecrawl 是整个项目的抓取核心你需要先注册并获取 API Key。访问 Firecrawl 官网 用邮箱注册账号。登录后在控制台Dashboard通常能找到 “API Keys” 或类似区域。创建一个新的 API Key复制下来。安全是重中之重。绝对不要将 API Key 硬编码在代码中或提交到 Git 仓库。项目采用了.env文件来管理敏感信息。# 在项目根目录下复制环境变量模板 cp .env.example .env # 使用文本编辑器如 VSCode, Notepad打开 .env 文件你会看到类似以下内容FIRECRAWL_API_KEYfc-your-api-key-here DEFAULT_URLhttps://sh.lianjia.com/ershoufang/pudong/ DEFAULT_WAIT5000将fc-your-api-key-here替换为你刚刚复制的真实 API Key。DEFAULT_URL和DEFAULT_WAIT是可选配置可以为你常用的搜索页面和等待时间设置默认值。实操心得.env文件已被列入.gitignore确保它不会被意外提交。这是保护密钥的基本操作。在团队协作中应该将.env.example提交而让每个成员在本地创建自己的.env文件。3.3 关键 Cookie 的获取与使用策略对于链家、贝壳这类网站即使使用 Firecrawl有时也需要提供用户会话 Cookie 来绕过初始的验证关卡模拟已登录状态。获取 Cookie 的流程需要手动在浏览器中完成一次打开一个无痕窗口避免现有Cookie干扰访问目标网站例如https://sh.lianjia.com。如果网站弹出滑块验证或点选验证像正常用户一样完成它。这是获取有效 Cookie 的关键一步。验证通过页面正常加载后按下F12打开开发者工具。切换到“Application”(Chrome/Edge) 或“存储”(Firefox) 标签页。在左侧导航栏中找到“Cookies”并展开当前网站的域名如sh.lianjia.com。此时右侧会列出所有 Cookie 键值对。你需要全选并复制这些值。一个更快捷的方式是在 Cookie 列表的任意处右键选择 “Copy All as HTTP header string” 或类似选项你会得到一个类似于Cookie: select_city310000; lianjia_uuidxxx;...的长字符串。你只需要和;之间的部分即select_city310000; lianjia_uuidxxx;...。Cookie 的使用与时效性在运行自动化工作流 (node workflow.js) 时脚本会提示你粘贴 Cookie。Cookie 具有时效性通常是几小时到几天过期后需要重新获取。如果抓取时遇到“访问被拒绝”或跳转回验证页首要排查的就是 Cookie 是否已失效。切勿分享你的 Cookie它等同于你在该网站的一段临时身份凭证。4. 自动化工作流实战与脚本解析4.1 workflow.js一站式抓取与对比流水线workflow.js是这个项目的“大脑”它串联了从输入到输出的全过程。运行它非常简单cd scripts node workflow.js接下来脚本会以交互式命令行问答的方式引导你输入 Cookie脚本会提示请输入链家 Cookie (直接粘贴回车结束):。将你之前复制的 Cookie 字符串粘贴进去确保是一整行没有多余换行然后按回车。输入目标 URL接着提示请输入要抓取的链家列表页 URL:。这里需要输入一个具体的房源列表页例如https://sh.lianjia.com/ershoufang/pudong/或你设置了筛选条件如价格、房型后的列表页 URL。务必确保是列表页而不是单个房源的详情页。自动执行脚本随后会依次执行以下操作调用firecrawl-fetch.js使用你提供的 Cookie 和 URL 进行抓取。将抓取到的原始 HTML 解析成结构化的房源信息并为每个房源生成一个独立的 Markdown 文件如house1.md,house2.md。调用compare.js自动读取刚生成的所有房源 Markdown 文件进行数据对比和评分。最终生成一份名为comparison.md的对比报告。整个过程无需人工干预实现了真正的“一键式”操作。这对于需要定期监控某几个小区房价变动的场景来说效率提升是颠覆性的。4.2 firecrawl-fetch.js对抗反爬的核心抓取器这个脚本封装了与 Firecrawl API 的交互。其核心逻辑如下参数解析支持命令行参数如--url指定目标--cookie传递 Cookie-o指定输出文件。API 调用构造符合 Firecrawl API 规范的请求体。关键参数包括url、crawlerOptions可设置excludes来跳过不必要的页面元素提升速度以及可选的formats如果希望 API 直接返回提取好的数据但目前项目主要用其返回 HTML。错误处理与重试网络请求可能失败API 也可能返回错误如额度不足、目标网站不可达。脚本中包含了基本的错误处理和重试机制例如遇到 429 状态码时等待一段时间后重试。结果保存将 Firecrawl 返回的 HTML 内容保存到本地 Markdown 文件。这里保存的还不是结构化数据而是包含房源列表的完整页面 HTML为下一步解析做准备。一个常见的踩坑点Firecrawl 的免费套餐有调用次数和并发限制。在脚本中我刻意在连续请求之间添加了setTimeout延迟通过DEFAULT_WAIT环境变量控制这既是遵守其服务条款也是模拟人类操作间隔避免触发更严格的风控。4.3 解析器从 HTML 到结构化数据的魔法这是将原始网页转化为可用数据的关键环节代码通常内嵌在workflow.js或独立的解析模块中。以链家为例解析器需要知道总价可能在.totalPrice这个 CSS 类里。单价可能在.unitPrice里。房屋基本信息面积、户型、楼层、朝向可能在一个.houseInfo的节点里需要用正则表达式拆分。解析函数会遍历抓取到的 HTML 文档根据这些预定义的规则定位元素、提取文本、清洗数据如去除多余空格、单位最后组装成一个 JavaScript 对象{ title: 浦东世纪公园 - 2室2厅 - 89㎡, totalPrice: 8500000, unitPrice: 95495, area: 89, layout: 2室2厅, floor: 中楼层/6层, orientation: 南, community: 浦东世纪公园, link: https://sh.lianjia.com/ershoufang/123456.html }这个对象就是后续生成 Markdown 和对比分析的基础。由于网站前端可能改版解析规则需要不定期维护。在脚本中我将针对不同网站的解析逻辑做了分离方便单独更新。4.4 compare.js智能对比与报告生成当所有房源都被解析成结构化对象后compare.js登场了。它的工作流程是读取与加载从命令行参数或默认路径读取所有待对比的房源 Markdown 文件并反向解析回 JavaScript 对象。数据归一化调用统一的归一化函数将字符串类型的楼层、朝向等转换为可计算的数值分数。执行评分算法根据预设的权重单价权重最高其次是楼层、朝向等计算每个房源的加权综合分。生成报告对比表格创建一个 Markdown 表格直观展示所有房源的核心指标。排序与推荐根据综合分降序排列将得分最高的房源标记为“首选推荐”。详细理由不仅给出排名还会简要说明推荐理由例如“该房源单价低于小区均价 5%楼层和朝向俱佳性价比指数最高。”最终生成的comparison.md文件是一份可以直接用于团队讨论或个人决策的简洁报告它把分散的信息聚合、量化、可视化让决策依据从“感觉”变成了“数据”。5. 高级技巧与定制化扩展5.1 如何适配新的房产网站项目目前内置了对链家、贝壳等主流站点的解析器。如果你想抓取一个新的网站如“房天下”或本地房产网需要为其编写一个新的解析函数。这个过程本质上是“模式匹配”手动分析页面结构在浏览器中打开目标网站的一个典型房源列表页使用开发者工具F12查看其 HTML 结构。识别数据选择器找到显示总价、单价、面积、户型等信息的 HTML 元素记录下其 CSS 选择器路径或 class/id 名称。编写解析函数在项目的解析器模块中新增一个函数例如parseFangTX(html)。函数内部使用cheerio一个类似 jQuery 的服务器端 HTML 解析库或Playwright的locator方法根据上一步找到的选择器提取信息。更新路由逻辑在主要的抓取或解析入口处添加一个判断如果 URL 包含新网站的域名如fang.com则调用你新写的parseFangTX函数。实操心得优先选择具有唯一性和稳定性的选择器如>问题现象可能原因排查与解决步骤返回空白页或验证码页面1. Cookie 已过期。2. IP 地址被目标网站临时限制。1.首要步骤重新获取并更新 Cookie。2. 检查 Firecrawl 控制台查看该次抓取任务的状态和原始返回确认是否是网站返回了验证码。3. 暂停抓取 1-2 小时后再试避免连续请求。Firecrawl API 返回 429 错误达到 API 调用频率限制。1. 登录 Firecrawl 查看用量统计。2. 在代码中增加请求间隔 (DEFAULT_WAIT)。3. 考虑升级 API 套餐或优化脚本减少不必要的调用。网络超时或连接错误本地网络不稳定或目标网站服务器问题。1. 使用node debug.js如果已实现或简单的curl命令测试目标 URL 的可达性。2. 在脚本中添加更完善的网络错误重试机制例如最多重试3次每次间隔递增。解析出错数据为空目标网站的页面结构已更新。1. 手动访问目标 URL用开发者工具查看关键信息如价格的 HTML 结构是否变化。2. 更新对应网站的解析函数中的 CSS 选择器。6.2 数据不准解析规则失效与数据清洗有时抓取能成功但得到的数据是乱的比如价格单位是“万”没被正确转换或者面积里混入了“平米”以外的字符。正则表达式要健壮在提取“89㎡”这样的字符串时使用正则表达式/(\d(?:\.\d)?)\s*㎡/比简单的字符串分割更可靠它能处理小数和可能存在的空格。设置默认值和容错在解析函数中对于可能缺失的字段如“装修”信息要设置默认值如“未知”避免后续对比评分时因undefined而报错。人工抽样校验在首次为一个新网站编写解析器或长时间未使用后重新启用时务必人工抽查几个抓取结果与网页上的原始信息进行比对确保解析准确无误。6.3 环境与依赖问题npm install卡住或报错这通常与网络环境有关。除了使用国内镜像源也可以尝试单独安装 Playwright 的浏览器npx playwright install chromium。运行脚本时报Error: Cannot find module确保你的命令行当前目录在scripts文件夹下并且node_modules已正确安装。可以尝试cd scripts后再运行命令。Firecrawl API Key 无效确认.env文件中的FIRECRAWL_API_KEY值是否正确且没有多余的空格或换行。可以尝试在代码中临时console.log(process.env.FIRECRAWL_API_KEY)来输出验证。这个项目是我在实际需求中打磨出来的工具它可能不是最庞大或最完美的但贵在实用、聚焦。技术服务于需求清晰的目标加上合理的工具选型往往能组合出一个高效解决问题的方案。如果你在使用的过程中有任何改进想法或者遇到了新的问题欢迎在项目仓库中交流。