GDC-client高效下载TCGA数据：从批量下载到断点续传全攻略-平芜编程栈

TCGA 数据下载是个老生常谈的话题，但每次组里来新人，我还是要让他们把 GDC-client 的文档从头到尾读一遍。原因很简单：网页端下载器看着方便，一旦涉及成百上千个文件，或者需要断点续传、校验完整性，网页那个“下载篮”方案基本就是给自己找麻烦。GDC-client 是 NCI 官方针对 TCGA（The Cancer Genome Atlas）数据分发系统 GDC（Genomic Data Commons）推出的命令行下载工具，本质上是把 HTTP 协议封装成了更可控的多线程任务流，专门解决大文件批量下载、中断后续传、以及文件完整性校验这些问题。适合谁用？凡是需要下载 RNA-seq 表达矩阵、甲基化芯片原始数据、拷贝数变异 segment 文件，或者 WES/WGS 的 BAM 文件的人，都应该把 GDC-client 纳入标准工作流。本文会从工具原理、环境配置、配置文件解析、命令使用到实战案例，把整个流程完整走一遍。

1. 内容整体设计与思路拆解

1.1 为什么批量下载必须放弃网页端

很多人第一次下 TCGA 数据，第一反应是打开 GDC Portal 网页，把感兴趣的病例加入购物车，然后点 Download。这个流程对下载几个文件来说完全没问题，但放到科研场景里根本不现实。举个例子，你想下载某个癌种全部样本的 RNA-seq 基因表达 STAR-Counts 结果，样本量动辄几百甚至上千，每个样本对应一个表达文件。通过网页下载，你得到的是一个一个手工保存的文件，名字还是乱七八糟的 UUID，整理起来累死人。

更关键的是，网页下载没有断点续传机制。网络稍微波动一下，下载到一半的文件直接作废，又得重头再来。我见过一个师弟下几百个文件，因为宿舍网络不稳定，点了整整一下午，最后成功落地的不足六成，剩下全是损坏的压缩包。这种体验相信不少人都经历过。

GDC-client 解决的就是这三个问题：批量调度、断点续传、数据校验。它通过读取一个 manifest 文件来获取需要下载的文件 ID、文件名和校验信息，然后多线程并发下载。整个下载过程，每一个文件都落盘到以文件 UUID 命名的子目录里，最后生成对应的.json元数据文件，方便后续追溯和管理。也就是说，只要配置得当，几百个文件可以无人值守地批量拉取，中间的失败会自动重试，实在不行还能手动补跑。

1.2 GDC-client 的工作流程和核心文件

GDC-client 的工作流程可以概括为三步：获取 manifest、配置下载参数、执行下载任务。

manifest 文件是 GDC Portal 中根据你的筛选条件自动生成的清单，本质上是一个 TSV（Tab 分隔）文件，包含四列：

id：文件的 UUID，全局唯一标识符
filename：原始文件名
md5：该文件的 MD5 校验值
size：文件大小，单位是字节

为什么要有这个清单？因为 GDC 服务器上所有文件的访问路径都是基于 UUID 生成的，文件名只是给人看的元数据。你单独知道文件名是没法直接定位到文件的，必须通过 manifest 里的 UUID 去请求 API。GDC-client 做的事就是逐行解析这个文件，然后向 GDC API 发起请求并下载文件本体。

下载完成后，每个文件目录下除了数据文件本身，还会有一个.json格式的元数据文件，记录文件的 MD5、大小、下载时间等信息。这个设计很贴心，你在后续整理数据时，不用重新回 GDC Portal 查这些信息，直接读本地 JSON 就行。

另外要理解一个关键概念：GDC 的下载接口分两种，一种是普通文件下载，一种是受控数据下载。普通数据（如 HTSeq-Counts 表达矩阵、masked 的甲基化信号）不需要认证，直接下载；受控数据（如部分 WES 的 BAM 文件、未 mask 的 VCF 文件）需要 GDC 账号申请 dbGaP 权限，并且在下载时携带 token 文件。GDC-client 的-t参数就是干这个用的。

1.3 工具选型对比：为什么是 GDC-client 而不是 gdc_get 或 API 脚本

为什么不用 Python 的 requests 库直接调 GDC API？毕竟 API 文档也是公开的，自己写脚本看起来更“灵活”。我来说说自己的体会。API 方案需要你自己处理重试机制、线程池、断点续传和校验逻辑，这些功能看起来不难，但真正做起来很容易出 bug。GDC-client 已经把这些基础能力固化进 C++ 实现里，而且是官方团队长期维护的，稳定性有保障。

