从链接启动EAS模拟器会话

构建一个经过身份验证的 expo.dev URL，从 EAS 构建、构建指纹、应用存档或 Expo Go 创建 EAS 模拟器会话，并打开其全屏浏览器预览。

重要 EAS 模拟器是限量预览版本。它不包含在付费或免费计划中，目前仅对精选合作伙伴开放。如果你有兴趣试用，请加入等候名单。

创建会话链接可以从 EAS Build、构建指纹、应用归档或 Expo Go 启动 iOS 模拟器会话。链接会在预览准备好后以全屏模式打开会话的浏览器预览。你可以用它在拉取请求、CI 结果或者内部工具中添加 EAS 模拟器操作，而无需集成 REST API。

🌐 A create session link starts an iOS Simulator session from an EAS Build, build fingerprint, application archive, or Expo Go. The link opens the session's browser preview in fullscreen mode when the preview is ready. Use one to add an EAS Simulator action to a pull request, CI result, or an internal tool without integrating the REST API.

创建会话链接可以启动仅浏览器预览的会话。它们不会配置代理设备、Appium 或 Argent。如果你需要控制器、安卓模拟器、空白设备，或者自定义时长和空闲限制，请使用 EAS CLI 或 REST API。

🌐 Create session links start browser-preview-only sessions. They do not provision agent-device, Appium, or Argent. Use EAS CLI or the REST API when you need a controller, an Android Emulator, a blank device, or custom duration and idle limits.

警告打开创建会话的链接会直接启动一个新会话，没有确认步骤。这个链接不是幂等的：再次打开可能会创建另一个会话，从而消耗 EAS 模拟器的使用次数。为了避免启动新会话，请从项目的模拟器会话页面打开已有会话，并分享它的会话页面 URL。

构建 URL

🌐 Construct the URL

在 URL 中使用 Expo 账号名和项目别名：

🌐 Use the Expo account name and project slug in the URL:

https://expo.dev/accounts/<account>/projects/<project>/simulator-sessions/create?<parameters>

打开链接的人必须登录一个可以访问该项目的 Expo 账户。如果他们已经登出，expo.dev 会在认证过程中保留完整的 URL，并在他们登录后开始会话。

🌐 The person opening the link must sign in to an Expo account that can access the project. If they are signed out, expo.dev preserves the complete URL during authentication and starts the session after they sign in.

选择一个应用来源

🌐 Choose an application source

每个创建会话的链接都需要恰好一个应用来源：

🌐 Every create session link requires exactly one application source:

参数	描述
`buildId`	已完成且未过期的 iOS 模拟器 EAS 构建的 ID。该构建决定了平台。
`buildFingerprint`	EAS 构建的指纹哈希。需要 `platform`。EAS 会将它解析为在请求的平台上具有此指纹的最新可安装构建。
`applicationArchiveUrl`	可下载的 iOS 应用归档的 URL。由于它嵌套在创建会话的 URL 中，请对该 URL 进行编码。支持的扩展名有 .tar.gz、.tgz、.app 和 .app.zip。
`expoGo`	设置为 `true` 以安装并启动 Expo Go，而不是项目构建。需要 `platform`。使用 `sdkVersion` 选择 Expo Go 版本，使用 `openUrl` 从 Metro 加载你的项目。`false` 和 `0` 会被视为不存在。

不要包含多个应用来源。像 buildId 和 expoGo=true 这样的多个链接会显示验证错误，无法创建会话。没有应用来源的链接也无法创建会话。

🌐 Do not include more than one application source. A link with more than one, such as buildId together with expoGo=true, shows a validation error and does not create a session. A link without an application source cannot create a session.

EAS把空的应用来源值，比如buildId=，当作不存在处理。

🌐 EAS treats an empty application source value, such as buildId=, as absent.

添加其他参数

🌐 Add other parameters

参数	描述
`platform`	用于 `buildFingerprint`、`applicationArchiveUrl` 或 `expoGo` 的平台。创建会话链接当前支持 `ios`。在使用 `buildFingerprint` 和 `expoGo` 时是必需的，当归档 URL 拥有支持的 iOS 扩展时可以省略。当应用来源是 `buildId` 时会被忽略，因为构建决定了其平台。
`sdkVersion`	用于选择 Expo Go 的 Expo SDK 版本，例如 `54`。可以使用主版本或语义版本。仅在 `expoGo=true` 下有效。省略则使用该平台当前的 Expo Go 版本。
`launchArgs`	应用启动时传递的参数。重复使用此参数可以传递多个参数。它们的顺序会被保留。
`openUrl`	应用启动后要打开的 Expo、开发客户端或应用深度链接。在使用 Expo Go 时，传入远程模拟器可以访问的 Metro 服务器 `exp://` URL，例如通过隧道的 Metro URL。在使用开发构建时，传入 `<scheme>://expo-development-client/?url=<encoded-public-metro-url>`，如使用开发构建进行实时更改所述。
`deviceIdentifier`	iOS 模拟器名称或唯一设备标识符 (UDID)，例如 `iPhone 16 Pro`。如果省略此参数，运行器会选择默认设备。
`name`	描述性的会话名称，最多 255 个字符。

对参数值进行 URL 编码，尤其是嵌套的 URL 和包含空格的值。大多数编程语言都提供了可以处理这种编码的 URL 构建器。例如：

🌐 URL-encode parameter values, especially nested URLs and values that contain spaces. Most programming languages provide a URL builder that handles this encoding. For example:

