使用本地凭据

了解如何在使用 EAS 时配置和使用本地凭据。

通常，到 让 EAS 为你处理 为止，你就可以不再成为代码签名专家。但是，在某些情况下，某些用户可能希望自己管理其项目密钥库、证书和配置文件。

¥You can usually get away with not being a code signing expert by letting EAS handle it for you. However, there are cases where some users might want to manage their project keystore, certificates and profiles on their own.

如果你想管理自己的应用签名凭据，可以使用 credentials.json 为 EAS Build 提供本地文件系统上凭据的相对路径及其关联的密码，以使用它们对你的构建进行签名。

¥If you would like to manage your own app signing credentials, you can use credentials.json to give EAS Build relative paths to the credentials on your local file system and their associated passwords to use them to sign your builds.

credentials.json

如果你选择加入本地凭据配置，则需要在项目的根目录中创建一个 credentials.json 文件，它应该看起来像这样：

¥If you opt-in to local credentials configuration, you'll need to create a credentials.json file at the root of your project, and it should look something like this:

{
  "android": {
    "keystore": {
      "keystorePath": "android/keystores/release.keystore",
      "keystorePassword": "paofohlooZ9e",
      "keyAlias": "keyalias",
      "keyPassword": "aew1Geuthoev"
    }
  },
  "ios": {
    "provisioningProfilePath": "ios/certs/profile.mobileprovision",
    "distributionCertificate": {
      "path": "ios/certs/dist-cert.p12",
      "password": "iex3shi9Lohl"
    }
  }
}

请记住将 credentials.json 和所有凭据添加到.gitignore，这样你就不会意外地将它们提交到存储库并可能泄露你的秘密。

¥Remember to add credentials.json and all of your credentials to .gitignore so you don't accidentally commit them to the repository and potentially leak your secrets.

安卓凭证

¥Android credentials

如果你想构建 Android 应用二进制文件，你需要有一个密钥库。如果你还没有发布密钥库，你可以使用以下命令自行生成它（将 KEYSTORE_PASSWORD、KEY_PASSWORD、KEY_ALIAS 和 com.expo.your.android.package 替换为你选择的值）：

¥If you want to build an Android app binary you'll need to have a keystore. If you don't have a release keystore yet, you can generate it on your own using the following command (replace KEYSTORE_PASSWORD, KEY_PASSWORD, KEY_ALIAS and com.expo.your.android.package with the values of your choice):

一旦你的计算机上有了密钥库文件，你应该将其移动到适当的目录。我们建议你将密钥库保存在 android/keystores 目录中。请记住 git-ignore 所有发布密钥库！如果你已运行上述 keytool 命令并将密钥库放在 android/keystores/release.keystore，则可以通过在 .gitignore 中添加以下行来忽略该文件：

¥Once you have the keystore file on your computer, you should move it to the appropriate directory. We recommend you keep your keystores in the android/keystores directory. Remember to git-ignore all your release keystores! If you have run the above keytool command and placed the keystore at android/keystores/release.keystore, you can ignore that file by adding the following line to .gitignore:

android/keystores/release.keystore

创建凭据.json 并使用凭据配置它：

¥Create credentials.json and configure it with the credentials:

{
  "android": {
    "keystore": {
      "keystorePath": "android/keystores/release.keystore",
      "keystorePassword": "KEYSTORE_PASSWORD",
      "keyAlias": "KEY_ALIAS",
      "keyPassword": "KEY_PASSWORD"
    }
  },
  "ios": {
    %%placeholder-start%%... %%placeholder-end%%
  }
}

• keystorePath 指向密钥库在你计算机上的位置。支持相对路径（相对于项目根目录）和绝对路径。

  ¥keystorePath points to where the keystore is located on your computer. Both relative (to the project root) and absolute paths are supported.

• keystorePassword 是密钥库密码。如果你已执行前面的步骤，则其值为 KEYSTORE_PASSWORD。

  ¥keystorePassword is the keystore password. If you have followed the previous steps it's the value of KEYSTORE_PASSWORD.

