tdl：Telegram 命令行工具完整指南

📖 项目介绍

项目地址：https://github.com/iyear/tdl

官方文档：https://docs.iyear.me/tdl

tdl 是一款用 Go 语言编写的 Telegram 工具集，定位是「Telegram 下载器，但又不仅仅是下载器」。它以其单文件启动、低资源占用和高速下载的特点著称。

核心特性

特性	说明
📦 单文件启动	无需复杂配置，一个文件即可运行
⚡ 低资源占用	运行时资源消耗极低
🚀 高速下载	充分利用带宽，比官方客户端更快
🔒 支持受保护聊天	可以从私有/受保护的频道下载文件
🔄 消息转发	支持自动回退和消息路由
📤 文件上传	支持将本地文件上传到 Telegram
📊 数据导出	导出消息/成员/订阅者到 JSON

适用场景

• 批量下载 Telegram 频道/群组的文件
• 导出聊天记录用于数据分析或备份
• 定时备份 Telegram 内容
• 高效管理 Telegram 媒体文件
• 社区成员/订阅者数据导出

---

🔧 安装

方式一：下载预编译版本（推荐）

前往 GitHub Releases 下载对应系统的最新版本。

Windows：

# 下载并解压
# 将 tdl.exe 放到合适的位置，或添加到 PATH

macOS：

wget https://github.com/iyear/tdl/releases/latest/download/tdl_Darwin_x86_64.tar.gz
tar -xzf tdl_Darwin_x86_64.tar.gz

Linux：

wget https://github.com/iyear/tdl/releases/latest/download/tdl_Linux_x86_64.tar.gz
tar -xzf tdl_Linux_x86_64.tar.gz

方式二：Scoop（Windows）

scoop bucket add extras
scoop install telegram-downloader

方式三：PowerShell 安装脚本（Windows）

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

方式四：从源码编译

需要 Go 1.19+ 环境：

git clone https://github.com/iyear/tdl.git
cd tdl
go build -o tdl .

安装后全局使用

# Linux / macOS
sudo mv tdl /usr/bin

# Windows (PowerShell)
Move-Item tdl.exe C:\Windows\System32

---

🚀 快速开始

基本配置

设置命名空间（每个命名空间代表一个 Telegram 账号）：

# 方式一：命令行指定
tdl -n myaccount

# 方式二：环境变量（推荐）
export TDL_NS=myaccount

设置代理（仅支持 SOCKS 协议）：

# 方式一：命令行指定
tdl --proxy socks5://localhost:1080

# 方式二：环境变量（推荐）
export TDL_PROXY=socks5://localhost:1080

设置 NTP 服务器（可选）：

# 方式一：命令行指定
tdl --ntp pool.ntp.org

# 方式二：环境变量
export TDL_NTP=pool.ntp.org

---

🔑 登录

从官方桌面客户端导入（推荐）

如果你已经有 Telegram 桌面客户端，可以直接导入会话：

# 基本导入
tdl login

# 如果设置了本地密码
tdl login -p YOUR_PASSCODE

# 指定桌面客户端路径
tdl login -d /path/to/TelegramDesktop

快速登录

# 使用 quickstart 命名空间导入桌面客户端会话
tdl login -n quickstart

# 如果设置了本地密码
tdl login -n quickstart -p YOUR_PASSCODE

# 指定自定义路径
tdl login -n quickstart -d /path/to/TelegramDesktop

使用手机号+验证码登录

# 二维码登录
tdl login -T qr

# 手机号+验证码登录
tdl login -T code

---

📥 下载

从消息链接下载

# 下载单个文件
tdl dl -u https://t.me/channel/123

# 下载多个文件
tdl dl -u https://t.me/channel/1 -u https://t.me/channel/2

从导出的 JSON 下载

Telegram 桌面客户端可以导出聊天内容为 JSON，tdl 支持直接读取：

# 从单个 JSON 文件下载
tdl dl -f result.json

# 从多个 JSON 文件下载
tdl dl -f result1.json -f result2.json

# 混合使用
tdl dl -u https://t.me/channel/1 -f result.json

下载参数

参数	说明	默认值
-t / --threads	单文件下载线程数	4
-l / --limit	最大并发任务数	2
-d / --dir	下载目录	当前目录
-s / --size	分块大小（字节）	自动
--desc	倒序下载（从新到旧）	升序

高级下载示例：

# 8 线程，512KB 分块，4 并发
tdl dl -u https://t.me/channel/1 -t 8 -s 524288 -l 4

# 指定下载目录
tdl dl -u https://t.me/channel/1 -d /path/to/downloads

# 倒序下载（从最新到最旧）
tdl dl -f result.json --desc

文件过滤

# 白名单：只下载 jpg 和 png
tdl dl -u https://t.me/channel/1 -i jpg,png

