Earthly CI构建 — Earthly容器化构建¶

一句话概述：Earthly 像是"Dockerfile 和 Makefile 生的孩子"，把构建过程放在容器里运行，保证在你的笔记本和 CI 服务器上跑出完全一样的结果。

核心知识点速查表¶

概念	白话解释
Earthfile	构建配置文件，语法像 Dockerfile 但能定义多个目标
Target	构建目标，类似 Makefile 的 target（比如 build、test）
Artifact	构建产物（比如编译好的二进制文件、Docker 镜像）
缓存	Earthly 自动缓存中间步骤，没变的不重新执行
DAG	有向无环图，Earthly 自动识别依赖关系并行执行

当前版本信息（2026年）¶

信息	详情
Earthfile 版本	VERSION 0.8
GitHub Stars	~12,000
新产品	Earthly Lunar（AI 时代的构建守护）
官网	https://earthly.dev
文档	https://docs.earthly.dev

安装配置¶

# Linux/macOS 安装
sudo /bin/sh -c 'wget https://github.com/earthly/earthly/releases/latest/download/earthly-linux-amd64 -O /usr/local/bin/earthly && chmod +x /usr/local/bin/earthly'

# macOS Homebrew
brew install earthly/earthly/earthly

# 初始化（首次使用）
earthly bootstrap

# 验证安装
earthly --version

# 需要 Docker 运行（Earthly 在容器中执行构建）
docker --version  # 确保 Docker 已安装

基本使用¶

第一个 Earthfile¶

# Earthfile（放在项目根目录）
VERSION 0.8                        # 声明 Earthfile 版本

# 基础镜像
FROM python:3.12-slim              # 所有 target 共用的基础镜像
WORKDIR /app                       # 工作目录

# 安装依赖的 target
deps:
    COPY requirements.txt .        # 复制依赖文件
    RUN pip install -r requirements.txt  # 安装依赖
    SAVE IMAGE --cache-hint        # 缓存这一步（依赖没变就不重装）

# 构建 target
build:
    FROM +deps                     # 依赖 deps target（先执行 deps）
    COPY src/ src/                 # 复制源码
    COPY tests/ tests/             # 复制测试
    SAVE ARTIFACT src /src         # 保存源码作为 artifact

# 测试 target
test:
    FROM +deps                     # 也依赖 deps
    COPY +build/src src/           # 使用 build 的 artifact
    COPY tests/ tests/
    RUN pytest tests/ -v           # 运行测试

# Docker 镜像 target
docker:
    FROM +deps
    COPY +build/src src/           # 使用构建产物
    ENTRYPOINT ["python", "-m", "src.main"]
    SAVE IMAGE my-app:latest       # 保存 Docker 镜像

# 全部运行
all:
    BUILD +test                    # 先测试
    BUILD +docker                  # 再构建镜像

运行构建¶

# 运行指定 target
earthly +build                    # 运行 build 目标
earthly +test                     # 运行 test 目标
earthly +docker                   # 构建 Docker 镜像
earthly +all                      # 运行所有

# 带参数运行
earthly --build-arg VERSION=1.0.0 +build

# 查看缓存状态
earthly --verbose +build          # 详细输出，看哪些步骤被缓存

生信流程示例¶

# Earthfile — 宏基因组分析流程
VERSION 0.8

FROM condaforge/mambaforge:latest
WORKDIR /pipeline

# 安装生信工具
setup:
    RUN mamba install -y -c bioconda -c conda-forge \
        fastp samtools megahit kraken2 bracken
    SAVE IMAGE --cache-hint

# 质控
qc:
    FROM +setup
    COPY data/raw/ data/raw/
    RUN fastp -i data/raw/sample.fq.gz \
              -o data/clean/sample.fq.gz \
              --html results/qc_report.html
    SAVE ARTIFACT data/clean /clean
    SAVE ARTIFACT results /results

# 组装
assemble:
    FROM +setup
    COPY +qc/clean data/clean/
    RUN megahit -r data/clean/sample.fq.gz \
                -o results/assembly
    SAVE ARTIFACT results/assembly /assembly

# 全流程
pipeline:
    BUILD +qc
    BUILD +assemble

高级用法¶

多平台构建¶

# 同时为 ARM 和 x86 构建
multi-platform:
    BUILD --platform=linux/amd64 --platform=linux/arm64 +docker

集成测试（WITH DOCKER）¶

# 在构建中启动 Docker 容器做集成测试
integration-test:
    FROM earthly/dind:alpine-3.19     # Docker-in-Docker 镜像
    COPY docker-compose.yml .
    WITH DOCKER --compose docker-compose.yml  # 启动依赖服务
        RUN python -m pytest tests/integration/
    END

引用其他项目的 Earthfile¶

# 引用 GitHub 上其他项目的 target
remote-dep:
    FROM github.com/org/repo:main+build   # 使用远程 Earthfile
    COPY +local-build/app /app            # 和本地 target 组合

常见报错与解决¶

报错信息	原因	解决方案
`Docker not available`	Docker 没运行	启动 Docker Desktop 或 dockerd
`SAVE ARTIFACT not found`	artifact 路径错误	检查 COPY +target/path 的路径
`Cache miss`	缓存失效	检查 COPY 顺序，依赖文件放前面
`Permission denied`	容器内权限问题	加 `USER root` 或调整权限
构建慢	没利用缓存	把不常变的步骤放前面（如装依赖）

速查表¶

# ===== 构建命令 =====
earthly +target               # 运行指定 target
earthly +target --no-cache     # 不用缓存
earthly --push +target         # 推送镜像/artifact
earthly --ci +target           # CI 模式（禁用交互）

# ===== Earthfile 语法 =====
VERSION 0.8                    # 版本声明（必须第一行）
FROM image                     # 基础镜像
COPY file dest                 # 复制文件
RUN command                    # 运行命令
SAVE ARTIFACT path /name       # 保存构建产物
SAVE IMAGE name:tag            # 保存 Docker 镜像
BUILD +target                  # 依赖其他 target
FROM +target                   # 基于其他 target

# ===== 特殊命令 =====
ARG --required NAME            # 必需参数
IF [ condition ]               # 条件构建
FOR item IN list               # 循环
WITH DOCKER                    # Docker-in-Docker

同类工具对比¶

特性	Earthly	Makefile	Docker	Bazel
容器隔离	✅ 所有步骤	❌	✅ 单步	✅ 沙箱
学习曲线	低（像 Dockerfile）	低	低	高
缓存	✅ 自动	❌ 手动	✅ 层缓存	✅ 精确
并行	✅ 自动 DAG	❌	❌	✅
跨平台	✅	❌	✅	✅
适用规模	中小项目	小项目	部署	大项目

总结：Earthly 适合中小团队和项目，语法直观（会写 Dockerfile 就会写 Earthfile），自动缓存和并行化。如果你的构建流程包含"编译+测试+打包 Docker 镜像"，Earthly 比纯 Makefile + Dockerfile 更整洁可靠。