ECMWF数据批量下载与自动化处理：基于Python CDS API的完整实践

搞气象、气候或者环境方向研究的人，对ECMWF这套数据应该都不陌生。ERA5、ERA5-Land这些再分析资料，几乎成了很多研究场景绕不开的“标准答案”。但数据好用，下载却是另一回事——手动在网页上一次点一个变量、一年一年勾选，遇到时间序列长、区域大、变量多的需求，基本就是跟浏览器和网速较劲。我之前被这个问题折磨了很久，后来干脆用Python API做了一套ECMWF大气数据批量下载与自动化处理的流程，把提交请求、轮询状态、断点重试、格式转换、定时更新全部串了起来。这篇就把整套实践过程完整讲一遍，从一个最小可用的请求开始，到批量任务管理，再到下载后的自动化处理和高频报错排查。无论你是刚开始接触ECMWF数据的科研新手，还是想把下载流程工程化的老手，应该都能从这里找到可以直接用的思路和代码。

1. ECMWF数据下载的痛点与自动化方案选型

1.1 手动下载到底卡在哪里

先说手动下载这件事。ECMWF的Climate Data Store（CDS）网页端做得不算差，支持按变量、年份、月份、区域、格式等条件筛选数据，然后生成下载请求。听起来很简单，真正用起来就麻烦：如果你要下载30年、每天24个时次、5个变量的数据，光是在网页上组合条件就要重复几十次操作；好不容易提交了请求，还得守在电脑前等它排队、处理，然后下载。中间网络断一下、浏览器缓存满一下，整个请求可能就废了，又要重新来过。

还有一个更隐蔽的问题是“不可复现”。今天手动下载了某段时间的数据，半年后想补充同区域的另一批变量，但当时操作界面上选了哪些参数、用了什么版本的数据集，完全没记录。研究做到后面，数据溯源变成一件非常头疼的事。尤其是论文审稿时被问到“数据是怎么获取的”，如果连自己的下载方式都说不清楚，就很尴尬。

我自己第一次下载ERA5的逐小时数据时，就经历了网页端反复勾选的崩溃。后来意识到，这种批量、重复、需要可复现性的下载任务，本质上就应该交给脚本去完成。手动操作适合偶尔下一次小数据，但凡需求量上来，自动化几乎是唯一靠谱的方案。

1.2 为什么选择Python API而不是其他方式

ECMWF官方提供了一套基于Python的CDS API，也就是cdsapi库。只要注册账号、拿到API Key，就可以在脚本里构造请求，批量向服务器提交任务，然后自动下载结果。相比网页端或wget直接拉取链接，Python API的优势很明显：

• 可编程：请求参数用字典表示，变量、年份、区域可以动态生成，方便做多层循环。
• 可复现：脚本本身就是数据获取的记录，换台电脑、换个时间执行，拿到的是同一批数据。
• 可集成：下载完成后可以直接在同一个Python环境里用xarray等库做后处理，不需要文件在多个工具之间来回倒腾。
• 异常可控：网络中断、请求失败都可以在代码里捕获并重试。

有人可能会问，既然CDS有时会给出一个临时下载链接，我直接用wget或者浏览器下载器不行吗？可以，但这里有个问题：批量请求本身需要逐一提交、轮询状态，链接是动态生成的，而且有时效性。你在脚本里做循环，用cdsapi提交一个请求、等它完成、再提交下一个，这才是自然的批处理逻辑。手动复制链接再用下载器，本质上还是半自动，遇到几十个任务一样手忙脚乱。

当时我也考虑过用R语言的ecmwfr包，它也能实现类似功能。但我后续要做数据处理和可视化，Python生态里xarray、cfgrib、cdo的Python绑定用得更顺手，所以最终选了Python API作为主方案。选型这件事没有绝对的优劣，关键是跟自己的使用场景匹配。

1.3 整体流程如何设计

