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] 时，它会检查是否存在具有匹配指纹的构建，然后下载并启动该构建，而不是再次编译它。否则，项目将像往常一样进行编译，然后生成的二进制文件会上传到远程缓存，以便将来使用。

🌐 Build caching is a feature that speeds up npx expo run:[android|ios] by caching builds remotely, based on the project fingerprint. When you run npx expo run:[android|ios], it checks if a build with a matching fingerprint exists, then downloads and launches it rather than compiling it again. Otherwise, the project is compiled as usual and then the resulting binary is uploaded to the remote cache for future runs.

使用 EAS 作为构建提供程序

🌐 Using EAS as a build provider

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

🌐 To use the EAS Build provider plugin, start by installing the eas-build-cache-provider package as a developer dependency:

然后，更新你的 app.json 以包含 buildCacheProvider 属性及其提供者：

🌐 Then, update your app.json to include the buildCacheProvider property and its provider:

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

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

🌐 You can roll your own cache provider by exporting a plugin that implements the following methods:

type BuildCacheProviderPlugin<T = any> = {
  /**
   * Try to fetch an existing build. Return its URL or null if missing.
   */
  resolveBuildCache(props: ResolveBuildCacheProps, options: T): Promise<string | null>;

  /**
   * Upload a new build binary. Return its URL or null on failure.
   */
  uploadBuildCache(props: UploadBuildCacheProps, options: T): Promise<string | null>;

  /**
   * (Optional) Customize the fingerprint hash algorithm.
   */
  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;
};

可以在 Build Cache Provider Example 中找到使用 GitHub Releases 缓存构建的参考实现。

🌐 A reference implementation using GitHub Releases to cache builds can be found in the Build Cache Provider Example.

局限性

🌐 Limitations

构建缓存提供程序仅由本地 npx expo run:[android|ios] 命令使用。通过 eas build 触发的构建不受影响。它们总是生成新的构件，并且从不调用缓存提供程序插件。

🌐 The build cache provider is consulted only by local npx expo run:[android|ios] commands. Builds triggered with eas build are not affected. They always produce fresh artifacts and never invoke the cache provider plugin.

一些本地构建也被跳过：

🌐 Some local builds are also skipped:

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

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

🌐 If you're using appVersionSource: "remote" in eas.json, note that the versionCode (Android) and buildNumber (iOS) live on EAS servers rather than in your project source, so they are not part of the fingerprint inputs. This is fine for normal development iteration. Local npx expo run:* invocations don't auto-increment those values, but be aware that a cached artifact retains whatever build number was embedded when it was originally built.

创建自定义构建提供程序

🌐 Creating a custom build provider

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

🌐 Start by creating a provider directory for writing the provider plugin in TypeScript and add a provider.plugin.js file in the project root, which will be the plugin's entry point.

{
  "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('Searching for remote builds...');
    return null;
  },
  uploadBuildCache: async () => {
    console.log('Uploading build to remote...');
    return null;
  },
};

export default plugin;

// This file configures the entry file for your plugin.
module.exports = require('./provider/build');

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

传递自定义选项

🌐 Passing custom options

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

🌐 To inject custom options to your plugin you can use the options field and it will be forwarded as the second parameter of your custom functions. To do so modify the buildCacheProvider field in example/app.json as shown below:

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