# 黑名单：排除 mp4 和 flv
tdl dl -u https://t.me/channel/1 -e mp4,flv

其他下载选项

# 根据 MIME 类型修正文件扩展名
tdl dl -u https://t.me/channel/1 --rewrite-ext

# 跳过同名同大小的文件
tdl dl -u https://t.me/channel/1 --skip-same

# 自定义文件名模板
tdl dl -u https://t.me/channel/1 \
  --template "{{ .DialogID }}_{{ .MessageID }}_{{ .FileName }}"

---

📤 上传

# 上传文件到指定聊天
tdl up -p /path/to/file.zip -c @mychannel

# 上传带标题
tdl up -p /path/to/file.zip -c @mychannel --caption "文件描述"

# 上传多个文件
tdl up -p file1.mp4 -p file2.jpg -c @mychannel

---

💬 聊天管理

查看聊天列表

# 列出所有聊天
tdl chat ls

# 查看特定命名空间
tdl chat ls -n myaccount

导出聊天记录

# 导出所有消息到 JSON
tdl chat export -c @channelname -o messages.json

# 导出消息内容和媒体
tdl chat export -c @channelname --with-content --all

按时间范围导出

时间格式为 Unix 时间戳：

# 导出指定时间范围的消息
tdl chat export -c @channelname -i 1704633600,1704719999 --with-content

# 时间戳转换：https://tool.lu/timestamp/

按消息 ID 范围导出

# 导出 ID 0-10 的消息
tdl chat export -c @channelname -T id -i 0,10 --with-content -o output.json

导出最新消息

# 导出最新的 10 条消息
tdl chat export -c @channelname -T last -i 10 --with-content

---

🔄 转发

# 转发消息
tdl forward -s https://t.me/source/123 -d @destination

# 批量转发
tdl forward -s https://t.me/source/123-130 -d @destination

---

📊 导出成员/订阅者

# 导出频道成员
tdl member export -c @channelname -o members.json

# 导出订阅者
tdl sub export -c @channelname -o subscribers.json

---

⚙️ 全局命令选项

选项	说明
--debug	启用调试模式
--delay	任务间延迟
-l / --limit	最大并发任务数
-n / --ns	命名空间
--ntp	NTP 服务器
--pool	DC 池大小
--proxy	代理地址
-t / --threads	下载线程数
--storage	存储选项

---

💡 最佳实践

避免封号风险

• 不要设置过大的线程数和分块大小
• 默认值与官方客户端一致，更安全
• 如需高速下载，逐步调高参数

# 保守配置
tdl dl -u https://t.me/channel/1 -t 4 -l 2

# 激进配置（可能触发风控）
tdl dl -u https://t.me/channel/1 -t 16 -s 1048576 -l 8

环境变量配置

建议在 shell 配置文件（如 ~/.bashrc、~/.zshrc）中设置：

# 永久设置命名空间
echo 'export TDL_NS=myaccount' >> ~/.bashrc

# 永久设置代理
echo 'export TDL_PROXY=socks5://localhost:1080' >> ~/.bashrc

# 使配置生效
source ~/.bashrc

Windows PowerShell 持久化

# 设置环境变量（当前会话）
$env:TDL_NS = "myaccount"
$env:TDL_PROXY = "socks5://localhost:1080"

# 永久设置（需管理员权限）
[System.Environment]::SetEnvironmentVariable("TDL_NS", "myaccount", "User")
[System.Environment]::SetEnvironmentVariable("TDL_PROXY", "socks5://localhost:1080", "User")

---

🔧 常见问题

Q1: 登录失败，提示「session not found」

确保 Telegram 桌面客户端已登录并设置了本地密码（如有）。

Q2: 下载速度慢

• 检查代理是否正常工作
• 尝试增加线程数：tdl dl -u URL -t 8
• 检查 Telegram 账号是否为 Premium（Premium 用户有更高下载限额）

Q3: 提示「flood wait」

Telegram 有请求频率限制，等待一段时间后重试即可。tdl 会自动处理大部分限流情况。

Q4: 如何更新 tdl？

重新下载最新版本并替换旧文件：

# Linux/macOS
wget https://github.com/iyear/tdl/releases/latest/download/tdl_Linux_x86_64.tar.gz
tar -xzf tdl_Linux_x86_64.tar.gz
sudo mv tdl /usr/bin

Q5: 如何查看帮助？

# 全局帮助
tdl -h

# 子命令帮助
tdl dl -h
tdl chat -h
tdl login -h

---

📚 相关资源

资源	链接
GitHub	https://github.com/iyear/tdl
官方文档	https://docs.iyear.me/tdl
中文文档	https://docs.iyear.me/tdl/zh/

---

本教程最后更新于 2026 年 4 月