至于另一个常用方案gdc_get，那是社区第三方开发的下载工具，虽然在某些场景下速度表现不错，但涉及 token 鉴权和断点续传时偶尔会出现兼容性问题。官方 GDC-client 在这些细节上做得更稳妥，尤其是处理受控数据时，token 的认证流程是官方验证过的，不容易遇到“明明有权限但下载 403”这种尴尬。

我个人的建议是：如果你只是偶尔下载十几个文件，网页端或者轻量脚本都行；但凡是下载量超过 50 个文件、或者文件本身是大体积的 BAM/FASTQ，直接上 GDC-client 不带犹豫的。

2. GDC-client 下载安装与环境配置详解

2.1 各平台下载方式与版本选择

GDC-client 官方发布的安装包支持 Windows、macOS 和 Linux 三大平台。建议直接到 GDC 官网的 Software 页面下载最新版本。截止我写这篇文章时，官方最新稳定版本为 v3.0 系列，但版本更新迭代较快，大家以官网为准。

有几个选版本时的注意事项：

如果你用的是 CentOS 7 这类比较老的 Linux 发行版，注意 glibc 版本兼容问题。新版本 GDC-client 可能在旧 glibc 环境下报错，这时候可以选择历史版本或者升级系统库。
macOS 用户注意区分 Apple Silicon（M1/M2/M3）和 Intel 芯片，官方提供的是通用版，但如果你的机器比较老，可能会出现权限问题。
Windows 用户下载的压缩包里是.exe可执行文件，不需要安装，解压即用。

这里放一个各平台下载和安装的最小操作说明：

Linux：

# 下载 tarball 包（以官方最新版本链接为准） wget https://gdc.cancer.gov/files/public/file/gdc-client_v3.0.1_Ubuntu_x64.zip # 解压 unzip gdc-client_v3.0.1_Ubuntu_x64.zip # 把二进制文件移动到 PATH 环境变量包含的目录 mv gdc-client /usr/local/bin/ gdc-client --version

macOS：

# 下载对应版本的 dmg 或 zip 包 # 如果下载后提示无法打开，需要去 系统设置 -> 隐私与安全性 中允许该应用运行

Windows：

解压 zip 包后得到gdc-client.exe，建议把整个文件夹加入系统 PATH 环境变量。具体操作是：右键“此电脑” -> 属性 -> 高级系统设置 -> 环境变量 -> 在 Path 中新增解压目录路径。不加入 PATH 也可以，只是每次调用都需要带上完整路径，比较麻烦。

安装后第一件事就是验证版本，确认二进制文件能正常运行：

gdc-client --version

正常输出类似gdc-client v3.0.1这样的信息，就说明安装成功了。

2.2 路径规划与目录结构设计

GDC-client 下载文件默认以文件 UUID 作为一级目录名，文件原始名作为二级文件名。在开始下载之前，我强烈建议你先规划好目录结构，这是很多人忽略但实际非常重要的环节。

举个反面例子。我见过有人直接在~/Downloads下面跑 GDC-client，结果整个目录全是 UUID 文件夹，后续样本整理和分析时，根本对不上哪个文件属于哪个样本。正确做法是，为每一个下载任务单独建立一个项目目录，目录名最好包含数据集信息和版本号，比如：

data/ └── TCGA-LUAD/ ├── manifest_20240101.txt └── gdc_download/ ├── 00022d47-1a3d-4b11-8a52-9fbf7f1c0f1b/ │ ├── 1a9c9e0d-8b0f-4db5-a75f-... .txt │ └── 00022d47-... .json └── 00a6e71d-0ae9-4f5e-9a3f-... / ├── 3c1a2e3b-... .txt └── 00a6e71d-... .json

这样设计的好处是，后续不管你用 R 还是 Python 处理数据，都能根据父目录名快速定位到样本对应的文件。此外，建议在下载完成后保留 manifest 文件副本，作为这次数据批次的身份标识。GDC 数据库版本升级后，同样的筛选条件重新生成的 manifest 可能略有差异，保留旧版 manifest 可以方便审计和复现。

2.3 网络环境要求与断点续传的理解

GDC 的下载服务器部署在 AWS 上，域名为api.gdc.cancer.gov和gdc-api.nci.nih.gov。国内用户下载时经常遇到速度慢或者连接中断的问题，这个不是 GDC 服务器的问题，而是跨境网络链路质量不稳定导致的。

