tdl 长期维护完整最终教程（Windows）

一、tdl 的正确定位

✅ tdl 是：

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

❌ tdl 不是：

• 爬虫 / bot
• 破解工具

工作模型（必须记住）

Telegram Desktop（登录一次）
        ↓
本地 session（凭证）
        ↓
tdl 以“正常用户身份”下载

本教程使用 Telegram Desktop 会话导入方式登录。导入后下载由 tdl 自己连接 Telegram，不要求 Desktop 窗口一直打开；注销或撤销相关会话后，应重新验证 tdl 是否仍可访问账号。

二、长期维护前必须固定的 3 件事

✅ 1️⃣ 固定账号（建议一个专用老号）

• 用来下载
• 不频繁换设备 / IP

✅ 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

✅ 一个频道 = 一个目录
❌ 永远不要混

三、安装 & 登录（一次性）

✅ 1️⃣ 安装 tdl

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

验证：tdl version

✅ 2️⃣ 安装 Telegram Desktop（官网版）

• 登录一次账号
• 不要退出登录

✅ 3️⃣ 登录 tdl（一次即可）

tdl login -n archive --proxy socks5://127.0.0.1:10808

验证状态（需要代理时，查询命令也显式传入代理）：

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 -t 12 -l 1 --continue --skip-same -d media

🔍 五、补充：-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 -t 12 -l 1 --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 所有你会用到的重要选项（完整表）

九、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 下载说明、下载命令参数。