缓存依赖项

编辑页面

了解如何通过缓存依赖项来加速构建。

在构建任务开始编译你的项目之前，所有项目依赖项都需要可用并存放在磁盘上。获取依赖项所花费的时间越长，你就需要等待构建完成的时间越久 — 因此，缓存依赖项是加快构建速度的重要部分。

我们正在积极改进缓存以及构建流程的其他方面，以使构建能够稳定且快速地完成。

自定义缓存

eas.json 中构建配置文件里的 cache 字段可用于为特定文件和目录配置缓存。指定的文件会在成功构建后保存到持久存储中，并在后续构建中于 JavaScript 依赖项安装完成后恢复。恢复时不会覆盖现有文件。更改 cache.key 的值会使缓存失效。更改 cache 对象的任何其他属性也会使缓存失效。

JavaScript 依赖项

EAS Build 会运行一个 npm 缓存服务器，可加速为你的构建任务下载 JavaScript 依赖项。默认情况下，使用 npm 或 Yarn 2+ 的项目会使用该缓存。不过，Yarn 1（Classic）需要你应用此变通方法，才能在项目的 package.json 中使用缓存。

若要在构建中禁用我们的 npm 缓存服务器，请在 eas.json 中将 EAS_BUILD_DISABLE_NPM_CACHE 环境变量的值设置为 "1"。

eas.json

{
  "build": {
    "production": {
      "env": {
        "EAS_BUILD_DISABLE_NPM_CACHE": "1"
        %%placeholder-start%%... %%placeholder-end%%
      }
      %%placeholder-start%%... %%placeholder-end%%
    }
    %%placeholder-start%%... %%placeholder-end%%
  }
  %%placeholder-start%%... %%placeholder-end%%
}

不可变锁文件

默认情况下，Node 包将使用你所偏好的包管理器的不可变锁文件标志/命令进行安装（例如，yarn --frozen-lockfile 或 npm ci）。如果你想禁用此功能，可以在 eas.json 中将 EAS_NO_FROZEN_LOCKFILE 环境变量设置为 "1"。

Android 依赖项

EAS Build 运行一个 Maven 缓存服务器，可加快你的构建任务下载 Android 依赖项的速度。

目前，我们正在缓存：

maven-central - https://repo1.maven.org/maven2/
google - https://maven.google.com/
plugins - https://plugins.gradle.org/m2/

要为你的构建禁用我们的 Maven 缓存服务器，请在 eas.json 中将 EAS_BUILD_DISABLE_MAVEN_CACHE 环境变量值设置为 "1"。

eas.json

{
  "build": {
    "production": {
      "env": {
        "EAS_BUILD_DISABLE_MAVEN_CACHE": "1"
        %%placeholder-start%%... %%placeholder-end%%
      }
      %%placeholder-start%%... %%placeholder-end%%
    }
    %%placeholder-start%%... %%placeholder-end%%
  }
  %%placeholder-start%%... %%placeholder-end%%
}

使用 ccache 缓存 C/C++ 编译产物

ccache 是一个编译器缓存，通过缓存之前的编译结果来加速原生代码的重新编译。EAS 原生支持 ccache 配置。

你可以使用以下环境变量，配置构建自动保存和恢复 ccache 缓存：

EAS_USE_CACHE：设置为 1 时，在构建任务期间同时启用恢复和保存缓存结果。
EAS_RESTORE_CACHE：控制是否在构建开始时恢复缓存。设置为 1 启用，设置为 0 禁用。会覆盖 EAS_USE_CACHE。
EAS_SAVE_CACHE：控制是否在构建结束时保存构建缓存。设置为 1 启用，设置为 0 禁用。会覆盖 EAS_USE_CACHE。

EAS Workflows

对于 EAS Workflows，请使用 eas/restore_cache 和 eas/save_cache。

Android 示例：

.eas/workflows/build-android.yml

jobs:
  build_android:
    type: build
    steps:
      - uses: eas/checkout
      - uses: eas/restore_build_cache
      # 这等同于上面的步骤。你也可以通过定义自己的键模式和路径，为其他缓存用途使用 /restore_cache
      # - uses: eas/restore_cache
      #   with:
      #     key: android-ccache-${{ hashFiles('yarn.lock') }}
      #     restore_keys: android
      #     path: /home/expo/.cache/ccache
      - uses: eas/build
      - uses: eas/save_build_cache
      # - uses: eas/save_cache
      #   with:
      #    key: android-ccache-${{ hashFiles('yarn.lock') }}
      #    path: /home/expo/.cache/ccache

iOS 示例：

.eas/workflows/build-ios.yml

jobs:
  build_ios:
    type: build
    steps:
      - uses: eas/checkout
      - uses: eas/restore_build_cache
      # 这等同于上面的步骤。你也可以通过定义自己的键模式和路径，为其他缓存用途使用 /restore_cache
      # - uses: eas/restore_cache
      #   with:
      #     key: ios-ccache-${{ hashFiles('yarn.lock') }}
      #     restore_keys: ios
      #     path: /Users/expo/Library/Caches/ccache
      - uses: eas/build
      - uses: eas/save_build_cache
      # - uses: eas/save_cache
      #   with:
      #    key: ios-ccache-${{ hashFiles('yarn.lock') }}
      #    path: /Users/expo/Library/Caches/ccache

自定义构建

在你自行管理构建步骤的自定义构建中，添加 eas/restore_build_cache 和 eas/save_build_cache 以启用 ccache 缓存。

.eas/build/custom.yml

build:
  name: 使用 ccache 构建
  steps:
    - eas/checkout
    - eas/restore_build_cache
    - eas/build
    - eas/save_build_cache

