# douyin-extract-toolkit

**Repository Path**: c2002/douyin-extract-toolkit

## Basic Information

- **Project Name**: douyin-extract-toolkit
- **Description**: 抖音短视频批量提取工具包（免登录 Chrome+CDP 抓取 + 浏览器插件辅助）
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-10-10
- **Last Updated**: 2026-10-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 抖音提取工具包

批量提取抖音博主账号的作品信息（标题/简介、话题、发布时间、作品链接、点赞/评论/转发等），配合浏览器插件「短视频数据分析组件」在抖音页面实时抓取数据。

> 详细使用说明见 [操作指南.md](操作指南.md)（含图文版 [操作指南.html](操作指南.html)）。

## 功能特性

- **免登录抓取**：真实 Chrome 渲染 + CDP 捕获接口数据，无需构造签名、无需 Cookie
- **批量提取**：从 Excel 模板读取博主列表（博主名称 / 抖音主页），时间窗口由命令行 `--window` 统一指定，自动逐个提取
- **断点续跑**：意外中断后可从失败项继续，不必重头开始
- **多维输出**：合并 CSV + JSON 数据文件，并生成可搜索、可排序的 HTML 报告
- **插件辅助**：浏览器插件「短视频数据分析组件」在抖音页面注入浮层，实时展示/导出抓到的数据
- **账号切换**：一键清除浏览器登录信息重新登录，方便切换抖音账号

## 快速开始

1. 填写 `runtime/data/博主信息模板.xlsx`（只有两列：第一列博主名称、第二列抖音主页链接）
   - **表格只管「抓谁」，时间段是运行参数**，通过 `--window` 传入，对全部博主生效
   - 时间段支持：`今天` / `3日内` / `最近一周` / `最近1月` / `近半年` / `本周` / `上月` / `2026-08-01~2026-08-21` / `全部` 等，完整清单用 `--test-window` 查看
   - 识别不了的写法会**直接报错并中止**，不会默默导出全部数据；不传 `--window` 时默认导出全部
2. 双击 `douyin-extract.bat`，按菜单选择（提取前会自动询问导出时间段，直接回车=全部）：
   - `[1] 一键启动 + 提取`
   - `[2] 只启动调试浏览器`（配合插件手动查看）
   - `[3] 只提取作品`（浏览器已开时）
   - `[4] 切换抖音账号`（清除登录信息重新登录）
   - `[5] 环境自检`
3. 提取完成后结果在 `runtime/outputs/<时间戳>/` 目录（每次运行一个文件夹）：CSV / JSON / HTML 报告

命令行模式（更多选项见操作指南）：

```bat
douyin-extract.bat all                            :: 启动浏览器并提取（会询问时间段）
douyin-extract.bat run --window 最近一周           :: 直接指定时间段，不再询问
douyin-extract.bat run --window 3日内 --refresh    :: 换时间段需加 --refresh 重跑
douyin-extract.bat run --failed-only              :: 只重试失败的博主
python batch_extract.py --test-window             :: 自测时间段解析（无需连浏览器）
python batch_extract.py --window 最近一周 --dry-run :: 预览解析出的起止日期，不实际抓取
```

一键流程（bash / Git Bash，等价于菜单 `[1]`，但内置端口预检与登录态校验）：

```bash
bash run_extract.sh "最近一周"                    # 端口取 config.json（9333）
bash run_extract.sh "2026-09-18~2026-09-19" 9444  # 临时换端口
```

> - 命令行驱动时 Chrome 与提取脚本必须在**同一个后台任务/进程组**里运行——bash 命令结束后派生的 Chrome 会被回收（`nohup` / `disown` 也无效），`run_extract.sh` 已在内部处理。
> - ⚠️ **未登录抖音时抓取不会报错**，而是每个博主都返回「完成: 0 条」，极易误判为「博主没更新」。`run_extract.sh` 会自动轮询登录态（最多约 20 分钟）并在未登录时中止；直接跑 `batch_extract.py` 前请先执行 `python check_login.py`（退出码：0=已登录 / 1=未登录 / 2=端口未就绪）。

## 目录结构