如果你也是这种情况，可以尝试两个办法：

使用代理。在 GDC-client 命令中通过环境变量HTTPS_PROXY指定代理地址，适合有实验室代理或者云服务器代理的情况。
错峰下载。美东时间白天对应北京时间凌晨，这个时段跨境链路相对空一些，下载速度通常会有明显改善。

但不管网络多差，GDC-client 的断点续传机制都能让你省心不少。它的实现原理是：下载每个文件时，先创建一个对应的临时文件（后缀为.part），下载过程中持续写入，同时记录当前已下载的字节数。如果下载中断，下次运行相同命令时，工具会检测到.part文件的存在，并从断点继续下载。完整下载完成后，.part文件会被重命名为目标文件。所以，中间网络断了或者命令被 Ctrl+C 中断，都不需要惊慌，重新跑一次命令即可续传。

这里有一个经验之谈：某些文件在下载过程中如果长时间没有新的数据写入，可能会被服务器判定为超时而断开连接，GDC-client 默认会在一定时间后自动重试。你可以通过调整下载参数来优化重试行为，这个我在后面结合具体命令讲。

3. GDC 数据检索与 manifest 文件生成

3.1 在 GDC Portal 上筛选数据并生成清单

manifest 文件的生成是使用 GDC-client 之前最重要的一步，也是最容易出错的一步。因为你选的数据范围直接决定了下载内容的对与错。

访问 GDC Portal（portal.gdc.cancer.gov），点击页面顶部“Repository”进入数据仓库页面。在这里你可以通过左侧的筛选器来限定数据范围，包括：

Primary Site：原发部位，如 Lung、Breast、Colorectal
Project：具体项目编号，如 TCGA-LUAD、TCGA-BRCA
Data Category：数据类别，如 Transcriptome Profiling、Copy Number Variation
Data Type：数据类型，如 Gene Expression Quantification、Masked Copy Number Segment
Experimental Strategy：实验策略，如 RNA-Seq、WXS、WGS
Workflow Type：分析流程，如 STAR-Counts、STAR - Gene Quantification（这个选项在转录组数据中很常用）

把筛选条件设置好之后，页面会列出符合条件的文件清单，同时显示总数和总体积。在这一步，我强烈建议你先看一眼“总体积”，因为它直接决定了你的下载时间。比如筛选出两三百个 BAM 文件，体量很可能达到数百 GB，你得确认自己的磁盘空间是否足够。

确认文件清单没问题后，点击“Manifest”按钮，浏览器会自动下载一个.txt文件。这个文件就是 GDC-client 下载时需要读取的清单文件。默认文件名通常是gdc_manifest_日期.txt，格式如下：

id filename md5 size 00022d47-1a3d-4b11-8a52-9fbf7f1c0f1b 01a2d3e4-..._counts.txt abcdef1234567890abcdef1234567890 123456

3.2 理解 manifest 的关键字段

manifest 文件看似简单，但四个字段都很有讲究：

id是文件 UUID，这是 GDC 内部文件的主键，也是 GDC-client 访问服务器的钥匙。filename只是给你看的样本文件名，它往往是UUID_基因注释来源的形式。这里有个小注意点：GDC 不同时间段处理的样本，文件名后缀格式可能不太一样。比如有些是.htseq.counts.gz，有些是.tsv.gz，这跟 GDC 的处理流程版本有关，不影响你下载，但后续读入数据时要注意匹配。

md5是文件内容的 MD5 哈希值，用于校验下载文件的完整性。GDC-client 在下载完成后会自动计算本地文件的 MD5 并与 manifest 中的值比较，不一致的话会判定下载失败并重新下载。

size是字节大小。有时候筛选条件相同、时间点不同的两次下载，size 值也会有细微差异，这与 GDC 数据的版本更新有关。所以在博文、论文中分析 TCGA 数据时，最好明确记录数据下载日期和 GDC 数据版本，否则后续别人复现你的分析时可能对不上结果。

3.3 使用 API 自动生成 manifest（进阶用法）

除了在网页端手工生成 manifest，GDC 还提供了一套 REST API，让你可以用脚本方式自动化获取清单。这对于需要同时处理多个癌种或者多组数据的用户特别有用。

比如你想查询 TCGA-LUAD 项目中所有 RNA-Seq 的 STAR-Counts 基因表达文件，可以用如下 API 查询：

