google-earth-engine

Google Earth Engine

用途：正确使用 GEE 的服务端模型。常见失败模式包括客户端与服务端混淆（在循环中调用 .getInfo()、对服务端对象使用 Python if）、无界计算（未缩放的归约导致超时）以及静默使用默认比例尺（以错误分辨率计算统计数据）。

这项工作适合在这里运行吗？—— Earth Engine 与本地计算

编写任何 ee. 代码之前，先回答这个问题。决策取决于六个方面，缺少这些信息就无法判断，因此请先确认它们——可以同时询问并给出暂定建议，但不能只给建议而不询问：

1. 档案范围与时长——面积，以及覆盖多少年、重访频率如何。这决定了服务端计算是否值得承受其限制；单景影像则不值得。
2. 算法可表达性——能否将工作写成掩膜、归约器和波段运算？任何需要任意逐像素迭代、自定义求解器，或依赖 GEE 不支持的 Python 库的工作，都应在本地进行。
3. 数据位置与敏感性——受限数据或离线数据无法上传，无论规模多大，这都会直接决定结果。
4. 交互式限制与批处理——参见配额与使用规范。任何超过约 5 分钟交互式请求限制的任务，都必须从一开始就设计为批量导出，而不是等 getInfo 超时后再改造。
5. 导出量——实际需要取回什么：少量归约统计数据，还是需要在本地存储并重新处理的全分辨率逐像素数据堆栈。
6. 可复现性成本——转为服务端计算的实际代价。目录版本可能发生变化，而且计算不会在本地留下记录，因此选择 GEE 就意味着必须提供来源记录。推荐 GEE 时要说明这项成本；遗漏这一点的建议并不完整。

只有在第 1 和第 2 项支持使用 Earth Engine，且第 3 项允许时，才推荐使用它。如果确实难分伯仲，请明确说明，并指出决定性问题，不要默认选择本技能所介绍的平台。xee 和 STAC + stackstac / odc-stac 是值得提及的折中方案：访问目录数据，在本地计算。

心智模型——一切都是延迟执行的

ee.Image、ee.ImageCollection、ee.FeatureCollection 都是服务端描述，而非数据。只有请求输出时（getInfo、导出、地图切片）才会进行计算。由此可得：

• 绝不要对服务端值使用 Python if/for——应谨慎使用 ee.Algorithms.If，优先使用 .map() + 筛选器。逐个元素调用 .getInfo() 的 Python 循环是 GEE 性能问题中的头号元凶。
• .getInfo() 会阻塞并传输数据；仅用于少量标量。 任何规模较大的数据 → 导出（到 Drive/GCS/Asset）。
• 使用 .aggregate_array()、.first()、.limit(3) 探查并调试——不要直接打印整个集合。

标准流程（Sentinel-2 无云合成影像）

import ee
ee.Initialize(project="my-project")

aoi = ee.Geometry.Rectangle([27.0, 38.3, 27.4, 38.6])

def mask_s2(img):
    # Cloud Score+ is the current best practice (threshold ~0.5-0.65)
    cs = img.linkCollection(csplus, ["cs_cdf"]).select("cs_cdf")
    return img.updateMask(cs.gte(0.6))

csplus = ee.ImageCollection("GOOGLE/CLOUD_SCORE_PLUS/V1/S2_HARMONIZED")
s2 = (ee.ImageCollection("COPERNICUS/S2_SR_HARMONIZED")
      .filterBounds(aoi)
      .filterDate("2025-05-01", "2025-09-30")
      .map(mask_s2))
composite = s2.median().clip(aoi)
ndvi = composite.normalizedDifference(["B8", "B4"]).rename("ndvi")

集合选择：S2_SR_HARMONIZED（对 2022 年之后的偏移进行协调处理），LANDSAT/LC08/C02/T1_L2 及相关集合（应用缩放因子：光学数据 *0.0000275 - 0.2），用于日尺度/粗分辨率数据的 MODIS/061/...，以及用于气候数据的 ERA5-Land。在交付物中记录集合 ID 和日期筛选条件。

归约器与分区统计——比例尺不可省略

stats = ndvi.reduceRegions(
    collection=districts,
    reducer=ee.Reducer.mean().combine(ee.Reducer.stdDev(), sharedInputs=True),
    scale=10,                    # ALWAYS explicit — native resolution
    tileScale=4,                 # raise when "computation timed out"
)

• 在某些流程中，scale 默认为地图缩放级别——会静默地产生粗略统计数据。始终将其设为数据的原生分辨率（或注明有意采用的降尺度）。
• bestEffort=True 会静默降低比例尺以满足限制——分析时应避免；优先使用 tileScale + 导出。
• 大规模归约 → 使用 Export.table.toDrive，不要使用 .getInfo()。
• 加权与非加权归约器在多边形边缘的处理不同（统计完整像元数量时使用 .unweighted()）；请注明所用方法。

时间序列