我在设计这套流程时，没有一上来就写一个大而全的脚本，而是先拆成几个独立的模块：

• 任务生成模块：定义要下载的数据集、变量列表、时间范围、空间区域，生成一组请求参数。
• 请求执行模块：逐个或并发提交请求，等待服务端处理，下载文件到本地。
• 异常重试模块：捕获超时、网络错误、HTTP错误，带退避策略地重试。
• 文件校验模块：下载完成后检查文件大小、尝试打开文件，避免留一个坏文件在磁盘上。
• 后处理模块：合并、裁剪、格式转换、时间重采样等。

这样拆的好处是每个模块都可以单独测试。比如任务生成模块，随便打印几个请求字典看看对不对，不用真的去请求服务器；异常重试模块也可以用模拟异常来验证。整套流程跑起来之后，维护成本很低，哪一步出问题直接看对应的日志就好。

2. 环境准备：Python环境、CDS账号与API接入

2.1 Python环境怎么搭

这一步看起来基础，但很多人（包括我早期）都栽在环境混乱上。ECMWF的cdsapi库本身依赖很少，一个干净的Python 3.8+环境就够了。如果电脑上还没有Python，建议直接装Miniconda，不要单独去系统里装一个裸Python，因为后续处理数据还会用到cdo、cfgrib等依赖，用conda管理省心很多。

安装完Python之后，用vscode或者任意你顺手的编辑器新建一个工作目录，为这个项目单独建一个虚拟环境，避免跟其他项目的包版本冲突：

conda create -n ecmwf python=3.10 conda activate ecmwf pip install cdsapi xarray netcdf4 cfgrib

如果你用的是Linux服务器，注意区分python和python3命令，以及pip和pip3的指向。直接在系统环境里pip install容易污染全局，还是那句话，用虚拟环境。Windows用户则要留意PATH设置，安装时勾选“Add Python to PATH”能省很多事。

2.2 注册CDS账号并获取API Key

使用CDS API需要一个账号。打开CDS官网，注册并登录，然后在个人页面里找到API Key相关的入口，页面上会显示你的个人URL和API Key，通常是类似下面这样的格式：

url: https://cds.climate.copernicus.eu/api key: 你的UID:你的密钥

注意这个Key一定要保密，它相当于你访问数据服务的凭证。不要把Key硬编码在脚本里然后传到公开仓库，轻则被提醒，重则被他人滥用导致账号被限制。我一般会把配置放到单独的文件，并且在.gitignore里排除掉。

2.3 安装cdsapi库并配置cdsapirc文件

cdsapi库的安装很简单，pip install cdsapi即可。接下来需要配置一个名为.cdsapirc的文件。Linux和macOS放在用户目录下，Windows放在C:\Users\你的用户名.cdsapirc。文件内容就两行：

url: https://cds.climate.copernicus.eu/api key: 你的UID:你的密钥

.cdsapirc文件的命名前面有个点，Windows资源管理器里默认可能看不到，用文本编辑器直接填写完整文件名“.cdsapirc\”新建即可。配置完成后，cdsapi会自动读取这个文件，脚本里就不用再暴露Key了。

2.4 用最小请求验证API连通性

环境配置好之后，千万不要一上来就跑大型下载任务。先发送一个很小的请求验证一下链路是否通。比如用ERA5-Land的月平均数据，选单个变量、单个月份、一个小区域：

import cdsapi c = cdsapi.Client() c.retrieve( 'reanalysis-era5-land-monthly-means', { 'variable': '2m_temperature', 'year': '2023', 'month': '01', 'time': '00:00', 'product_type': 'monthly_averaged_reanalysis', 'format': 'netcdf', 'area': [50, 110, 30, 130], }, 'test_era5_land.nc' ) print('done')

如果脚本顺利跑完，并且本地生成了一个test_era5_land.nc文件，说明账户、网络、API地址都没问题。这里我踩过一个小坑：有些数据集不支持netcdf格式只支持grib，提交前建议去数据集的文档页确认一下format支持范围。小请求通过后，再进入批量脚本的开发。

