Kimkykie/twitter-image-downloader
GitHub: Kimkykie/twitter-image-downloader
基于 Puppeteer 浏览器自动化的 Twitter/X 时间线图片批量下载工具，支持增量同步与会话持久化。
Stars: 8 | Forks: 4
# Twitter 时间线图片下载器
通过 CLI 从 Twitter/X 个人主页下载图片。专为 OSINT 工作流构建。
## 问题
需要存档 Twitter 个人主页的媒体文件以供研究或备份。手动下载非常繁琐，而且由于 Twitter 的反自动化措施，大多数现有工具经常失效。
## 解决方案
基于自动化浏览的爬虫，可处理身份验证、无限滚动和批量下载。使用会话持久化来尽量减少登录阻力，并包含智能速率限制以避免被封锁。
## 快速开始
需要 Node.js 24。如果您使用 `nvm`，请在安装依赖项之前选择固定的 runtime：
```
git clone https://github.com/Kimkykie/twitter-image-downloader.git
cd twitter-image-downloader
nvm use
npm install
```
设置环境：
```
cp .env.example .env
```
**重要提示**：首次运行时请设置 `PUPPETEER_HEADLESS=false`（用于处理 Twitter CAPTCHA）。
```
npm start
```
## 工作原理
1. **身份验证** - 通过 cookie 持久化进行自动登录
2. **时间线解析** - 无限滚动以加载所有媒体帖子
3. **增量下载** - 仅获取自上次运行以来的新推文（通过 SQLite 追踪）
4. **下载队列** - 并行下载并检测重复项
5. **恢复能力** - 从中断处继续未完成的下载
6. **进度追踪** - 实时统计和 CSV 导出
身份验证 cookie 保存在 `cookies.json` 中。删除此文件可强制重新进行身份验证。
## SQLite 启动故障排除
`better-sqlite3` 包含一个与安装它的 Node.js 主版本号绑定的原生二进制文件。如果自上次安装以来 Node 已升级，请在启动应用程序之前重新构建该 module：
```
nvm use
npm rebuild better-sqlite3
```
如果重新构建失败，请使用 `npm ci` 重新安装锁定的依赖项。这不会删除 `data/twitter_downloads.db` 或之前下载的图像。
当 SQLite 无法启动时，应用程序会在启动浏览器之前退出，因为增量下载和恢复追踪需要数据库。
## 登录问题故障排除
如果您在 `onboarding/task.json` 上遇到类似 `"Could not log you in"` 或 `400 Bad Request` 的错误，说明 Twitter 检测到了自动化行为。请改用手动导出 cookie：
### 手动导出 Cookie（推荐）
1. **安装 cookie 导出扩展：**
- Chrome：[Cookie-Editor](https://chrome.google.com/webstore/detail/cookie-editor/hlkenndednhfkekhgcdicdfddnkalmdm)
- Firefox：[Cookie Quick Manager](https://addons.mozilla.org/en-US/firefox/addon/cookie-quick-manager/)
2. **手动登录 Twitter：**
- 打开浏览器并访问 `https://x.com`
- 使用您的凭据登录
- 完成任何 CAPTCHA 或验证提示
3. **导出 cookie：**
- 在 x.com 上点击 cookie 扩展图标
- 点击“Export”或“Export as JSON”
- 复制 JSON 内容
4. **将 cookie 保存到项目中：**
# 删除旧的过期 cookie
rm cookies.json
# 创建新的 cookies.json 并粘贴导出的 JSON
nano cookies.json
# 或者使用任意文本编辑器
5. **运行工具：**
npm start
该工具将使用您的手动会话，无需自动登录。
### 必要的 Cookie
确保您导出的 cookie 包含：
- `auth_token` - 主要身份验证 token
- `ct0` - CSRF 保护 token
- `twid` - Twitter 用户 ID
### 仍有问题？
- 如果受到速率限制，请等待 15-30 分钟
- 尝试更换 IP（VPN）
- 先在浏览器中手动登录以清除安全标记
- 检查您的账户是否有任何安全暂停
## CLI 用法
```
# 交互模式（提示所有选项）
npm start
# 从特定账号下载
npm start elonmusk
npm start user1 user2 user3
# 控制下载顺序
npm start --newest elonmusk # Download newest tweets first (default)
npm start --oldest elonmusk # Download oldest tweets first
# 仅检查新推文（遇到已下载的推文时停止）
npm start --new-only elonmusk
npm start --new-only --stop-after=10 elonmusk # Stop after 10 known tweets
# 帮助
npm start --help
```
## 配置
编辑 `.env`：
```
TWITTER_USERNAME=your_username # Optional - will prompt if missing
TWITTER_PASSWORD=your_password # Optional - will prompt if missing
PUPPETEER_HEADLESS=false # Keep false until authenticated
VIEWPORT_WIDTH=1366 # Browser dimensions
VIEWPORT_HEIGHT=768
# 下载行为
DOWNLOAD_ORDER=newest # newest or oldest first
# 提前停止 - 遇到已处理的推文时停止
EARLY_STOP_ENABLED=false # Default: scroll entire timeline
EARLY_STOP_THRESHOLD=20 # Consecutive known tweets before stopping
# 重试设置
MAX_TWEET_RETRIES=3 # Retries for failed tweet pages
MAX_IMAGE_RETRIES=3 # Retries for failed image downloads
RETRY_BASE_DELAY=2000 # Base delay between retries (ms)
```
## 项目结构
```
src/
├── config/config.js # App configuration
├── db/ # SQLite database layer
│ ├── connection.js # Database connection
│ ├── migrations.js # Schema migrations
│ └── repositories/ # Data access
│ ├── accountRepository.js
│ ├── tweetRepository.js
│ └── imageRepository.js
├── services/
│ ├── authService.js # Login/session handling
│ ├── browserService.js # Puppeteer automation
│ ├── imageService.js # Download management
│ ├── pagePoolManager.js # Parallel browser tabs
│ ├── parallelTweetProcessor.js # Concurrent processing
│ └── progressTracker.js # Resume capability
├── utils/
│ ├── downloadTracker.js # Progress tracking
│ ├── logger.js # Console output
│ ├── fileSystem.js # File operations
│ ├── errors.js # Custom error types
│ └── semaphore.js # Concurrency control
└── index.js # CLI entry point
data/
└── twitter_downloads.db # SQLite database (auto-created)
```
## 输出
- **图片**：`./images/{username}/`
- **下载日志**：包含元数据和状态的 CSV
- **会话数据**：`cookies.json`（自动生成）
## 速率限制
内置节流机制以规避 Twitter 的反机器人措施：
- 页面交互之间的请求延迟
- 检测到速率限制时自动退避
- 会话轮换支持
## 安全提示
- 使用专用的 Twitter 账户进行抓取
- Cookie 包含身份验证 token，请视为凭据妥善保管
- 对于大规模操作，请考虑使用 VPN/代理
## 路线图
- [x] 增量下载（跳过已处理的推文）
- [x] 用于持久状态的 SQLite 追踪
- [x] 恢复中断的下载
- [x] 并行浏览器标签页基础设施
- [ ] 支持 GIF 和 MP4 下载
- [ ] 激活完全并行处理模式
## 许可证
MIT
**免责声明**：请遵守 Twitter 的服务条款和适用法律。此工具仅供研究和存档之用。
## 问题
需要存档 Twitter 个人主页的媒体文件以供研究或备份。手动下载非常繁琐，而且由于 Twitter 的反自动化措施，大多数现有工具经常失效。
## 解决方案
基于自动化浏览的爬虫，可处理身份验证、无限滚动和批量下载。使用会话持久化来尽量减少登录阻力，并包含智能速率限制以避免被封锁。
## 快速开始
需要 Node.js 24。如果您使用 `nvm`，请在安装依赖项之前选择固定的 runtime：
```
git clone https://github.com/Kimkykie/twitter-image-downloader.git
cd twitter-image-downloader
nvm use
npm install
```
设置环境：
```
cp .env.example .env
```
**重要提示**：首次运行时请设置 `PUPPETEER_HEADLESS=false`（用于处理 Twitter CAPTCHA）。
```
npm start
```
## 工作原理
1. **身份验证** - 通过 cookie 持久化进行自动登录
2. **时间线解析** - 无限滚动以加载所有媒体帖子
3. **增量下载** - 仅获取自上次运行以来的新推文（通过 SQLite 追踪）
4. **下载队列** - 并行下载并检测重复项
5. **恢复能力** - 从中断处继续未完成的下载
6. **进度追踪** - 实时统计和 CSV 导出
身份验证 cookie 保存在 `cookies.json` 中。删除此文件可强制重新进行身份验证。
## SQLite 启动故障排除
`better-sqlite3` 包含一个与安装它的 Node.js 主版本号绑定的原生二进制文件。如果自上次安装以来 Node 已升级，请在启动应用程序之前重新构建该 module：
```
nvm use
npm rebuild better-sqlite3
```
如果重新构建失败，请使用 `npm ci` 重新安装锁定的依赖项。这不会删除 `data/twitter_downloads.db` 或之前下载的图像。
当 SQLite 无法启动时，应用程序会在启动浏览器之前退出，因为增量下载和恢复追踪需要数据库。
## 登录问题故障排除
如果您在 `onboarding/task.json` 上遇到类似 `"Could not log you in"` 或 `400 Bad Request` 的错误，说明 Twitter 检测到了自动化行为。请改用手动导出 cookie：
### 手动导出 Cookie（推荐）
1. **安装 cookie 导出扩展：**
- Chrome：[Cookie-Editor](https://chrome.google.com/webstore/detail/cookie-editor/hlkenndednhfkekhgcdicdfddnkalmdm)
- Firefox：[Cookie Quick Manager](https://addons.mozilla.org/en-US/firefox/addon/cookie-quick-manager/)
2. **手动登录 Twitter：**
- 打开浏览器并访问 `https://x.com`
- 使用您的凭据登录
- 完成任何 CAPTCHA 或验证提示
3. **导出 cookie：**
- 在 x.com 上点击 cookie 扩展图标
- 点击“Export”或“Export as JSON”
- 复制 JSON 内容
4. **将 cookie 保存到项目中：**
# 删除旧的过期 cookie
rm cookies.json
# 创建新的 cookies.json 并粘贴导出的 JSON
nano cookies.json
# 或者使用任意文本编辑器
5. **运行工具：**
npm start
该工具将使用您的手动会话，无需自动登录。
### 必要的 Cookie
确保您导出的 cookie 包含：
- `auth_token` - 主要身份验证 token
- `ct0` - CSRF 保护 token
- `twid` - Twitter 用户 ID
### 仍有问题？
- 如果受到速率限制，请等待 15-30 分钟
- 尝试更换 IP（VPN）
- 先在浏览器中手动登录以清除安全标记
- 检查您的账户是否有任何安全暂停
## CLI 用法
```
# 交互模式（提示所有选项）
npm start
# 从特定账号下载
npm start elonmusk
npm start user1 user2 user3
# 控制下载顺序
npm start --newest elonmusk # Download newest tweets first (default)
npm start --oldest elonmusk # Download oldest tweets first
# 仅检查新推文（遇到已下载的推文时停止）
npm start --new-only elonmusk
npm start --new-only --stop-after=10 elonmusk # Stop after 10 known tweets
# 帮助
npm start --help
```
## 配置
编辑 `.env`：
```
TWITTER_USERNAME=your_username # Optional - will prompt if missing
TWITTER_PASSWORD=your_password # Optional - will prompt if missing
PUPPETEER_HEADLESS=false # Keep false until authenticated
VIEWPORT_WIDTH=1366 # Browser dimensions
VIEWPORT_HEIGHT=768
# 下载行为
DOWNLOAD_ORDER=newest # newest or oldest first
# 提前停止 - 遇到已处理的推文时停止
EARLY_STOP_ENABLED=false # Default: scroll entire timeline
EARLY_STOP_THRESHOLD=20 # Consecutive known tweets before stopping
# 重试设置
MAX_TWEET_RETRIES=3 # Retries for failed tweet pages
MAX_IMAGE_RETRIES=3 # Retries for failed image downloads
RETRY_BASE_DELAY=2000 # Base delay between retries (ms)
```
## 项目结构
```
src/
├── config/config.js # App configuration
├── db/ # SQLite database layer
│ ├── connection.js # Database connection
│ ├── migrations.js # Schema migrations
│ └── repositories/ # Data access
│ ├── accountRepository.js
│ ├── tweetRepository.js
│ └── imageRepository.js
├── services/
│ ├── authService.js # Login/session handling
│ ├── browserService.js # Puppeteer automation
│ ├── imageService.js # Download management
│ ├── pagePoolManager.js # Parallel browser tabs
│ ├── parallelTweetProcessor.js # Concurrent processing
│ └── progressTracker.js # Resume capability
├── utils/
│ ├── downloadTracker.js # Progress tracking
│ ├── logger.js # Console output
│ ├── fileSystem.js # File operations
│ ├── errors.js # Custom error types
│ └── semaphore.js # Concurrency control
└── index.js # CLI entry point
data/
└── twitter_downloads.db # SQLite database (auto-created)
```
## 输出
- **图片**：`./images/{username}/`
- **下载日志**：包含元数据和状态的 CSV
- **会话数据**：`cookies.json`（自动生成）
## 速率限制
内置节流机制以规避 Twitter 的反机器人措施：
- 页面交互之间的请求延迟
- 检测到速率限制时自动退避
- 会话轮换支持
## 安全提示
- 使用专用的 Twitter 账户进行抓取
- Cookie 包含身份验证 token，请视为凭据妥善保管
- 对于大规模操作，请考虑使用 VPN/代理
## 路线图
- [x] 增量下载（跳过已处理的推文）
- [x] 用于持久状态的 SQLite 追踪
- [x] 恢复中断的下载
- [x] 并行浏览器标签页基础设施
- [ ] 支持 GIF 和 MP4 下载
- [ ] 激活完全并行处理模式
## 许可证
MIT
**免责声明**：请遵守 Twitter 的服务条款和适用法律。此工具仅供研究和存档之用。标签：GNU通用公共许可证, MITM代理, Node.js, Puppeteer, Twitter, 命令控制, 数据泄露, 数据采集, 自定义脚本