# house

**Repository Path**: Vincent_OSChina/house

## Basic Information

- **Project Name**: house
- **Description**: vibe编写贝壳房源爬取项目
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-28
- **Last Updated**: 2026-09-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 贝壳二手房信息采集工具

基于 Python + Playwright 的二手房信息采集与 Excel 导出工具，默认目标城市为**常州**。

> ⚠️ **合规声明**
> 本项目仅供个人学习、研究使用。使用时请遵守目标网站的 `robots.txt`、服务条款及当地法律法规。
> 工具已内置低频随机延时、`robots.txt` 检查、验证码检测暂停机制，**请勿用于高频抓取或商业用途**。

## 功能特性

- 按城市 / 行政区 / 商圈 / 户型 / 面积 / 总价 / 楼层档位进行**爬前筛选**
- Playwright 无头浏览器渲染，规避纯静态请求的字段缺失
- 进入详情页补全：楼层档位、总高、建成年份、装修、电梯、产权、**房源标签**
- 可选下载**户型图**（带 Referer 规避防盗链），记录本地路径与原始链接
- 按总高、建成年份、小区名做**详情页后过滤**
- 房源编号去重、JSONL 实时落盘、断点续爬
- 运行中连按两次 `q` **优雅停止**，已抓取部分立即导出，断点保留
- 导出 Excel：`房源明细`（按城市/区域/商圈/小区排序）+ `区域汇总`

## 目录结构

```
house_spider/
├── house_spider/
│   ├── __main__.py      # 入口
│   ├── cli.py           # 命令行参数
│   ├── config.py        # 城市/区域/映射/选择器/列定义
│   ├── models.py        # House 数据模型
│   ├── url_builder.py   # 筛选条件 -> URL
│   ├── parser.py        # 列表页/详情页多策略解析
│   ├── spider.py        # Playwright 爬虫主体
│   ├── storage.py       # 去重缓存 + 断点
│   ├── exporter.py      # Excel / CSV 导出
│   └── utils.py         # 日志、清洗、限速
├── data/                # houses.jsonl、state.json（运行期生成）
├── output/              # 导出文件
├── logs/                # 日志
└── requirements.txt
```

## 安装

```bash
python -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install -r requirements.txt
playwright install chromium        # 安装浏览器内核
```

## 快速开始

```bash
# 采集常州全部二手房，最多 50 页，请求间隔 5 秒起
python -m house_spider --city changzhou --max-pages 50 --delay 5

# 按区域 + 户型 + 面积筛选
python -m house_spider --city changzhou --district 天宁区 --layout 2 --area-min 70 --area-max 100

# 按小区名检索并后过滤总高（>=18 层）
python -m house_spider --city changzhou --community 阳光城 --min-total-floors 18 --no-headless

# 续爬
python -m house_spider --city changzhou --resume

# 离线转换：把已抓取的 houses.jsonl 直接导出为 Excel（无需启动浏览器）
python jsonl_to_excel.py --csv
```

## 参数说明

| 参数 | 默认 | 说明 |
| --- | --- | --- |
| `--city` | `changzhou` | 城市拼音或中文名（见 `config.py` 的 `CITY_CODES`） |
| `--district` | `全部` | 行政区中文名 |
| `--biz-area` | 空 | 商圈中文名 |
| `--community` | 空 | 小区名关键词（服务端 `rs` 检索，可与区/商圈组合；户型/面积/价格在检索结果内后过滤） |
| `--layout` | 空 | 室数，如 `2` |
| `--area-min` / `--area-max` | 空 | 面积区间（㎡） |
| `--price-min` / `--price-max` | 空 | 总价区间（万） |
| `--floor-level` | 空 | `low` / `mid` / `high` |
| `--min-total-floors` | 空 | 总高下限（详情页后过滤） |
| `--year-min` | 空 | 建成年份下限（详情页后过滤） |
| `--max-pages` | `100` | 最大翻页数 |
| `--delay` | `5` | 每次请求随机延时基数（秒） |
| `--out` | `output/houses.xlsx` | 导出路径 |
| `--csv` | 关 | 额外导出 CSV |
| `--download-layout` | 关 | 下载户型图到本地 |
| `--image-dir` | `output/images` | 户型图保存目录 |
| `--no-headless` | 关 | 有头模式，便于人工过验证码 |
| `--resume` | 关 | 断点续爬 |

## 输出

- `output/houses.xlsx`
  - **房源明细**：全部字段，按 `城市 → 行政区 → 商圈 → 小区 → 总价` 排序
  - **区域汇总**：按行政区统计房源数、均价、平均面积、平均单价
- `data/houses.jsonl`：原始数据（可二次处理）
- `data/state.json`：断点状态
- `output/images/`：户型图（`--download-layout` 时生成，命名 `{房源编号}_layout.jpg`）

## 常见问题

**Q：抓不到数据 / 字段为空？**
贝壳前端结构会不定期改版。解析优先级为 `__NEXT_DATA__` JSON → DOM 选择器 → 正则兜底。若某字段普遍为空，打开
`https://changzhou.ke.com/ershoufang/` 按 F12 查看实际结构，更新 `config.py` 中的 `LIST_CARD_SELECTORS`、`DETAIL_ATTR_SELECTORS`、`DETAIL_TAG_SELECTORS` 即可。

**Q：出现验证码 / 登录拦截怎么办？**
贝壳对无头浏览器风控较严，**首次务必用有头模式**：

```bash
python -m house_spider --city changzhou --no-headless --delay 8
```

- 程序会先访问首页预热，若检测到验证码/登录墙会**暂停**，请在弹出的浏览器窗口中手动完成验证或登录，然后回终端按回车继续（输入 `s` 跳过）。
- 验证态（Cookie/登录态）保存在 `--user-data-dir`（默认 `data/browser_profile`），**后续运行可直接复用**，不必每次验证。
- 若无头模式仍被拦截，说明该会话未通过风控：先用 `--no-headless` 人工验证一次即可。
- 程序已内置：持久化上下文、`navigator.webdriver` 弱化、真实 UA/视口/语言。请勿高频运行，间隔建议 ≥ 8 秒。

**Q：区域拼音段不对？**
在浏览器打开对应区域页面，复制地址栏中 `/ershoufang/` 后的拼音段，补充到 `config.py` 的 `DISTRICTS` 映射。

**Q：小区名、总高、年份为什么不能直接筛？**
小区名走服务端关键词检索（`rs{小区名}`），可与行政区/商圈组合，无需全量爬取；但贝壳的关键词检索**不能**与户型/面积/价格等筛选段共存，因此这些条件会在检索结果（通常只有几十条）内做后过滤。
总高、建成年份贝壳不提供筛选参数，仍需进入详情页后对已抓数据做后过滤（`post_filter`）。