curl -X POST "https://api.gdc.cancer.gov/files" \ -H "Content-Type: application/json" \ -d '{ "filters": { "op": "and", "content": [ { "op": "in", "content": { "field": "cases.project.project_id", "value": ["TCGA-LUAD"] } }, { "op": "in", "content": { "field": "files.experimental_strategy", "value": ["RNA-Seq"] } }, { "op": "in", "content": { "field": "files.analysis.workflow_type", "value": ["STAR - Counts"] } } ] }, "fields": "file_id,file_name,md5sum,file_size,cases.submitter_id", "format": "TSV", "size": 10000 }' \ -o manifest_TCGA-LUAD.txt

这种方式适合后续要写 pipeline 的用户，一次性集成到流程里，避免每次都在网页上手工点筛选器。不过提醒一下，fields参数中字段名要注意大小写和分隔符，比如 GDC 用md5sum而不是md5，返回的 TSV 表头和 manifest 略有差异，需要简单处理一下再给 GDC-client 使用。

4. GDC-client 核心命令详解与实操记录

4.1 download 命令的参数说明与实战

GDC-client 最核心的命令就是download，它的基本用法如下：

gdc-client download -m manifest_file.txt -d 下载目录

-m参数指定 manifest 文件路径，-d参数指定下载目录。如果省略-d，默认下载到当前目录。这个命令会读取 manifest 中所有条目，然后并发下载。

常用参数一览：

参数	含义	注意事项
`-m`	指定 manifest 文件	必选参数
`-d`	指定下载目录	建议设置为项目目录下的`gdc_download`子目录
`-t`	指定 token 文件	下载受控数据时必须携带
`-n`	并发下载任务数	默认 1，建议根据网络情况调整
`-r`	重试次数	默认 0，建议设置为 3-5
`-s`	分片下载开关	默认不开启，开启后可提高大文件下载速度
`--no-related-files`	不下载关联文件	默认会下载所有关联文件

实际运行中，一个典型的多文件下载命令是：

gdc-client download -m gdc_manifest_20240101.txt -d ./gdc_download -n 8 -r 5

这里的关键参数是-n和-r。-n控制并发数量，太小速度慢，太大容易触发 GDC 服务器的限流或导致连接中断。我实测下来，国内网络环境-n 4左右比较稳妥；如果是在海外节点或者代理环境，-n 8甚至-n 12都能稳定跑。-r控制在单个文件下载失败后的重试次数，建议至少设置 3 次，网络不稳定时可以加大到 8 次。

4.2 使用 token 下载受控数据

TCGA 数据库中，部分数据属于受控访问级别，比如某些未汇总的 VCF 文件、BAM 原始文件，需要先申请 dbGaP 授权，然后在 GDC 官网生成 token 文件。下载这类数据时，必须带上 token：

gdc-client download -m manifest_controlled.txt -d ./gdc_download -t gdc-user-token.2024-01-01.txt

token 文件本质是一串加密令牌，GDC-client 会把它的内容放在 HTTP 请求的 Header 中完成身份认证。这里有几个关键经验分享：

token 文件是有有效期的，一般是三个月。过期后下载会报 401 错误，这时候需要去 GDC Portal 重新生成。
token 文件关联的是你的 GDC 账号，不要随意分享给他人，也绝对不要上传到 GitHub 等公开仓库。
每次下载受控数据前，建议先确认 token 文件格式是否正确。直接cat一下 token 文件，如果看到的是{"token": "..."}的 JSON 格式，就没问题。
一个常见错误是 Windows 用户直接在 PowerShell 里执行命令时，token 文件路径带了空格或者反斜杠，导致解析失败。建议把 token 文件放在项目根目录，用相对路径来引用。

4.3 upload 命令和其他辅助命令

GDC-client 的另一个常用命令是upload，用于向 GDC 上传数据。这个命令主要面向数据提交方，比如你要向 TCGA 以外的项目提交测序数据，就可能用到。基本格式是：

gdc-client upload --path /path/to/upload_folder --token gdc-user-token.txt

上传数据时也会自动做 MD5 校验，保证数据完整性。不过对绝大多数科研人员来说，upload 命令很少用到，了解有这回事就行。

除了上传下载，GDC-client 还有一条很有帮助的信息查询命令：

gdc-client --help

这条命令会列出所有可用命令和参数说明。当你忘记参数时，可以直接在终端查，不用翻文档。

4.4 下载过程日志解读与状态分析

GDC-client 在下载时会实时输出日志，很多人看到一堆日志就发慌，其实日志信息非常有价值。我来教你怎么读懂它。