const url = new URL('https://expo.dev/accounts/acme/projects/my-app/simulator-sessions/create');

url.searchParams.set('buildFingerprint', 'FINGERPRINT_HASH');
url.searchParams.set('platform', 'ios');
url.searchParams.set('name', 'PR preview');
url.searchParams.set('deviceIdentifier', 'iPhone 16 Pro');
url.searchParams.append('launchArgs', '-UITestMode');
url.searchParams.append('launchArgs', '1');
url.searchParams.set('openUrl', 'myapp://profile/42');

console.log(url.toString());

示例

🌐 Examples

从 EAS Build 开始一个会话

🌐 Start a session from an EAS Build

https://expo.dev/accounts/acme/projects/my-app/simulator-sessions/create?buildId=BUILD_UUID

构建必须完成，它的产物不能过期，并且必须针对 iOS 模拟器，而不是实体 iOS 设备。

🌐 The build must be finished, its artifact must not be expired, and it must target the iOS Simulator instead of a physical iOS device.

用指纹启动最新可安装版本

🌐 Start the most recent installable build with a fingerprint

https://expo.dev/accounts/acme/projects/my-app/simulator-sessions/create?buildFingerprint=FINGERPRINT_HASH&platform=ios

EAS 会将指纹解析到最新可安装的 iOS 模拟器版本。如果没有具有此指纹的可安装版本，链接会显示验证错误。当你需要选择一个特定的版本时，请改用 buildId。

🌐 EAS resolves the fingerprint to the most recent installable iOS Simulator build. If no installable build with this fingerprint exists, the link shows a validation error. Use buildId instead when you need to select one specific build.

给会话命名并选择一个设备

🌐 Name the session and choose a device

https://expo.dev/accounts/acme/projects/my-app/simulator-sessions/create?buildId=BUILD_UUID&name=PR%20preview&deviceIdentifier=iPhone%2016%20Pro

从应用档案启动会话

🌐 Start a session from an application archive

https://expo.dev/accounts/acme/projects/my-app/simulator-sessions/create?applicationArchiveUrl=https%3A%2F%2Fcdn.example.com%2FMyApp.app.zip&platform=ios

传递启动参数并打开深层链接

🌐 Pass launch arguments and open a deep link

https://expo.dev/accounts/acme/projects/my-app/simulator-sessions/create?buildId=BUILD_UUID&launchArgs=-UITestMode&launchArgs=1&openUrl=myapp%3A%2F%2Fprofile%2F42

启动 Expo Go 并从 Metro 加载一个项目

🌐 Start Expo Go and load a project from Metro

https://expo.dev/accounts/acme/projects/my-app/simulator-sessions/create?expoGo=true&platform=ios&sdkVersion=58&openUrl=exp%3A%2F%2Fmetro.example.ngrok.dev

EAS 会为所请求的 SDK 版本安装 Expo Go 版本，并在其中打开 openUrl 值。省略 sdkVersion 将使用当前的 Expo Go 版本。远程模拟器必须能够访问 Metro。在打开链接之前，通过公共隧道启动 Metro：

🌐 EAS installs the Expo Go release for the requested SDK version and opens the openUrl value in it. Omit sdkVersion to use the current Expo Go release. The remote simulator must be able to reach Metro. Start Metro with a public tunnel before you open the link:

Terminal

- EXPO_UNSTABLE_TUNNEL_V2=1 npx expo start --tunnel

想了解更多信息，请参阅使用 Expo Go。

🌐 For more information, see Use Expo Go.

如果没有为请求的 SDK 版本发布 Expo Go 版本，该链接会显示验证错误。

🌐 If no Expo Go release is published for the requested SDK version, the link shows a validation error.

当链接打开时会发生什么

🌐 What happens when the link opens

认证完成后，expo.dev 会验证参数和构建，然后创建会话。它会在保留模拟器和准备浏览器预览的同时显示会话的启动进度。这大约需要一分钟。当浏览器预览可用时，expo.dev 会直接重定向到它的 webPreviewUrl 并携带 fullscreen=1，因此预览会填满整个页面。

🌐 After authentication, expo.dev validates the parameters and build, then creates the session. It shows the session's startup progress while reserving a simulator and preparing the browser preview. This can take about a minute. When the browser preview becomes available, expo.dev redirects directly to its webPreviewUrl with fullscreen=1, so the preview fills the page.

要返回或共享同一个会话而不启动新的会话，可以从项目的模拟器会话页面打开它。其会话页面的 URL 使用这种格式：

🌐 To return to or share the same session without starting another one, open it from the project's Simulator sessions page. Its session page URL uses this format:

https://expo.dev/accounts/<account>/projects/<project>/simulator-sessions/<session-id>

关闭页面或离开不会取消服务已接受的会话创建，也不会停止正在运行的会话。完成后请停止会话，以免继续消耗使用量。

🌐 Closing the page or navigating away does not cancel a session creation that the service already accepted, and it does not stop a running session. Stop the session when you finish so that it does not continue consuming usage.

如果参数或构建无效，expo.dev 会显示无法启动模拟器会话错误。常见原因包括：

🌐 If the parameters or build are invalid, expo.dev shows a Cannot start simulator session error instead. Common causes include:

未完成或已过期的构建
一个 iOS 设备版本
没有 platform 的指纹或 expoGo 链接
没有可安装的指纹版本
不支持的存档网址
sdkVersion没有expoGo=true
没有发布 Expo Go 版本的 SDK 版本
不止一个应用来源