3. 批量下载脚本：从单次请求到工程化任务

3.1 理解CDS API的请求机制

在使用批量脚本之前，有必要先把CDS API的请求机制讲清楚。client.retrieve()方法做了两件事：提交一个请求给服务端，然后轮询任务状态，直到数据准备好后下载到本地。这个过程对使用者来说是阻塞的——函数不会立即返回，而是会一直等到文件下载完成，或者抛出异常。

这意味着，如果某个请求在服务端排队两小时，你的脚本就会卡在那里两小时。批量下载几十个文件，总耗时可能是几十个小时。这个特性决定了批量任务不能像普通爬虫那样一次性发一大堆请求，必须考虑服务端的队列策略和速率限制。

具体请求参数上，核心是构造一个字典，包含数据集约束的所有维度。以ERA5月平均数据为例，变量、年份、月份、时间、产品类型、格式、区域都是字典里的键。不同数据集支持的枚举值不同，比如变量名的拼写、product_type的取值，必须以数据集的文档为准。写代码之前，先花几分钟把目标数据集的资料页看一遍，能省下后面排查400错误的大量时间。

3.2 多任务批量遍历与任务清单管理

理解了请求机制，批量脚本的核心就变成了“如何生成一组请求参数，并为每个请求维护状态”。我用一个很朴素的方法：把所有要下载的数据集、变量、年份组合成一个任务列表，循环处理。

import cdsapi import os import time c = cdsapi.Client() variables = ['2m_temperature', 'total_precipitation'] years = ['2020', '2021', '2022'] months = [f'{m:02d}' for m in range(1, 13)] save_dir = './era5_downloads' os.makedirs(save_dir, exist_ok=True) tasks = [] for var in variables: for year in years: for month in months: fname = f'era5_{var}_{year}_{month}.nc' if os.path.exists(os.path.join(save_dir, fname)): print(f'skip {fname}') continue tasks.append((var, year, month, fname)) print(f'total tasks: {len(tasks)}') for var, year, month, fname in tasks: target = os.path.join(save_dir, fname) try: c.retrieve( 'reanalysis-era5-single-levels-monthly-means', { 'product_type': 'monthly_averaged_reanalysis', 'variable': var, 'year': year, 'month': month, 'time': '00:00', 'format': 'netcdf', }, target ) print(f'downloaded: {fname}') except Exception as e: print(f'failed: {fname}, error: {e}')

这个脚本里有几个细节值得说一说：

第一，任务列表可以随时重建。因为文件名是确定的，每次运行之前先检查目标文件是否已经存在，存在就跳过。这样即使中途断掉，重新执行脚本就能接着下载，不需要手动去数下载到第几个。

第二，文件名命名规则很关键。变量的英文名、年份、月份都嵌在文件名里，后期用xarray打开、合并、筛选时一目了然。文件名不规范，后面处理数据时你会花大量时间在“猜这个文件是什么”上。

第三，每个任务的try/except不能少。下载过程中可能遇到网络抖动、服务端临时报错，单独捕获异常并打印日志，不会因为一个任务失败导致整个脚本中断。

3.3 重试机制与断点续传

批量任务跑久了，你会慢慢意识到：任务中断是常态，不中断才是意外。可能某次服务器返回500，可能本地网络闪断，可能导致文件下载到一半只剩几KB。所以脚本里必须有重试和校验。

我给下载函数加了一个简单的重试包装器：

import time import random def download_with_retry(c, dataset, params, target, max_retries=5): for attempt in range(1, max_retries + 1): try: c.retrieve(dataset, params, target) if os.path.getsize(target) > 0: print(f'ok: {target}') return True else: raise Exception('empty file') except Exception as e: print(f'attempt {attempt} failed: {e}') if attempt == max_retries: raise time.sleep(10 * attempt + random.uniform(0, 3)) return False