• 使用映射函数遍历日期的 ee.List.sequence，构建逐时段合成影像（月度／季节中位数），然后再进行归约——不要导出之后还要聚合的每日影像栈。
• 对于逐像素趋势：使用 ee.Reducer.sensSlope()（稳健）或 linearFit；对于物候分析，使用谐波回归（通过 .addBands 添加正弦／余弦项）。根据有效观测数量进行掩膜——在 200 个可能值中仅有 4 个像素得出的趋势只是噪声；请报告数量波段。
• 对于存档尺度的断点检测（GEE 提供 LandTrendr/CCDC），方法选择遵循 change-detection。

在 GEE 中分类

ee.Classifier.smileRandomForest 可应对大多数情况。通过 image.sampleRegions 获取训练样本；按空间划分训练集／测试集（添加网格单元属性并筛选——随机 randomColumn 划分会造成数据泄漏；参见 ml-experiment-standards → references/spatial-cv-protocol.md）。从 errorMatrix 报告每个类别的准确率；基于分类地图进行面积估算时，仍需进行基于抽样设计的调整（change-detection / Olofsson）。

导出与交接

• 使用 Export.image.toDrive/toCloudStorage，并显式指定 region、scale、crs、maxPixels；当需要与现有栅格进行像素对齐时，使用 crsTransform。
• 导出超过约 10⁸ 个像素时：按瓦片拆分，或使用 toAsset 作为中间步骤。
• 通过导出 COG，交接给本地 Python 技术栈（rasterio/xarray）；也可以使用 xee 以原生方式访问 xarray；使用 geemap 进行交互式可视化。

配额与使用规范

批处理任务会排队（请检查任务状态；不要不加判断地一次提交数百个任务）。 交互式请求约在 5 分钟后超时——长时间任务请使用批量导出。 如果工作流会重复使用中间产品，请将其缓存为资产。

溯源记录

服务器端计算事后无法追溯：目录可能在你处理时发生变化，归约器的默认值可能改变结果，而导出文件中不会记录它使用了哪个存档。每项 Earth Engine 交付物都应附带溯源记录，以旁置 JSON 文件的形式与导出文件一同生成——而不是留在笔记本中：

• 目录资产 ID 及其版本后缀（COPERNICUS/S2_SR_HARMONIZED 和具体的集合版本），以及应用的日期范围和筛选条件。
• 掩膜方法和阈值——云概率来源、阈值，以及任何形态学缓冲区。
• 归约器及其参数，包括 tileScale、bestEffort 和任何 crsTransform。
• 导出参数：region、scale、crs、maxPixels 和任务 ID。
• 运行日期和 ee.__version__ / API 客户端版本，因为服务器端默认值可能会在不通知的情况下发生变化。

如果推荐使用 Earth Engine 而不是本地工作流，却没有说明这一点，就算不上完整：可复现性成本是用户转向服务器端处理时放弃的主要优势，因此应说明如何弥补。

验证流程

1. 探查：composite.select("B4").projection().nominalScale().getInfo() 和波段名称——在归约前确认比例尺／CRS 假设。
2. 在 geemap 中以 2 个缩放级别对照底图进行目视检查。
3. 在导出的裁剪影像上，将一个分区统计值与本地计算结果交叉核对（可发现比例尺／掩膜差异）。
4. 报告：集合 ID、日期范围、掩膜方法和阈值、比例尺、归约器类型。

常见问题检查清单

• 在循环中调用 .getInfo()（将逻辑移至服务器端）。
• 在 reduceRegion(s) 中缺少 scale → 统计结果随缩放级别变化。
• 使用 Landsat C2 时未应用比例因子 → 反射率 > 1。
• 使用 bestEffort=True 隐藏分辨率下降。
• 中位数合成中包含多云像素（归约前先应用掩膜）。
• 在服务器端对象上使用 Python 条件语句（结果始终为假）。
• 趋势地图未根据有效观测数量进行掩膜。

执行规范

• 工作流： 定义数据集和时间范围；构建服务端掩膜和转换管线；在小范围区域内测试；执行计算；验证比例尺和投影；以可复现的方式导出。
• 决策规则： 使用 Earth Engine 处理全球档案数据和可扩展的聚合；对于敏感数据或离线数据，使用本地工具；对于超出交互式处理限制的任务，使用批量导出。
• 验证流程： 检查波段、投影、比例尺、掩膜和观测数量；检查空间样本；在本地交叉核验一项导出的统计数据；记录数据集版本和参数。
• 故障模式： 如遇客户端循环、隐式比例尺、掩膜像素偏差、配额导致的静默降级、资产过期或无边界区域操作，应立即停止。
• 交付物： 可运行脚本、数据集和日期清单、掩膜和归约器参数、任务/导出设置、验证证据，以及导出资产清单。
• 来源时效性： 执行时，请查阅权威来源注册表，了解目录、API、配额和政策变更。