跳到主要内容

tdl 长期维护与追加下载教程


tdl 长期维护与追加下载教程(Windows)


一、tdl 的正确定位

✅ tdl 是:

  • 基于 Telegram API 的第三方下载客户端(不是 Telegram 官方出品)
  • 使用 你自己的账号(session)
  • 命令行工具

❌ tdl 不是:

  • 爬虫 / bot
  • 破解工具

登录与会话

tdl 支持从官方 Telegram Desktop 会话导入,也支持二维码和手机号验证码登录。长期使用时选一种稳定方式即可:

# 默认尝试从官方 Telegram Desktop 导入
tdl login -n archive

# 或二维码登录
tdl login -n archive -T qr

# 或手机号 + 验证码
tdl login -n archive -T code

登录后的会话由 tdl 自己保存。使用 Desktop 导入方式时,Desktop 窗口不需要一直打开;但注销账号、撤销会话或出现 session 冲突后,应重新验证 tdl 登录状态。


二、长期维护时建议固定的几件事

1. 使用稳定账号和默认并发

Telegram 对账号和下载存在服务端限制。长期批量下载时尽量使用稳定账号,不要频繁在很多设备上同时操作,也不要一开始就把线程和并发调得很高。

2. 固定 namespace(隔离账号会话与本地数据)

tdl login -n archive

后续这个归档任务继续使用同一个 -n archive,避免和其他账号/任务混用。

3. 固定目录结构

D:\TG-Archive\
│
├─ Channel_A\
│  ├─ tdl-export.json
│  └─ media\
│
├─ Channel_B\
│  ├─ tdl-export.json
│  └─ media\
│
└─ README.txt

一个频道单独一个目录更容易维护,但这只是目录组织建议,不影响 tdl 本身的工作机制。


三、安装与验证登录

Windows 可以使用官方安装脚本:

iwr -useb https://docs.iyear.me/tdl/install.ps1 | iex

验证:

tdl version

前面已经完成 -n archive 登录后,可检查当前账号是否能正常读取聊天列表;需要代理时继续显式传入:

tdl -n archive chat ls --proxy socks5://127.0.0.1:10808

四、第一次完整下载(初始化)

✅ 只做一次
✅ 之后都是“追加”


Step 1:进入频道目录

cd D:\TG-Archive\Channel_A

Step 2:导出聊天清单(不下载)

$Chat = '@your_channel'  # 替换为你有权访问的频道用户名或ID
tdl -n archive chat export -c $Chat --proxy socks5://127.0.0.1:10808

生成:tdl-export.json

👉 这是一个“下载清单/快照”


Step 3:按清单下载(长期维护核心命令)

tdl -n archive dl -f tdl-export.json --takeout --proxy socks5://127.0.0.1:10808 --continue --skip-same -d media

先使用 tdl 默认线程和并发。只有确认账号、网络和磁盘都稳定时,再按实际需要调整 -t / -l,不要把高并发当成长期维护的固定配置。


🔍 五、补充:-d media 是干什么的?

✅ 结论

-d media

表示:

把所有下载的图片/视频,统一放到当前目录下的 media 文件夹中


✅ 不加 -d 会怎样?

默认行为是:

当前目录/
└─ downloads/

✅ 加了 -d media 后(推荐)

如果你在:

D:\TG-Archive\Channel_A

结果一定是:

D:\TG-Archive\Channel_A\
├─ tdl-export.json
└─ media\
   ├─ -100xxx_12345_video.mp4
   ├─ -100xxx_12346_photo.jpg

✅ 好处:

  • 导出文件与媒体分离
  • 目录长期不会乱
  • 后期备份、迁移非常清晰

长期维护时固定使用同一个下载目录会更方便,-d media 只是这里采用的目录习惯。

(目录不存在会自动创建)


六、长期维护:追加新内容

❗ tdl 不会自动追踪更新
✅ 追加 = 重新 export + 同一下载目录 + --skip-same;中断任务再用 --continue 恢复

✅ 标准追加流程(以后永远这样)

cd D:\TG-Archive\Channel_A

$Chat = '@your_channel'  # 与首次导出使用同一频道
tdl -n archive chat export -c $Chat --proxy socks5://127.0.0.1:10808

tdl -n archive dl -f tdl-export.json --takeout --proxy socks5://127.0.0.1:10808 --continue --skip-same -d media

✅ 目标目录中名称(不含扩展名)和大小都相同的旧文件可跳过
✅ 清单中的新文件会下载到目标目录
✅ 同名同大小文件可由 --skip-same 跳过;改名或变更下载模板后需重新核对


七、直接下载“一条视频 / 图片”

✅ 这是手动补漏 / 临时下载必会用的


✅ 1️⃣ 下载一条视频 / 图片

tdl -n archive dl -u https://t.me/xxx/123

国内环境常用:

tdl -n archive dl -u https://t.me/xxx/123 --proxy socks5://127.0.0.1:10808 --continue

✅ 2️⃣ 下载相册 / 组合消息(一定要加)

tdl -n archive dl -u https://t.me/xxx/123 --group

否则只会下其中一个文件。


✅ 3️⃣ 补漏神器:批量链接下载

Get-Content links.txt | ForEach-Object {tdl -n archive dl -u $_ --continue}

八、tdl -n archive dl 所有你会用到的重要选项(完整表)

选项 作用
-f tdl-export.json 从导出清单批量下载
-u <链接> 直接下载某条消息
-d media 指定下载目录
--takeout 使用 Telegram Takeout 会话导出,可能降低 Flood Wait 限制
--continue 继续已有下载任务,不等同于永久去重
--restart 重新开始当前下载任务
--group 下载相册/组合消息
--skip-same 文件名(不含扩展名)和大小相同时跳过;不校验内容哈希
-t <n> 单文件线程数
-l <n> 同时下载多少个文件
-i mp4,mkv 只下载指定类型
-e jpg,png 排除某些类型
--template 自定义文件名
--desc 从新到旧下载(不推荐长期用)

九、tdl 如何判断“已经下载过”(核心机制)

这里需要区分任务续传和文件去重:

  1. --continue 用于恢复上次中断的下载任务。续传记录与任务指纹有关,任务正常完成后会清除相应记录;重新导出清单后,不应假设旧任务记录仍适用。
  2. --skip-same 检查目标目录中名称(不含扩展名)和大小相同的文件。长期追加下载应保持目录和文件名模板稳定;它不通过哈希校验文件内容。
  3. namespace 管理账号会话及该命名空间的本地数据,不是永久的“已下载 MessageID 数据库”。

改名、移动文件或变更模板会影响 --skip-same 的匹配。删除本地会话/存储可能丢失登录和任务数据,也不会自动找回被移动的文件;迁移前应同时备份会话数据、导出清单与媒体目录。


十、Telegram Desktop 要不要打开?

✅ 下载时不需要打开 Desktop。

退出应用窗口与注销账号不同;注销或撤销相关会话后,先验证 tdl 登录状态,不要假定旧凭证永久有效。

判断方法:

tdl -n archive chat ls

十一、长期维护三条铁律(一定记住)

1️⃣ namespace 永远不换
2️⃣ 一个频道一个目录
3️⃣ 追加时重新导出清单,保持目录与模板不变,并使用 --skip-same;任务中断时使用 --continue

参考:tdl 下载说明、下载命令参数。


文章作者: 0xdadream
版权声明: 本博客所有文章除特別声明外,均采用 CC BY 4.0 许可协议。转载请注明来源 0xdadream !
赏
评论

评论将在接近此处时加载,也可点击立即加载。

  目录