重试间隔采用线性退避加随机抖动，避免每次失败后同时重试导致服务端压力增大。下载完成后检查文件大小只是一个最基础的校验，更稳妥的做法是尝试用xarray打开文件，确认里面不是只有空壳。对于重要的数据，我通常会额外记录一个任务清单json文件，里面保存每个任务的完成状态，这样即使脚本逻辑改动、重启机器，任务进度依然清晰。

3.4 并行下载与速率控制

前面提到CDS请求会排队，那么是不是并发越多越好？不是。CDS对每个用户有并发请求数的限制，超过限制会返回429或者排队时间急剧变长。我实测下来，串行提交请求是最稳的，适合过夜批量跑；如果确实想快一点，可以用ThreadPoolExecutor控制并发数在2到3之间，再往上就很容易触发限流。

from concurrent.futures import ThreadPoolExecutor, as_completed def handle_task(task): var, year, month, fname = task target = os.path.join(save_dir, fname) if os.path.exists(target): return f'skip {fname}' c = cdsapi.Client() params = { 'product_type': 'monthly_averaged_reanalysis', 'variable': var, 'year': year, 'month': month, 'time': '00:00', 'format': 'netcdf', } download_with_retry(c, 'reanalysis-era5-single-levels-monthly-means', params, target) return f'done {fname}' with ThreadPoolExecutor(max_workers=3) as executor: futures = [executor.submit(handle_task, t) for t in tasks] for f in as_completed(futures): print(f.result())

这里有个容易忽略的问题：每个线程里要分别创建cdsapi.Client()，不要共享同一个客户端实例，因为客户端在下载过程中会持有连接状态，多线程复用容易出问题。

4. 下载后的自动化处理：格式转换、合并与裁剪

4.1 GRIB和NetCDF格式怎么选

从CDS下载数据时，有些数据集可以直接选择NetCDF格式，有些只提供GRIB格式。GRIB是气象领域很常见的二进制格式，存储效率高，但通用性不如NetCDF。如果你只有GRIB文件，后处理前最好转成NetCDF，因为xarray、pandas这些数据分析库对NetCDF的生态支持更完善。

CDS请求参数里直接写format就行。比如ERA5-Land逐小时数据支持netcdf，ERA5的某些pressure-level数据则默认grib。如果数据集支持netcdf，建议直接请求netcdf，省去后面转换的步骤。如果只能拿到grib，就需要借助CDO工具。

4.2 用CDO批量合并与区域裁剪

CDO（Climate Data Operators）可以说是气象数据处理的神器。它的语法简洁，功能强大，合并、裁剪、插值、统计都能一条命令搞定。安装方式根据系统不同略有差异，Linux下用conda安装最方便：

conda install -c conda-forge cdo

假设我下载了某变量2020年12个月的NetCDF文件，想合并成一个完整的年度文件：

cdo mergetime era5_2m_temperature_2020_*.nc era5_2m_temperature_2020_full.nc

如果只需要某个区域的数据，可以在合并后用sellonlatbox裁剪：

cdo sellonlatbox,100,120,20,40 era5_2m_temperature_2020_full.nc era5_2m_temperature_2020_region.nc

注意sellonlatbox的参数顺序是经度范围、纬度范围，写成经度最小值、经度最大值、纬度最小值、纬度最大值。这里我曾经写反过，结果裁剪出来的区域完全不在目标范围内，折腾了半天才发现是参数顺序的问题。

CDO还支持时间筛选，比如只要夏季月份：

cdo selmon,6,7,8 era5_2m_temperature_2020_full.nc era5_2m_temperature_2020_jja.nc

把CDO命令跟Python脚本结合起来，就能实现“下载完成后自动处理”的效果。在下载循环跑完后，调用subprocess执行CDO命令，整个过程一键完成。

4.3 基于xarray进行灵活的后处理