典型日志输出大致是这样的：

Output directory: gdc_download 12:00:01 INFO Downloading: 00022d47-1a3d-4b11-8a52-9fbf7f1c0f1b (1/10) 12:00:03 INFO Download complete: 00022d47-1a3d-4b11-8a52-9fbf7f1c0f1b 12:00:03 INFO Downloaded 10 files successfully; 0 errors

如果某个文件下载失败，日志会显示类似信息：

12:05:17 ERROR Failed to download: 00a6e71d-...: Cannot connect to host 12:05:17 INFO Retrying in 5 seconds... (attempt 1/5)

这里要注意的信息是“attempt X/Y”，Y 就是-r参数指定的重试次数。如果 Y 次都失败了，就说明这个文件的连接问题比较顽固，光靠 GDC-client 自己重试解决不了，需要检查网络或者代理。

还有一个常见的日志情况是：

12:10:22 WARNING An error occurred while trying to download a file: 418

这个 418 状态码有点特殊，一般是 GDC 服务器认为请求异常（比如并发太高触发了限流保护）。遇到这种情况，降低-n并发数后重新运行即可。

4.5 常见问题与排查技巧实录

问题一：证书验证失败

在部分 Linux 环境下，运行 GDC-client 可能提示 SSL 证书验证失败。这是因为系统缺少对应的 CA 证书根目录。解决办法很简单：

yum install ca-certificates -y # CentOS/RHEL apt install ca-certificates -y # Ubuntu/Debian

问题二：gdc-client: command not found

这是 PATH 环境变量没有包含 GDC-client 二进制文件所在目录导致的。重新检查一下文件是否真的下载成功，以及 PATH 配置是否正确。临时用一下可以写绝对路径，比如/usr/local/bin/gdc-client。

问题三：Windows 系统杀毒软件拦截

Windows Defender 或者其他杀毒软件有时会把 GDC-client 的下载行为误判为异常活动，导致下载进程被强制终止。如果出现莫名其妙的中断问题，可以先把杀毒软件实时防护临时关闭，或者把 GDC-client 所在目录加入白名单。

问题四：下载目录磁盘空间不足

manifest 文件里每个条目有一个 size 字段，你可以把所有条目的 size 加起来，估算总下载体积。下 BAM 文件的时候，几百 GB 的数据量很常见，磁盘空间不够会导致失败。建议下载前先在项目目录里跑一下df -h看剩余空间。

问题五：manifest 文件行尾符问题

Windows 用户可能碰到过一个隐藏坑：用记事本编辑过 manifest 文件后，文件行尾变成 CRLF，导致 Linux 上的 GDC-client 解析失败。处理方法很简单，用 dos2unix 转换一下：

dos2unix gdc_manifest_20240101.txt

4.6 Windows 下 CMD 而非 PowerShell 的坑

这是一个专门想拿出来说的经验。在 Windows 环境下运行 GDC-client，官方支持的是 CMD（命令提示符），而不是 PowerShell。在 PowerShell 中直接运行gdc-client时，可能会因为执行策略或控制台代码页的问题，导致输出的日志中文乱码或者参数传递异常。我之前排查过一例：同样的命令 paste 到 PowerShell 里，文件就是下载不下来，切到 CMD 一切正常。

如果你习惯用 PowerShell，也不是完全不能用。可以显式调用 cmd 来执行命令：

cmd.exe /c "gdc-client download -m manifest.txt -d gdc_download"

不管用哪种终端，我都不建议在路径里带空格或中文，免得字符编码问题干扰日志解析。

5. 从下载到整合：数据落地后的整理与验证

5.1 下载完成后的目录检查与 MD5 校验

很多人在 GDC-client 完成下载后，直接从 UUID 目录里把文件复制出来就开工了，我建议先做一次整体检查。方法很简单，用自带命令行工具对所有子目录的.json元数据文件的md5字段和实际文件比对一下就行。

如果你不想写脚本，也有个简单的手工方式。GDC-client 在日志里会显示“Downloaded X files successfully； 0 errors”，如果 errors 不为 0，就说明有文件没下成功。这时候可以直接重新运行一次相同的下载命令，它会自动跳过已下载且校验通过的文件，只补下缺失或损坏的文件。

重新补下命令的便捷性，是 GDC-client 节省时间的一大原因。因为它会读取已有文件目录里的.json元数据，判断哪些文件已经存在且 MD5 校验通过，从而跳过这些条目，只处理剩余部分。对于网络不稳定的环境来说，这个特性特别实用。

