Automated Instagram video downloader with user tracking, deduplication, and cron scheduling
npm install instagram-video-dl一个强大的 Instagram 视频自动下载工具,支持用户跟踪、去重检测和定时任务调度。
- 🎯 多用户跟踪 - 同时追踪多个 Instagram 账号
- 🔄 智能去重 - 自动识别已下载的视频,避免重复下载
- ⏰ 定时调度 - 支持 cron 定时任务,自动运行下载
- 📊 统计分析 - 查看每个用户的下载历史和统计信息
- 🚀 批量下载 - 并发下载多个视频,提升效率
- 💾 断点续传 - 下载失败自动重试,带指数退避策略
- 🎨 友好界面 - 彩色终端输出,实时进度提示
- 🔍 干运行模式 - 预览下载内容而不实际下载
- Node.js 16+
- npm
``bash全局安装
npm install -g ig-downloader
$3
`bash
无需安装,直接运行(每次都会下载最新版本)
npx ig-downloader --help
`$3
`bash
克隆仓库
git clone https://github.com/JackEngineer/ig-downloader.git
cd ig-downloader安装依赖
npm install构建项目
npm run build安装 Playwright 浏览器(首次运行需要)
npx playwright install chromium本地链接开发版本
npm link
`🚀 快速开始
全局安装后,使用
ig-downloader 或简写 igd 命令:$3
`bash
添加用户
ig-downloader add natgeo --note "国家地理"
或简写
igd add natgeo --note "国家地理"限制最大视频数
igd add bbcnews --max-videos 5
`$3
`bash
igd list
`$3
`bash
下载所有用户的新视频
igd run只下载特定用户
igd run natgeo预览模式(不实际下载)
igd run --dry-run
`$3
`bash
使用向导配置定时计划
igd schedule-wizard安装到系统 crontab
igd install-cron查看定时任务状态
igd cron
`> 从源码安装的用户:继续使用
npm start 命令代替 igd📖 命令详解
$3
####
add <用户名> - 添加跟踪用户`bash
igd add <用户名> [选项]
`选项:
-
--max-videos <数量> - 设置该用户最大下载视频数(默认 20)
- --note <文本> - 为用户添加备注标签示例:
`bash
igd add natgeo --max-videos 10 --note "国家地理官方"
igd add bbcnews --note "BBC新闻"
`####
remove <用户名> - 移除用户`bash
igd remove natgeo
igd rm bbcnews # 简写形式
`####
enable <用户名> - 启用用户重新启用已禁用的用户:
`bash
igd enable natgeo
`####
disable <用户名> - 禁用用户暂时禁用用户而不删除其历史记录:
`bash
igd disable natgeo
`####
list - 查看跟踪列表显示所有跟踪用户及其统计信息:
`bash
igd list
igd ls # 简写形式
`输出包括:
- 用户名
- 启用状态
- 最大视频数限制
- 已下载视频数量
- 总下载大小
- 用户备注
$3
####
run [用户名] - 执行下载`bash
igd run [用户名] [选项]
`选项:
-
--dry-run - 预览模式,只显示将要下载的内容示例:
`bash
下载所有启用用户的新视频
igd run只下载特定用户
igd run natgeo预览将要下载的内容
igd run --dry-run
`工作流程:
1. 访问用户的 Instagram 主页
2. 收集 Reels 视频链接
3. 检查历史记录,过滤已下载的视频
4. 提取视频 CDN 链接
5. 批量下载新视频
6. 保存下载记录到历史数据库
$3
####
config - 查看/修改配置查看当前配置:
`bash
igd config
`修改配置项:
`bash
igd config <配置项> <值>
`可用配置项:
-
download-dir - 设置下载目录
- max-videos - 设置默认最大视频数
- scroll-timeout - 设置滚动超时时间(毫秒)
- schedule - 设置 cron 定时表达式示例:
`bash
设置下载目录
igd config download-dir ~/Videos/Instagram设置默认最大视频数
igd config max-videos 20设置滚动超时
igd config scroll-timeout 30000设置定时计划(每天早8点和晚8点)
igd config schedule "0 8,20 *"
`$3
####
schedule-wizard - 定时计划向导交互式配置定时任务(推荐):
`bash
igd schedule-wizard
`支持的定时模式:
- 每小时
- 每天(指定时间)
- 每周(指定星期和时间)
- 每月(指定日期和时间)
- 自定义 cron 表达式
####
install-cron - 安装定时任务自动将任务添加到系统 crontab:
`bash
igd install-cron
`功能:
- 自动检测 Node.js 路径
- 验证启用用户列表
- 添加任务到 crontab
- 配置日志输出到
~/ig-downloader.log####
uninstall-cron - 卸载定时任务从 crontab 中移除定时任务:
`bash
igd uninstall-cron
`####
cron - 查看定时任务状态显示当前定时任务配置和状态:
`bash
igd cron
`输出包括:
- 当前定时计划
- 任务是否已安装
- crontab 中的任务条目
- 手动安装指南
$3
####
stats - 全局统计查看所有用户的下载统计:
`bash
igd stats
`显示:
- 跟踪用户总数
- 已下载视频总数
- 总下载大小
⚙️ 配置文件
配置文件存储在
~/.ig-downloader/config.json:`json
{
"downloadDir": "./downloads",
"maxVideosPerUser": 20,
"scrollTimeout": 30000,
"schedule": "0 /6 ",
"users": [
{
"username": "natgeo",
"enabled": true,
"maxVideos": 10,
"note": "国家地理"
}
]
}
`历史记录存储在
~/.ig-downloader/history.json。📁 目录结构
下载的视频按用户名组织:
`
downloads/
├── natgeo/
│ ├── natgeo_ABC123_2024-01-15.mp4
│ └── natgeo_DEF456_2024-01-16.mp4
└── bbcnews/
└── bbcnews_GHI789_2024-01-15.mp4
`文件命名格式:
{用户名}_{shortCode}_{日期}.mp4🔧 开发
$3
`
src/
├── cli.ts # CLI 入口和命令处理
├── config.ts # 配置管理
├── config.test.ts # 配置模块测试
├── extractor.ts # 基于 Playwright 的视频提取
├── downloader.ts # 文件下载逻辑
├── downloader.test.ts # 下载器模块测试
├── history.ts # 下载历史跟踪
├── logger.ts # 彩色日志工具
├── logger.test.ts # 日志模块测试
├── cron-wizard.ts # 定时任务向导
└── cron-installer.ts # Crontab 安装工具
`$3
`bash
开发模式(自动重新编译)
npm run dev运行测试
npm run test监听模式运行测试
npm run test:watch生成测试覆盖率报告
npm run test:coverage代码检查
npm run lint自动修复 lint 问题
npm run lint:fix格式化代码
npm run format检查格式
npm run format:check
`$3
- TypeScript - 类型安全的 JavaScript
- Playwright - 浏览器自动化和网络拦截
- Vitest - 快速的单元测试框架
- ESLint + Prettier - 代码质量和格式化工具
$3
- 使用 TypeScript 严格模式
- ES2022 + ES 模块
- 双引号字符串
- 2 空格缩进
- 显式返回类型
- 命名导出(无默认导出)
详见
AGENTS.md 获取完整代码风格指南。🐛 故障排除
$3
如果遇到 "Executable doesn't exist" 错误:
`bash
npx playwright install chromium
`$3
可能原因:
- Instagram 需要登录才能访问该用户
- 用户没有公开的 Reels
- 网络问题或 Instagram 临时限流
解决方案:
- 尝试使用
--dry-run 检查链接收集是否正常
- 检查用户是否为公开账号
- 等待一段时间后重试$3
检查步骤:
`bash
查看 crontab 配置
crontab -l查看日志文件
tail -f ~/ig-downloader.log确认任务状态
igd cron
`$3
确保下载目录有写入权限:
`bash
chmod 755 ~/Downloads/Instagram
``⚠️ 使用须知:
1. 本工具仅供学习和个人使用
2. 请遵守 Instagram 的使用条款
3. 避免过于频繁的请求,以免触发限流
4. 不要用于商业用途或侵犯版权
5. 下载的内容版权归原作者所有
MIT License
欢迎提交 Issue 和 Pull Request!
- Playwright 文档
- Cron 表达式指南
- TypeScript 文档
---
如有问题或建议,欢迎反馈!