如果你还需要做更灵活的统计分析，xarray会是比CDO更顺手的选择。xarray里的DataArray和Dataset概念，让你可以用标签来索引数据，而不是靠记忆数组维度顺序。下面是一个典型的处理示例：打开多年逐月文件，计算季节平均，然后导出为CSV。

import xarray as xr data = xr.open_mfdataset( 'era5_2m_temperature_202*.nc', combine='by_coords' ) # 按季节重采样 seasonal_mean = data['t2m'].resample(time='QS-DEC').mean('time') # 计算区域平均 area_mean = seasonal_mean.mean(dim=['latitude', 'longitude']) # 转成DataFrame并保存 df = area_mean.to_dataframe().reset_index() df.to_csv('seasonal_mean_t2m.csv', index=False) print(df.head())

xarray还有一个好处是延迟加载。open_mfdataset打开多个文件时，数据并不会全部读入内存，而是先构建计算图，等真正需要结果时才去读取。配合dask，即使数据总量超过内存，也能处理。但要注意的是，如果你的机器内存本来就不大，一次性打开上百个文件做聚合依然可能卡死，稳妥的做法是先用CDO合并成少量中间文件，再用xarray处理。

4.4 定时任务让数据自动保持更新

很多应用场景不只需要一次性下载，而是需要定期更新。比如你搭建了一个本地气象数据服务，希望每天自动拉取最新的ERA5-Land数据。这时可以写一个主脚本，把下载和执行后处理串在一起，再用系统的定时任务来触发。

Linux下用crontab：

0 3 * * * cd /path/to/project && /path/to/conda/envs/ecmwf/bin/python main.py >> logs/cron.log 2>&1

Windows下用任务计划程序，设置每天固定时间运行python主脚本即可。定时任务跑起来后，日志非常重要。我习惯每次运行都生成带日期的日志文件，方便回溯哪一次运行出了什么问题。记住：一个长期无人值守的自动化任务，没有日志等于裸奔。

这里再补充一个经验：定时更新和批量补数据最好分成两个脚本。批量补数据的任务可能一次运行几十个小时，定时更新则每天跑几分钟，两者混在一起会导致任务编排混乱，而且一旦补数据脚本某个请求卡住，每天的增量更新也会被阻塞。

5. 实测中遇到过的高频报错与排查方案

5.1 HTTP 400错误与请求参数校验失败

用CDS API下载时，我遇到最多的就是HTTP 400错误。这个错误通常意味着你提交的请求参数服务端无法解析。常见原因有：变量名拼写错误、枚举值不在允许范围内、数据集名称写错、请求了当前数据集不支持的字段。

举个具体例子。某个数据集里气温变量名叫2m_temperature，另一个数据集可能叫t2m，如果混用，服务端就会直接抛出一个schema验证错误。这类报错在日志里通常会提示是哪个字段非法，但有时候信息比较隐晦。我的排查习惯是：把这个请求的参数跟数据集的官方文档逐项对照。不要凭记忆写参数，不确定就去文档页看枚举值列表。

另外，产品类型这个字段也容易踩坑。同样是ERA5数据，不同时间分辨率的产品类型可能是reanalysis、monthly_averaged_reanalysis、ensemble_members等。取值一旦写错，即使其他参数都对，也会返回400错误。

5.2 429限流与请求排队时间过长

当你的脚本在短时间内提交了大量请求，服务端有可能返回429 Too Many Requests。这说明你提交请求的频率超过了限制。遇到这种情况，首先要做的是停止继续发请求，让队列消化一段时间，然后减小并发数，增加请求间隔。

还有一个容易被忽视的点：CDS的retrieve请求在“等待处理”阶段也会占用并发名额。你并行提交了5个任务，可能这5个任务全在排队，而队列里的其他用户也在等，导致排在你前面的任务越积越多。所以批量下载时，我建议先用串行模式跑一遍，确认平均每个任务的耗时和排队时间，再决定要不要引入并行，而不是一开始就疯狂开线程。