5.2 文件映射：从 UUID 找到样本名

GDC 下载下来的文件夹是 UUID，虽然对机器友好，但人的可读性很差。为了后续分析方便，你通常需要把 UUID 映射回 TCGA 样本的 barcode。怎么做？

最常用的方案是通过 GDC API 查询每个文件 UUID 关联的病例信息：

curl -X POST "https://api.gdc.cancer.gov/files" \ -H "Content-Type: application/json" \ -d '{ "filters": { "op": "in", "content": { "field": "files.file_id", "value": ["00022d47-1a3d-4b11-8a52-9fbf7f1c0f1b"] } }, "fields": "file_id,file_name,cases.submitter_id,cases.samples.sample_type,cases.samples.submitter_id", "format": "TSV" }'

返回结果会包含 sample submitter_id 和 sample type。把这些信息保存成一个映射表，后续分析时会非常有用。我习惯在下载完数据后，就直接生成一个file_to_sample.tsv映射文件，这样每次处理数据都省去查 API 的时间。

5.3 用 R 或 Python 读取下载文件的简单示意

数据整合到这一步，就可以进入正式分析了。比如说，你想把某个癌种所有样本的基因表达文件合并成一个表达矩阵。RNA-seq 的 STAR-Counts 结果是一个 TSV 文件，一般行是基因 ID（Ensembl ID），列是对应样本的表达量。Python 遍历目录里的所有文件并合并的代码可以参考：

import pandas as pd import glob files = glob.glob("gdc_download/*/*.tsv") expression = [] for f in files: df = pd.read_csv(f, sep="\t", index_col=0, header=None, names=["gene_id", "count"]) sample_id = f.split("/")[1] # 用 UUID 目录作临时 ID df.columns = [sample_id] expression.append(df.iloc[:, 0]) expr_matrix = pd.concat(expression, axis=1) expr_matrix.columns = [f.split("/")[1] for f in files] expr_matrix.to_csv("expr_matrix_counts.tsv", sep="\t")

需要注意的是 STAR-Counts 标准输出里包含一些特殊行（比如___no_feature、___ambiguous等统计行，以__开头），合并前建议先过滤掉。另外，GDC 提供的注释文件包含 gene_id 和 gene_name 的映射关系，做差异分析时往往需要做一次 ID 转化，这也是一个常规操作了。

5.4 线下存档与版本管理建议

最后说一个实操中很多人忽略的问题：TCGA 数据库本身会随着时间推移而不断更新数据版本。半年前下载的数据和现在下载的数据，在同样的筛选条件下，文件版本可能不同，这会影响你的分析结果的可复现性。

因此建议每个下载任务完成后，把以下文件一并归档保存：

manifest文件（标识这次数据的文件清单）
GDC Portal 筛选条件截图或者 JSON 配置文件
下载日期记录
数据版本号（Portal 页面底部通常会显示，如 GDC Data Release 40.0）

这样存档一年后再被别人问起“你这数据什么时候下的？哪个版本？”的时候，你能快速给出准确回答。科研数据的管理，严谨是第一位。

6. 大文件下载的分片策略与逻辑

6.1 分片下载的工作原理

GDC-client 从 v1.4 开始支持分片下载（range request）。传统下载是把一个文件作为一个整体，从头拉到尾；分片下载则是把一个文件切成多个固定大小的片段，并发地去拉取不同片段，最后在本地合并。

这个机制对大文件特别有效，尤其是 BAM 文件动辄几 GB 甚至几十 GB 的场景。单个连接传输受限于带宽和延迟，分片后理论上可以并行利用更多带宽，显著提升下载速度。

开启分片下载的方法是在命令中加-s或者--slicing：

gdc-client download -m manifest.txt -d gdc_download -s

默认分片大小一般不用调整，用默认值即可。但如果你在日志里看到某些分片反复失败，可能和网络路径稳定性有关，可以考虑关闭分片、回到普通模式下载。

6.2 大文件下载时内存和磁盘的占用

分片下载会临时产生多个.part文件碎片，这些碎片存在同一个目标文件夹里。如果你的磁盘空间只剩几十 GB，千万别启动分片下载大 BAM 文件，因为分片数据合并前会占用额外的临时空间，极容易把磁盘撑爆。

还有一点需要留意，分片下载对系统内存占用比普通模式略高。如果服务器内存比较小（小于 4GB），不建议同时把并发数和分片都开满。实测下来，在 4GB 内存的云服务器上，-n 4加上-s基本就是内存占用的安全上限了。