缓存键会使用包管理器锁文件的哈希值，根据你的依赖生成一个唯一键。当依赖发生变化时，会创建新的缓存，同时仍可通过 restore_keys 回退到之前的缓存。

缓存键匹配

恢复缓存时，缓存系统会遵循特定的搜索顺序来查找匹配的缓存条目。缓存键要么是自动生成的（使用 eas/restore_build_cache 或 eas/save_build_cache 时），要么是通过 key 参数显式提供的（使用 eas/restore_cache 或 eas/save_cache 时）。

搜索顺序如下：

精确匹配：首先搜索与缓存键完全匹配的项（自动生成或显式提供）
恢复键：如果未找到精确匹配项，将按顺序检查 restore_keys，寻找最近的前缀匹配

如果与提供的 key 完全匹配，这会被视为直接命中缓存，并立即恢复缓存。如果是部分匹配或来自 restore_keys 的匹配，缓存也会恢复，但性能可能不会同样理想

使用恢复键

注意：恢复键匹配由缓存系统自动处理，不需要手动配置。这是对预期行为细节的说明。

恢复键 android-ccache- 匹配任何以字符串 android-ccache- 开头的键。例如，android-ccache-fd3052de 和 android-ccache-a9b253ff 这两个键都匹配该恢复键。会使用创建日期最新的缓存。此示例中的键按以下顺序搜索：

android-ccache-${{ hashFiles('yarn.lock') }} 匹配特定哈希值。
android-ccache- 匹配以 android-ccache- 为前缀的缓存键。
android- 匹配任何以 android- 为前缀的键。

缓存限制

访问限制通过在不同 Git 分支或用户之间创建逻辑边界来提供缓存隔离和安全性。在构建应用时，理解并利用这些限制对你和你的用户的安全都很重要。

GitHub 运行

当构建从 GitHub 运行时，缓存会限定在构建所在的分支范围内。构建可以恢复以下位置创建的缓存：

当前分支
默认分支（main 或 master）

EAS CLI 运行

当构建由 eas-cli 触发时，缓存会限定在运行构建的用户范围内。这些按用户限定的缓存允许进行隔离，从而避免在开发过程中或不同用户之间无意共享构建及其缓存的修改。

默认分支缓存

如果构建没有恢复到按用户限定的缓存，它会自动回退，恢复由默认分支上的 GitHub 构建发布的缓存。这使得即使还没有按用户限定的缓存，构建也能受益于可信来源创建的缓存。

共享用户行为

当多个用户共享同一个用户主体时（例如使用访问令牌或从 GitHub Actions 触发构建），按用户限定的缓存规则仍然适用。这意味着在该共享账户下运行的构建将不再拥有隔离缓存，并有共享非预期产物的风险。为避免这种情况，我们建议不要为共享用户下的生产构建恢复缓存，并指定专门的作业只保存干净、全新的缓存。

用于创建缓存的指定作业

你可以通过禁用缓存恢复并仅保存缓存来配置某个作业，以发布干净、全新的缓存。

为生产构建禁用恢复缓存：

你可以通过配置以下环境变量，为特定构建配置文件禁用缓存恢复：

eas.json

{
  "build": {
    "production": {
      "env": {
        "EAS_RESTORE_CACHE": "0",
        "EAS_SAVE_CACHE": "1"
      }
    },
    "preview": {
      "env": {
        "EAS_USE_CACHE": "1"
      }
    }
  }
}

仅从指定作业保存缓存：

为确保只有可信来源发布缓存，你可以配置一个工作流，仅从主分支上的特定作业保存缓存。

.eas/workflows/build.yml

jobs:
  build_production:
    type: build
    if: ${{ github.ref_name == 'main' }}
    env:
      EAS_RESTORE_CACHE: '0'
      EAS_SAVE_CACHE: '1'
    params:
      platform: android
      profile: production

注意：设置 EAS_SAVE_CACHE: '1' 并不会使缓存保存仅限于此作业，其他具有相同环境变量的作业仍然可以保存并覆盖缓存。

iOS 依赖

EAS Build 会从缓存服务器提供大多数 CocoaPods 产物。这提高了 pod install 时间的一致性，并且通常会提升速度。如果你提供了自己的 .netrc 或 .curlrc 文件，缓存将自动被绕过。

要为你的构建禁用使用我们的 CocoaPods 缓存服务器，请在 eas.json 中将 EAS_BUILD_DISABLE_COCOAPODS_CACHE 环境变量值设置为 "1"。

eas.json

{
  "build": {
    "production": {
      "env": {
        "EAS_BUILD_DISABLE_COCOAPODS_CACHE": "1"
        %%placeholder-start%%... %%placeholder-end%%
      }
      %%placeholder-start%%... %%placeholder-end%%
    }
    %%placeholder-start%%... %%placeholder-end%%
  }
  %%placeholder-start%%... %%placeholder-end%%
}

在使用 prebuild 在远程构建时生成你的 ios 目录时，通常不会将项目的 Podfile.lock 提交到源代码管理中。缓存你的 Podfile.lock 可能很有用，这样可以获得可确定的构建结果，但这种情况下的权衡是，由于你在本地开发期间不使用 lockfile，你判断何时需要更改以及更新特定依赖项的能力会受到限制。如果你缓存此文件，偶尔可能会遇到需要清除缓存的构建错误。要缓存 Podfile.lock，请将 ./ios/Podfile.lock 添加到 eas.json 中构建配置里的 cache.paths 列表。

eas.json

{
  "build": {
    "production": {
      "cache": {
        "paths": ["./ios/Podfile.lock"]
        %%placeholder-start%%... %%placeholder-end%%
      }
      %%placeholder-start%%... %%placeholder-end%%
    }
    %%placeholder-start%%... %%placeholder-end%%
  }
  %%placeholder-start%%... %%placeholder-end%%
}