5.3 网络中断与下载文件不完整

批量下载动辄几十个文件，跑到一半本地网络闪断很常见。现象是某个任务下载到一半抛ConnectionError，或者文件下载完但大小异常。我早期遇到这种情况时，总是手动重新执行脚本，后来发现更坑的是：有些文件下载到了本地但实际不完整，程序却没有报错，直到后处理阶段用xarray打开时才暴露。

所以我现在严格执行两条规则：

• 下载完成后立刻检查文件大小，小于预期阈值就重试。
• 每周做一次数据完整性校验，用xarray或cdo对所有已下载文件做遍历打开，凡是打不开或者变量缺失的文件重新下载。

这两条规则配合断点续传逻辑，基本可以保证最终数据集是完整可用的。

5.4 数据量估算与磁盘空间不足

最后说说磁盘空间。ECMWF数据的分辨率很高，ERA5-Land全球数据每个格点约9公里，全球网格数量大约有两百多万个。如果下载多个变量多年逐小时数据，总数据量很容易超过几十GB甚至几百GB。我第一次估算不足，脚本跑了很久才发现磁盘满了，前面下载的文件用不上又舍不得删，非常狼狈。

下载之前先做个粗略估算：变量数 × 时间步数 × 空间格点数 × 每个值占用的字节数。比如一个温度变量，全球0.25°分辨率逐月数据，一年12个时次，占用空间不算大；但如果换成逐小时数据，一年就是8760个时次，体积直接翻两百多倍。估算完再决定是分区域下载、分时间段下载，还是只下载需要的变量。

提示：在长期运行的下载任务里，建议定期用df -h命令查看磁盘剩余空间，或者干脆在脚本里用shutil.disk_usage写一个前置检查。

5.5 高频问题速查表

6. 几点实操心得与后续扩展方向

6.1 我踩过几次坑之后的总结

整套流程跑了几个月，我最大的体会是：ECMWF的CDS API本身不复杂，真正决定项目顺不顺利的，是对任务管理和异常处理的细节把控。这里分享几个我觉得最值得记住的经验。

第一，先小后大。任何新写好的脚本，先用一个小区域、一个短时间段跑通，再扩展到全量任务。不要一上来就提交几十个大型请求，出了问题又难排查又浪费配额。

第二，日志要留全。每条下载记录、每次异常、每次重试，都要有日志输出。没有日志，批量脚本跑挂了之后你只能靠猜。我自己的项目里，日志里会记录任务名、开始时间、请求参数摘要、耗时、文件大小这些信息，配合文件名规则，后期几乎不需要手动去翻文件。

第三，任务清单要独立于脚本存在。我一般把任务列表保存成json或csv文件，脚本每次运行都读取任务清单，对比本地文件，决定哪些任务需要执行。这样即使脚本代码大改，任务进度也不会丢。

第四，文件名和目录结构一定要规范。比如按“数据集/变量/年份/文件”的层级存放，或者统一用“数据集_变量_年份_月份.nc”的格式。看似小事情，数据量起来之后，规范命名带来的效率提升非常明显。

6.2 这套流程还能往哪些方向扩展

如果后续想继续深入，我觉得有几个方向很值得尝试。一是接入消息通知，任务跑完或异常时通过邮件或即时通讯工具推送消息，长期无人值守的下载任务会省心很多。二是把下载和处理流程封装成命令行工具或者简单的Web服务，让课题组其他成员也能使用，而不需要自己去碰代码。三是在后处理阶段引入更多自动化，比如把下载好的数据直接入库，或者自动生成数据集摘要报告。

另外，ECMWF数据只是其中一环，如果研究涉及多套再分析资料对比，可以用类似的模式扩展到其他数据平台。核心思路都是通用的：任务清单管理、请求重试、文件校验、后处理自动化。当你把一套流程跑顺了之后，换数据源只是换一下请求参数的事。