6.3 何时不需要分片

下载小文件（几十到几百 MB）时，分片带来的性能提升几乎可以忽略不计，反而可能因为分片多、校验开销大，导致整体速度变慢。所以如果你下载的是表达矩阵、甲基化信号文件这类小体量数据，直接不带-s参数即可。

7. 自动化批量下载：集成进分析流程的思路

7.1 Shell 脚本自动批量下载多个项目

生物信息分析流程中，一次性下载多个项目是常有的事。比如你同时要 TCGA-LUAD、TCGA-LUSC、TCGA-BRCA 三个项目的数据，只要把三个 manifest 文件分别准备好，写一个简单的循环脚本就能自动处理：

#!/bin/bash for project in LUAD LUSC BRCA; do gdc-client download \ -m manifest_${project}.txt \ -d data/${project} \ -n 4 -r 5 \ --log-file log_${project}.txt done

注意--log-file参数，可以把日志写入文件而不是只输出到终端。这样你可以挂一个nohup或者后台任务，跑完后再统一查看日志，不用一直盯着终端窗口。

7.2 定时任务与增量更新

TCGA 数据库不是静止的，每隔一段时间会发布新的数据版本。如果项目在做长期追踪分析，可以利用 crontab 写一个定时任务，每月拉取最新数据。但这里要强调一个原则：不要直接在原来的下载目录上更新，而是建议新数据放到新目录，通过比较 manifest 文件的内容来判断哪些文件新增了、哪些文件版本变化了。这样做的好处是，旧版本的文件不会被覆盖，分析结果可以保持可追溯性。

7.3 并发数与网络带宽的平衡

最后把并发参数再说透一点。-n不是越大越好。GDC 服务器对每个 IP 的并发连接数有限制，当你把-n拉到 20 以上，大量连接同时建立，很容易触发服务器的限流机制，表现为任务反复卡住、速度反而下降。

一个比较稳的参数选择思路是：

普通项目文件（每个小于 100MB）：-n 8
大文件（BAM、FASTQ）：-n 4加上-s
网络信号不稳定（丢包率较高）：-n 2或-n 3，优先保证完整率

我自己的经验是，稳定比速度更重要。下载中断后虽然可以续传，但每次重试都要重新建立连接、重新验证元数据，花在“返回去处理失败任务”上的时间，往往比一开始稳着下载多得多。

8. 数据校验与整理后的最后一步：归档备份

8.1 检查下载日志确保零错误

下载完成后，第一件事不是处理数据，而是确认日志中没有错误。推荐做法是执行完下载命令后，手动 grep 一下日志里的错误信息：

grep -iE "error|fail" log_download.txt

如果没有任何输出，说明所有文件都下载成功了。如果还有少量 error，直接重新运行下载命令，让它自动补下那些失败的文件。

8.2 快照文件清单与最终数据管理

所有文件下载并验证完成后，生成一份完整的文件清单：

find gdc_download -type f -name "*.json" > download_metadata.txt

这份清单配合 manifest 文件保存在一起，作为数据包的“身份档案”。以后不管谁拿这批数据去分析，只要对照清单，就能确认数据来源和完整性。

8.3 长期归档时的压缩策略

如果你需要把这批数据放到实验室共享存储或者对象存储中，建议不要直接压缩整个目录，因为 UUID 目录嵌套层次深、文件数量多，tar 起来效率不高，而且后续要单独取某个文件时还得先解压。

更好的办法是维持目录结构不变，把整个父目录放入对象存储桶，再用单独的文本清单来管理元信息。这样既保留了 GDC-client 原本的目录组织方式，又方便后续对单文件做快速访问。

我这里再说一个小心得：给数据备份时，可以把每个 UUID 目录里的.json文件里记录的 MD5 值和对象存储返回的 ETag 做一次比对，如果对得上，说明备份过程数据没有损坏，这个环节能帮你避免很多“备份完才发现数据坏了”的糟心事。

9. 从下载到产出：一个完整的 TCGA 转录组数据实操复盘

前面把 GDC-client 的原理、安装、参数和常见问题都说了一遍，这一节我拉一个真实场景，带大家把整个流程串一遍，也方便你们对照自己的操作。

9.1 场景设定与数据范围

假设我们要下载 TCGA-LUAD（肺腺癌）的 RNA-seq 基因表达数据，具体条件是：