• keyAlias 是关键别名。如果你已执行前面的步骤，则其值为 KEY_ALIAS。

  ¥keyAlias is the key alias. If you have followed the previous steps it's the value of KEY_ALIAS.

• keyPassword 是密钥密码。如果你已执行前面的步骤，则其值为 KEY_PASSWORD。

  ¥keyPassword is the key password. If you have followed the previous steps it's the value of KEY_PASSWORD.

iOS 凭证

¥iOS credentials

构建 iOS 应用二进制文件还有一些先决条件。你需要一个付费的 Apple 开发者账户，然后需要为你的应用生成分发证书和配置文件，这可以通过 苹果开发者门户。

¥There are a few more prerequisites for building the iOS app binary. You need a paid Apple Developer Account, and then you'll need to generate the Distribution Certificate and Provisioning Profile for your application, which can be done via the Apple Developer Portal.

一旦你的计算机上有了分发证书和配置文件，你应该将它们移动到适当的目录。我们建议你将它们保存在 ios/certs 目录中。在本文档的其余部分中，我们假设它们分别命名为 dist.p12 和 profile.mobileprovision。

¥Once you have the Distribution Certificate and Provisioning Profile on your computer, you should move them to the appropriate directory. We recommend you keep them in the ios/certs directory. In the rest of this document we assume that they are named dist.p12 and profile.mobileprovision respectively.

请记住将包含你的凭据的目录添加到 .gitignore，这样你就不会意外地将它们提交到存储库并可能泄露你的秘密。

¥Remember to add directory with your credentials to .gitignore, so you don't accidentally commit them to the repository and potentially leak your secrets.

如果你已将凭据放置在建议的目录中，则可以通过将以下行添加到 .gitignore 来忽略这些文件：

¥If you have placed the credentials in the suggested directory, you can ignore those files by adding the following line to .gitignore:

