Expo Versions Endpoint 实战用 CLI 更新 SDK 版本配置以及 expo CLI 如何消费这份数据【免费下载链接】expoAn open-source framework for making universal native apps with React. Expo runs on Android, iOS, and the web.项目地址: https://gitcode.com/GitHub_Trending/ex/expoVersions endpointhttps://expo.io/--/api/v2/versionsstaging 环境为https://staging.expo.io/--/api/v2/versions是 Expo 工具链中一份关键的“SDK 版本清单”它返回一个 JSON 对象记录了每个 Expo SDK 版本对应的客户端下载地址、React / React Native 版本、关联包版本等信息。Expo CLI 依赖它完成模拟器客户端Expo Go安装、依赖版本校验、eject 以及包升级等操作网站侧也可以用它跳转到对应 SDK 的 release notes。本文基于仓库内的发布指南guides/releasing/Versions Endpoint.md与配套源码讲解这份数据的内容结构、如何用et命令行工具安全地更新 staging/production 配置以及 CLI 端读取与消费这份数据的完整实现链路。数据结构每个 SDK 版本包含哪些字段从更新脚本的数据模型 VersionsSchema 可以看到整个 endpoint 的响应形如{ sdkVersions: { 54.0.0: { androidClientUrl: ..., androidClientVersion: ..., iosClientUrl: ..., iosClientVersion: ..., releaseNoteUrl: ..., relatedPackages: { typescript: ~5.5.0, ...: ... }, facebookReactNativeVersion: 0.7x.x, facebookReactVersion: 19.x.x, packagesToInstallWhenEjecting: { ...: ... } } }, turtleSdkVersions: { android: ..., ios: ... } }其中sdkVersions以 SDK 版本号为 key每个条目VersionsSdkSchema至少包含字段含义androidClientUrl/androidClientVersionAndroid 端 Expo Go 客户端的下载地址与版本号iosClientUrl/iosClientVersioniOS 端 Expo Go 客户端的下载地址与版本号releaseNoteUrl该 SDK 发布公告的 URL供网站链接 release notes 使用relatedPackages该 SDK 推荐的关联 npm 包及版本范围重点见下文facebookReactNativeVersion/facebookReactVersion该 SDK 绑定的 react-native / react 版本packagesToInstallWhenEjectingejectbare workflow 化时需要额外安装的包expokitNpmPackage/expoReactNativeTag历史字段与 Exponent / RN fork 构建相关顶层还有一个turtleSdkVersions字段{ android, ios }从字段命名看是 CI/CD 侧Turtle 构建系统使用的客户端版本映射。在 CLI 消费侧这份数据被建模为 SDKVersion 类型iosVersion、iosClientUrl、androidClientUrl、releaseNoteUrl、relatedPackages、facebookReactVersion、facebookReactNativeVersion、expoVersion、beta等字段与其一一对应说明发布端与消费端共享同一份 schema 约定。用 CLI 更新 Versions Endpoint更新操作统一通过etExpo 内部工具集命令实现位于 tools/src 目录完成遵循“先 staging、后 production”的两段式发布流程。1. update-versions-endpoint更新 staging文档给出的基础用法et update-versions-endpoint --sdkVersion35.0.0 --keymyKey --valuemyValue执行后会展示一个 diff确认输入y后才会写入 staging拒绝则放弃变更。完整的命令选项来自 UpdateVersionsEndpoint.ts比文档示例丰富得多选项说明-s, --sdkVersion [string]要更新的 SDK 版本省略时交互选择已有版本列表--root修改整个配置根节点下的 key而非某个 SDK 版本下的 key-d, --deprecated [boolean]将指定 SDK 标记为isDeprecated-r, --release-note-url [string]设置该 SDK 的 release 公告 URL写入releaseNoteUrl-k, --key [string]要设置的自定义 key支持点号路径dot notation-v, --value [any]与--key配合的值--delete删除--key指向的配置项--delete-sdk删除整个指定 SDK 的配置--reset将 staging 配置回滚为 production 的当前状态几个值得注意的实现细节均来自 UpdateVersionsEndpoint.ts--key支持 lodash 风格的点号路径setConfigValueForKey内部使用lodash/set写入因此可以精确修改relatedPackages下的单个包指定的 SDK 版本不存在时会交互式询问是否初始化该 SDK 的配置SDK 版本号会先做semver合法性校验纯数字输入如35会被 normalizeSdkVersion 规范化为35.0.0所有变更都通过jsondiffpatch计算 diff 并打印后才落盘落盘动作由 applyChangesToStagingAsync 完成。2. promote-versions-to-production推送到 productionstaging 验证无误后执行et promote-versions-to-production该命令别名promote-versions-to-prod/promote-versions会对比 production 与 staging 两份配置打印staging - production的 diff确认后把 staging 全量写入 production实现见 PromoteVersionsToProduction.ts。3. 底层 API 调用与安全前提两条命令最终都落到 tools/src/Versions.ts 的三个函数getVersionsAsync(host)GEThttps://{host}/v2/versions/latest读取{ data }包裹的响应体setVersionsAsync(versions, host)POSThttps://{host}/v2/versions/update请求体为{ value, secret }host 枚举值为PRODUCTION api.expo.dev、STAGING staging-api.expo.dev。需要强调的运行前提写入操作要求环境变量EXPO_VERSIONS_SECRET已设置否则直接抛错见 setVersionsAsync。这也解释了为什么该流程只面向有权限的发布人员且 staging/production 分离——任何一次 key 的变更都必须先经过 staging 的 diff 确认。Required related package versionsrelatedPackages 规范指南明确约定自 SDK 34 起每个 SDK 版本条目都应包含relatedPackages字段且至少覆盖以下包types/reacttypes/react-nativetypescriptreact-native-webbabel-preset-exporeact-native-unimodules这些值是expoCLI 做依赖一致性校验doctor / install 版本归一化的核心依据。写入方式同样是update-versions-endpoint的点号路径例如et update-versions-endpoint --sdkVersion35.0.0 --keyrelatedPackages.types/react-native --value^0.57.65消费端expo CLI 如何使用 Versions Endpoint发布端只管写入真正的价值体现在expoCLI 的读取与使用上。仓库内expo/cli的实现可以完整还原这条链路。1. 带缓存的请求层getVersionsAsync 通过createCachedFetch请求versions/latest相对路径缓存目录为~/.expo/versions-cacheTTL 为 5 分钟“保持相对新鲜”的折中EXPO_NO_CACHE或EXPO_BETA开启时自动禁用缓存。底层 fetch 包装链基础 URL 拼接、认证头注入、离线检测在 api/rest/client.ts 中定义网络不可达时会抛出OFFLINE错误码并提示可用EXPO_OFFLINE1跳过网络请求。行为测试见 getVersions-test.tsmock 了GET /v2/versions/latest的正常与 500 两种响应。2. 安装模拟器客户端Expo Goexpo start为 iOS/Android 模拟器下载 Expo Go 时downloadExpoGoAsync.ts 会先调getExpoGoVersionEntryAsync(sdkVersion)从sdkVersions[sdkVersion]取出条目用其中的${platform}ClientVersion/${platform}ClientUrl定位下载地址遇到UNVERSIONEDSDK 时退化为取列表中最大的版本号并给出警告。ExpoGoInstallerstart/platforms/ExpoGoInstaller.ts同样以getVersionsAsync()作为版本来源——这正是文档中“installing simulator builds”用途的实现。3. 依赖版本校验与 install 归一化expo install的“自动选对版本”能力来自 getVersionedPackages.tsgetCombinedKnownVersionsAsync 合并两个来源项目本地bundledNativeModules.json提供的版本以及远端 endpoint 返回的版本远端优先源码注释解释了原因——“这样可以在用户不升级expo包的情况下推送紧急修正”normalizeSdkVersionObject 将relatedPackages展开为一张包名 - 版本的映射并补充注入react、react-dom来自facebookReactVersion、expo来自expoVersion、react-native来自facebookReactNativeVersion若命中该映射且用户没有指定精确版本、也没有通过expo.install.exclude排除expo install foo会被改写为foo{endpoint 中的版本}并输出“N SDK 54 compatible native modules”之类的操作日志。这条链路正好印证了指南中“validating package versions ... upgrading packages”的说法relatedPackages里维护的typescript、react-native-web、babel-preset-expo等版本范围就是用户执行expo install时被对齐的目标版本。小结与适用前提发布侧修改走et update-versions-endpointstagingdiff 确认制确认后用et promote-versions-to-production推到 production写入依赖EXPO_VERSIONS_SECRET环境变量命令与 schema 见 tools/src/commands 与 tools/src/Versions.ts。消费侧expoCLI 通过GET /v2/versions/latest5 分钟缓存读取该数据用于下载 Expo Go 客户端、expo install的版本归一化与依赖校验核心实现分布在 api/getVersions.ts、utils/downloadExpoGoAsync.ts 与 start/doctor/dependencies/getVersionedPackages.ts。规范每个 SDK 版本条目应完整提供relatedPackages至少含types/react、types/react-native、typescript、react-native-web、babel-preset-expo、react-native-unimodules六个包这是保证 CLI 侧依赖校验可靠性的底线约定。适用前提以上流程面向 Expo 基础设施维护者普通开发者无需接触写入 API只需了解 CLI 的依赖校验结果“来自哪里”即可。离线EXPO_OFFLINE1或 canary SDK 场景下依赖校验会被跳过或降级相关提示见 getVersionedPackages.ts。【免费下载链接】expoAn open-source framework for making universal native apps with React. Expo runs on Android, iOS, and the web.项目地址: https://gitcode.com/GitHub_Trending/ex/expo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考