数据类别：Transcriptome Profiling
数据类型：Gene Expression Quantification
实验策略：RNA-Seq
分析流程：STAR - Counts
文件格式：TSV

在这个条件下，GDC Portal 会筛出满足条件的全部文件。

9.2 操作步骤实录

第一步：在 GDC Portal 筛选并下载 manifest

进入 Repository 页面，左侧筛选器按上述条件逐个勾选，右侧列表会自动刷新。点击 Manifest 按钮，下载得到gdc_manifest_20240101.txt。

第二步：预估数据量

用文本编辑器或者终端查看 manifest，统计文件个数和总大小：

awk -F'\t' 'NR>1 {sum+=$4} END {print NR-1 " files, " sum/1024/1024/1024 " GB"}' gdc_manifest_20240101.txt

这一步的目的是在下载之前就确认磁盘空间是否足够。

第三步：执行下载

在项目目录中运行：

gdc-client download \ -m gdc_manifest_20240101.txt \ -d ./gdc_download \ -n 8 \ -r 5 \ --log-file log_download_20240101.log

下载过程中观察日志输出，了解实时进度。

第四步：校验并整理

下载完成后，检查日志错误：

grep -iE "error|fail" log_download_20240101.log

确认没有报错后，进入gdc_download目录，检查目录结构和数量是否与 manifest 一致。

第五步：生成文件映射表

调用 GDC API，将 UUID 映射到样本 barcode，并保存为映射表。后续 R/Python 分析直接读取映射表即可完成样本 ID 转换。

这一套流程走下来，一个转录组表达数据的下载任务就算完整结束了。整个过程大约十分钟的操作时间，剩下就是等待下载完成。

9.3 进阶：批量合并表达矩阵的脚本

数据下载并且映射表生成好后，合并表达矩阵就非常简单了。这里给一个稍微完整一点的 Python 脚本，按映射表重命名样本列：

import pandas as pd import glob # 读取 UUID 到样本名的映射表 mapping = pd.read_csv("file_to_sample.tsv", sep="\t", index_col=0) expr_list = [] for f in glob.glob("gdc_download/*/*.tsv"): uuid = f.split("/")[1] if uuid not in mapping.index: continue df = pd.read_csv(f, sep="\t", index_col=0, comment="#") df = df[~df.index.str.startswith("_")] # 过滤掉统计行 sample_name = mapping.loc[uuid, "sample_submitter_id"] df.columns = [sample_name] expr_list.append(df) matrix = pd.concat(expr_list, axis=1) matrix.to_csv("TCGA_LUAD_star_counts_matrix.tsv", sep="\t")

合并后的表达矩阵就能直接用于差异表达分析、生存分析特征筛选等下游工作了。以后每年 GDC 数据版本更新，只需重新走一遍下载流程，替换映射文件，就能快速产出最新版本的表达矩阵，很方便。

10. 写在最后：几个实战中的细节体会

操作过很多次 GDC 数据下载之后，我想单独强调几个容易踩坑但很少被文档提到的细节。

下载窗口期的问题。GDC 的数据并不是绝对静态的，官方会不定期发布数据版本更新。同一份 manifest，过几个月重新下载，可能会发现文件版本和之前有细微差异。所以你的分析结果如果想保持稳定可复现，最好把“数据下载日期+数据版本号”写进论文的方法部分。

关于并发数，真的不要贪。我见过有人为了追求速度把-n调到 50，结果大量文件反复失败，最后花在排查上的时间比省下来的时间还多。做科研下载数据，稳定压倒一切。

token 文件的管理要养成习惯。很多人下载受控数据时临时生成 token，用完就随手删了，等下次需要时又找不到。建议统一放在一个~/.gdc_token/目录下，按日期命名，比如gdc-user-token.2024-01-01.txt，同时把这个目录做好权限控制。

还有一个容易被忽略的小问题：GDC-client 下载的目录是 UUID，但部分下游分析工具（比如某些 R 包）需要你按 TCGA barcode 来组织文件。这个转换可以在数据下载后立刻做，也可以在分析代码里动态做，但千万不要把 UUID 目录里的文件复制出来重命名后再删除原目录，因为一旦后续需要核对 MD5，失去原目录结构会让你非常被动。

如果你刚接触 TCGA 数据下载，我建议先在本地挑一个小规模的 manifest（比如 10 个文件以内）测试一遍流程，确认网络、工具、参数都没问题后，再跑全量数据。毕竟几百个文件下载到一半出问题，排查的代价还是要比一开始多花十分钟测试高得多。