```
抖音提取工具包/
├── douyin-extract.bat        ← 唯一入口（菜单 + 命令行）
├── batch_extract.py          ← 批量提取脚本
├── build_report.py           ← 生成 HTML 报告
├── make_template.py          ← 重新生成博主信息模板.xlsx
├── load_extension.py         ← CDP 加载浏览器插件（Chrome 137+ 替代 --load-extension）
├── check_login.py            ← 校验调试浏览器里的抖音登录态（未登录会静默抓到 0 条）
├── run_extract.sh            ← 【bash/Git Bash】一键：启浏览器 → 装插件 → 校验登录 → 提取
├── sync_plugin.sh            ← 从上游插件仓库单向同步 短视频数据分析组件/（含 --check）
├── config.json               ← 运行配置（端口 / 字段 / 滚动参数）
├── 操作指南.md / .html       ← 详细使用说明
└── 短视频数据分析组件/        ← Chrome 插件内嵌副本 v1.1.1（上游真源见下节）

运行时数据（runtime/，与程序本体分离，不入库）：
├── runtime/outputs/          ← 提取结果，每次运行新建时间戳子文件夹
│   └── 20260822_110501/      ← 单次运行的全部产物
│       ├── 作品数据_*.csv / .json
│       ├── 作品分析_*.html   ← build_report 生成的报告
│       ├── raw/              ← 每账号原始数据
│       └── extract_state.json
├── runtime/logs/             ← 运行日志（run-extract.log / start-debug.log）
├── runtime/profiles/         ← Chrome 调试配置（含登录态，勿删，否则需重新登录）
└── runtime/data/             ← 用户表格（博主信息模板.xlsx）
```

## 插件版本与同步

`短视频数据分析组件/` 是**内嵌副本**，上游唯一真源是独立仓库：

**https://gitee.com/gao-yinjie/douyin-data-analyzer-extension**

两处内容必须逐字节一致，但**不要手工复制文件**——两边 `manifest.json` 写着同样的版本号时，靠肉眼看不出内容是否一致。用脚本同步：

```bash
bash sync_plugin.sh           # 从上游拉最新并覆盖内嵌副本，写完自动逐字节校验
bash sync_plugin.sh --check   # 只比对不写入（不一致时退出码 1），适合放进流程开头做预检
```

`--check` 会打印两边版本号。内嵌副本更新后，**已加载扩展的浏览器要点刷新才生效**：`chrome://extensions` → 找到「短视频数据分析组件」→ 点刷新图标。

> **为什么需要专门比对行尾**：本机 PortableGit 的 system 级 `core.autocrlf=true`，会把同一份 `content.js` 在一个目录检出成 LF（51445 字节）、在另一个目录转成 CRLF（52526 字节）。字节数不同、版本号却相同，**极易被误判成「插件版本落后」**（本项目历史上就发生过一次误判）。因此两个仓库都加了 `.gitattributes`（`text=auto eol=lf`）把文本固定为 LF；若手工比对，务必先归一化行尾：
> ```bash
> diff <(tr -d '\r' < a/content.js) <(tr -d '\r' < b/content.js)
> ```

## 环境要求

- Windows + Chrome 或 Edge 浏览器
- Python 3.9+（或使用 bat 内配置的虚拟环境路径）

## 工作原理

- 真实 Chrome 以调试端口（默认 **9333**，见 `config.json` 的 `port`）启动，加载 `短视频数据分析组件` 插件
  - ⚠️ 若该端口被代理/VPN 类进程占用，Chrome 的 `bind()` 会失败（WSAEACCES 0x271D）并**退化为只监听 IPv6 `[::1]`**，而探测走 `127.0.0.1` 必然失败。`run_extract.sh` 与 `check` 会先做端口预检并提示换端口（如 `9444`）
- 插件在抖音页面（`world: MAIN`，`document_start`）劫持 fetch/XHR，截获 `aweme` 系列接口响应
- 批量脚本通过 CDP 驱动浏览器访问博主主页，捕获作品列表数据并落盘
- 免登录状态受抖音服务端限制：每个账号主页约返回首页 18 条，登录浏览可抓全

## 版本

- v1.0.0：首个可用版本（批量提取 + 插件 + 报告 + 账号切换 + 工具包整理）
- v1.1.0：时间段解析重写——支持中文数字/周/关键词窗口/整月日期；解析失败报错中止而非静默导出全部；新增 `--test-window` 自检与 `--dry-run` 日期预览
- v1.2.0：时间段从表格第3列改为命令行 `--window` 参数（表格回归两列：名称+链接）；模板重建；bat 菜单提取前自动询问时间段；修正 bat 内 Python 路径
- v1.2.1：新增 `run_extract.sh`（bash 一键流程：启浏览器 → 装插件 → 校验登录 → 提取，含端口预检）与 `check_login.py`（登录态校验，防未登录静默抓到 0 条）；调试端口默认 9222 → **9333**（规避 Clash 类代理占用导致的 IPv4 绑定失败）；`check_login.py` 默认端口改为读 `config.json`
- v1.2.2：新增 `sync_plugin.sh`（内嵌插件与上游仓库单向同步 + 一致性预检）；内嵌插件升到 **v1.1.1**（折叠成正方形悬浮图标等）；两仓库加 `.gitattributes` 固定 LF，消除「同一份插件字节数不同」的误判；文档补端口/登录态/插件同步说明