ios/certs/*

创建（或编辑）credentials.json 并使用凭据配置它：

¥Create (or edit) credentials.json and configure it with the credentials:

{
  "android": {
    %%placeholder-start%%... %%placeholder-end%%
  },
  "ios": {
    "provisioningProfilePath": "ios/certs/profile.mobileprovision",
    "distributionCertificate": {
      "path": "ios/certs/dist.p12",
      "password": "DISTRIBUTION_CERTIFICATE_PASSWORD"
    }
  }
}

• provisioningProfilePath 指向配置文件在你计算机上的位置。支持相对路径（相对于项目根目录）和绝对路径。

  ¥provisioningProfilePath points to where the Provisioning Profile is located on your computer. Both relative (to the project root) and absolute paths are supported.

• distributionCertificate.path 指向分发证书在你计算机上的位置。支持相对路径（相对于项目根目录）和绝对路径。

  ¥distributionCertificate.path points to where the Distribution Certificate is located on your computer. Both relative (to the project root) and absolute paths are supported.

• distributionCertificate.password 是位于 distributionCertificate.path 的分发证书的密码。

  ¥distributionCertificate.password is the password for the Distribution Certificate located at distributionCertificate.path.

多目标项目

¥Multi-target project

如果你的 iOS 应用使用 应用扩展（例如共享扩展、小组件扩展等），你需要为 Xcode 项目的每个目标提供凭据。这是必要的，因为每个扩展都由单独的包标识符来标识。

¥If your iOS app is using App Extensions like Share Extension, Widget Extension, and so on, you need to provide credentials for every target of the Xcode project. This is necessary because each extension is identified by an individual bundle identifier.

假设你的项目由一个主应用目标（名为 multitarget）和一个共享扩展目标（名为 shareextension）组成。

¥Let's say that your project consists of a main application target (named multitarget) and a Share Extension target (named shareextension).

在这种情况下，你的 credentials.json 应如下所示：

¥In this case, your credentials.json should look like below:

{
  "ios": {
    "multitarget": {
      "provisioningProfilePath": "ios/certs/multitarget-profile.mobileprovision",
      "distributionCertificate": {
        "path": "ios/certs/dist.p12",
        "password": "DISTRIBUTION_CERTIFICATE_PASSWORD"
      }
    },
    "shareextension": {
      "provisioningProfilePath": "ios/certs/shareextension-profile.mobileprovision",
      "distributionCertificate": {
        "path": "ios/certs/another-dist.p12",
        "password": "ANOTHER_DISTRIBUTION_CERTIFICATE_PASSWORD"
      }
    }
  }
}

设置凭证源

¥Setting a credentials source

你可以通过在构建配置文件上指定 "credentialsSource": "local" 或 "credentialsSource:" "remote" 来告诉 EAS Build 应如何解析凭据。

¥You can tell EAS Build how it should resolve credentials by specifying "credentialsSource": "local" or "credentialsSource:" "remote" on a build profile.

• 如果提供了 "local"，则将使用 credentials.json。

  ¥If "local" is provided, then credentials.json will be used.

• 如果提供了 "remote"，则将从 EAS 服务器解析凭据。

  ¥If "remote" is provided, then credentials will be resolved from EAS servers.

例如，你可能希望在部署到 Amazon Appstore 时使用本地凭据，在部署到 Google Play 商店时使用远程凭据：

¥For example, maybe you want to use local credentials when deploying to the Amazon Appstore and remote credentials when deploying to the Google Play Store:

{
  "build": {
    "amazon-production": {
      "android": {
        "credentialsSource": "local"
      }
    },
    "google-production": {
      "android": {
        "credentialsSource": "remote"
      }
    }
  }
}

如果不设置任何选项，"credentialsSource" 将默认为 "remote"。

¥If you do not set any option, "credentialsSource" will default to "remote".

在 CI 触发的构建上使用本地凭据

¥Using local credentials on builds triggered from CI

在开始设置 CI 作业之前，请确保已配置 如上所述 的 credential.json 和 eas.json 文件。

¥Before you start setting up your CI job, make sure you have your credentials.json and eas.json files configured as described above.

开发者倾向于使用环境变量为 CI 作业提供密钥。这种方法的挑战之一是，credentials.json 文件包含一个 JSON 对象，并且可能很难正确转义它，因此你可以将其分配给环境变量。此问题的一种可能解决方案是将文件转换为 Base64 编码的字符串，将环境变量设置为该值，然后对其进行解码并在 CI 上恢复文件。

¥Developers tend to provide CI jobs with secrets by using environment variables. One of the challenges with this approach is that the credentials.json file contains a JSON object and it might be difficult to escape it properly, so you could assign it to an environment variable. One possible solution to this problem is to convert the file to a base64-encoded string, set an environment variable to that value, and later decode it and restore the file on the CI.

考虑以下步骤：

¥Consider the following steps:

• 在控制台中运行以下命令，根据你的凭据文件生成 Base64 字符串：

  ¥Run the following command in the console to generate Base64 string based on your credentials file:

• 在 CI 上，使用上述命令的输出设置 CREDENTIALS_JSON_BASE64 环境变量。

  ¥On your CI, set the CREDENTIALS_JSON_BASE64 environment variable with the output of the above command.

• 在 CI 作业中，使用简单的 shell 命令恢复文件：

  ¥In the CI job, restore the file using a simple shell command:

同样，你可以对密钥库、配置文件和分发证书进行编码，以便稍后可以在 CI 上恢复它们。要使用 CI 中的本地凭据成功触发构建，你必须确保所有凭据都存在于 CI 实例的文件系统中（位于与 credentials.json 中定义的位置相同的位置）。

¥Similarly, you can encode your keystore, provisioning profile and distribution certificate so you can restore them later on the CI. To successfully trigger your build using local credentials from CI, you'll have to make sure all the credentials exist in the CI instance's file system (at the same locations as defined in credentials.json).

恢复步骤到位后，你可以使用 从 CI 触发构建 指南中描述的相同流程来触发构建。

¥Once the restoring steps are in place, you can use the same process described in the Triggering builds from CI guide to trigger the builds.