This documentation is available as Markdown for AI agents and LLMs. See the full Markdown index or append .md to any documentation URL.

通过从提供程序缓存和复用构建来加速本地开发。

构建缓存是一项功能，它会基于项目 指纹 将构建结果远程缓存，从而加快 npx expo run:[android|ios] 的速度。 当你运行 npx expo run:[android|ios] 时，它会检查是否存在具有匹配指纹的构建，然后下载并启动它，而不是重新编译。否则，项目会照常编译，然后将生成的二进制文件上传到远程缓存，供以后运行时使用。

使用 EAS 作为构建提供程序

要使用 EAS Build provider 插件，请先将 eas-build-cache-provider 包作为开发依赖安装：

然后，更新你的 app.json，添加 buildCacheProvider 属性及其提供程序：

{
  "expo": {
    "buildCacheProvider": "eas"
    %%placeholder-start%%... %%placeholder-end%%
  }
}

你可以通过导出一个实现以下方法的插件来自定义自己的缓存提供程序：

type BuildCacheProviderPlugin<T = any> = {
  /**
   * 尝试获取一个已存在的构建。若缺失则返回其 URL 或 null。
   */
  resolveBuildCache(props: ResolveBuildCacheProps, options: T): Promise<string | null>;

  /**
   * 上传一个新的构建二进制文件。失败时返回其 URL 或 null。
   */
  uploadBuildCache(props: UploadBuildCacheProps, options: T): Promise<string | null>;

  /**
   * （可选）自定义 fingerprint 哈希算法。
   */
  calculateFingerprintHash?: (
    props: CalculateFingerprintHashProps,
    options: T
  ) => Promise<string | null>;
};

type ResolveBuildCacheProps = {
  projectRoot: string;
  platform: 'android' | 'ios';
  runOptions: RunOptions;
  fingerprintHash: string;
};
type UploadBuildCacheProps = {
  projectRoot: string;
  buildPath: string;
  runOptions: RunOptions;
  fingerprintHash: string;
  platform: 'android' | 'ios';
};
type CalculateFingerprintHashProps = {
  projectRoot: string;
  platform: 'android' | 'ios';
  runOptions: RunOptions;
};

一个使用 GitHub Releases 缓存构建的参考实现可以在 构建缓存提供程序示例 中找到。

局限性

构建缓存提供程序仅会被本地的 npx expo run:[android|ios] 命令调用。由 eas build 触发的构建不受影响。它们始终会生成全新的产物，且不会调用缓存提供程序插件。

某些本地构建也会被跳过：

• iOS 物理设备构建。 设备构建只有在与其配置描述文件匹配的设备上才有效，因此在不同机器或设备之间复用是不安全的。因此，npx expo run:ios 在目标为物理设备时会跳过缓存查找和构建后的上传。只有 iOS 模拟器构建会参与缓存。

如果你在 eas.json 中使用 appVersionSource: "remote"，请注意，versionCode（Android）和 buildNumber（iOS）存储在 EAS 服务器上，而不是你的项目源码中，因此它们不属于指纹输入的一部分。这对于正常的开发迭代来说没有问题。本地执行的 npx expo run:* 不会自动递增这些值，但请注意，缓存产物会保留其最初构建时嵌入的构建编号。

创建自定义构建提供程序

首先创建一个 provider 目录，用于以 TypeScript 编写提供程序插件，并在项目根目录添加一个 provider.plugin.js 文件，它将作为插件入口点。

{
  "extends": "expo-module-scripts/tsconfig.plugin",
  "compilerOptions": {
    "outDir": "build",
    "rootDir": "src"
  },
  "include": ["./src"],
  "exclude": ["**/__mocks__/*", "**/__tests__/*"]
}

import { type BuildCacheProviderPlugin } from '@expo/config';

const plugin: BuildCacheProviderPlugin = {
  resolveBuildCache: async () => {
    console.log('正在搜索远程构建...');
    return null;
  },
  uploadBuildCache: async () => {
    console.log('正在上传构建到远程...');
    return null;
  },
};

export default plugin;

// 此文件为你的插件配置入口文件。
module.exports = require('./provider/build');

{
  "expo": {
    %%placeholder-start%%... %%placeholder-end%%
    "buildCacheProvider": {
      "plugin": "./provider.plugin.js"
    }
  }
}

传递自定义选项

要向你的插件注入自定义选项，你可以使用 options 字段，它会作为你自定义函数的第二个参数传递进去。为此，请按如下所示修改 example/app.json 中的 buildCacheProvider 字段：

{
  "expo": {
    %%placeholder-start%%... %%placeholder-end%%
    "buildCacheProvider": {
      "plugin": "./provider.plugin.js",
      "options": {
        "myCustomKey": "XXX-XXX-XXX"
      }
    }
  }
}