tdl 长期维护完整最终教程

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

---

一、tdl 的正确定位

✅ tdl 是：

• Telegram 官方 API 客户端
• 使用 你自己的账号（session）
• 命令行工具

❌ tdl 不是：

• 爬虫 / bot
• 破解工具

工作模型（必须记住）

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

👉 是否打开软件不重要
是否退出账号非常重要

---

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

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

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

---

✅ 2️⃣ 固定 namespace（这是下载历史的“身份证”）

tdl login -n archive

以后所有命令 必须加：-n archive

---

✅ 3️⃣ 固定目录结构（一定照做）

Text
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

---

四、第一次完整下载（初始化）

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

---

Step 1：进入频道目录

cd D:\TG-Archive\Channel_A

---

Step 2：导出聊天清单（不下载）

tdl -n archive chat export -c <频道ID或@username> --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 -d media

---

🔍 五、补充：-d media 是干什么的？

✅ 结论

-d media

表示：

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

---

✅ 不加 -d 会怎样？

默认行为是：

Text
当前目录/
└─ downloads/

---

✅ 加了 -d media 后（推荐）

如果你在：

Text
D:\TG-Archive\Channel_A

结果一定是：

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

✅ 好处：

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

👉 长期维护必须用 -d media

（目录不存在会自动创建）

---

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

❗ tdl 不会自动追踪更新
✅ 追加 = 重新 export + continue

✅ 标准追加流程（以后永远这样）

cd D:\TG-Archive\Channel_A

tdl -n archive chat export -c <频道ID> --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 -d media

✅ 老内容自动跳过
✅ 新视频自动追加
✅ 永不重复

---

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

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

---

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

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

国内环境常用：

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

---

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

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

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

---

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

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

---

八、tdl dl 所有你会用到的重要选项（完整表）

选项	作用
-f tdl-export.json	从导出清单批量下载
-u <链接>	直接下载某条消息
-d media	指定下载目录
--takeout	官方导出模式（降风控）
--continue	断点续传 + 不重复
--restart	忽略历史，全部重下
--group	下载相册/组合消息
--skip-same	文件名+大小相同跳过
-t <n>	单文件线程数
-l <n>	同时下载多少个文件
-i mp4,mkv	只下载指定类型
-e jpg,png	排除某些类型
--template	自定义文件名
--desc	从新到旧下载（不推荐长期用）

---

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

✅ tdl 不主要看文件在不在
tdl 看 MessageID + 本地状态

判断顺序：

1️⃣ MessageID + .tdl 状态（核心）
2️⃣ 文件名 + 文件大小（--skip-same）
3️⃣ 文件是否存在（最弱）

👉 所以：

• ✅ 改文件名不影响
• ❌ 删 .tdl = tdl 失忆

---

十、Telegram Desktop 要不要打开？

✅ 不需要打开、不需要运行
❌ 不能退出账号

判断方法：

tdl chat ls

---

十一、长期维护三条铁律（一定记住）

1️⃣ namespace 永远不换
2️⃣ 一个频道一个目录
3️⃣ 追加只用：export + --continue