返回

Expo App转让必看:解决App Store 403协议缺失错误

IOS

Expo 应用转让 App Store 账户后遭遇 “协议缺失” 403 错误的解决之道

问题来了:账户转移后的拦路虎

刚把一个 React Native 应用(用的 Expo SDK 51.0.0)从一个苹果开发者账户转到另一个。本想着可以顺利上传新版本,结果 App Store Connect 直接甩来一个错误:

A required agreement is missing or has expired. (403)

头疼的是,我翻来覆去检查了新账户,所有“协议、税务和银行业务”里的协议明明都接受了,绿色的勾勾✓ 看得真真切切。那这问题到底出在哪?难道是 Expo 或者 React Native 项目里有什么配置没跟着更新?

别急,这情况确实有点绕,但通常不是 App Store Connect 在“撒谎”,而是某些构建或配置环节还“惦记”着老账户。

分析问题根源:哪里卡住了?

这个 403 错误,虽然字面意思是“协议问题”,但在账户转移的背景下,根源往往更深层一些:

1. App Store Connect 协议同步延迟或细节遗漏

虽然你确认了协议,但有时候:

  • 同步延迟 :苹果后台的某些状态同步需要时间,尤其是账户操作之后。
  • 隐藏的协议 :可能有些不常用的协议(比如针对特定地区或功能的)被遗漏了,或者某个协议有新的修订版需要重新同意。即使主面板显示正常,细微之处可能存在差异。

2. Expo 构建配置与旧账户的残留关联

这通常是最可能的原因 。Expo 应用(特别是使用 EAS - Expo Application Services 构建和提交的应用)在构建和上传过程中,会依赖一些本地或云端的配置信息来与 Apple Developer 账户交互。账户转移后,这些配置可能没有自动更新:

  • EAS CLI 登录状态 :你本地或 CI/CD 环境中的 EAS CLI 可能还保留着旧账户的登录凭证或会话。
  • 项目构建配置 :通过 eas build:configure 生成的配置文件(可能存储在 Expo 服务器上,与你的项目 ID 关联)可能还指向旧的 Team ID。
  • 证书和配置文件缓存 :EAS 或者本地环境可能缓存了与旧账户关联的签名证书(Distribution Certificate)和配置文件(Provisioning Profile)。

3. 本地构建环境的“记忆”

如果你的项目进行过本地原生构建(例如 expo prebuild 后在 Xcode 中操作),本地机器上可能残留着旧账户的证书、配置文件或其他缓存信息,干扰了上传过程。

解决方案:逐一排查,对症下药

既然知道了可能的原因,咱们就一步步来解决。

方案一:再三确认 App Store Connect 协议

虽然你检查过了,但严谨起见,我们再彻底过一遍,并且换个角度思考。

原理与作用
确保 App Store Connect 账户层面不存在任何未处理的协议或条款更新。这是所有提交流程的基础。

操作步骤

  1. 登录新账户 :使用具有“账户持有人”或“管理”权限的 Apple ID 登录 App Store Connect
  2. 导航至协议部分 :点击顶部的 “协议、税务和银行业务” (Agreements, Tax, and Banking)。
  3. 仔细审查所有协议
    • 检查 “生效中”(Active) 标签页下的所有协议。确保它们都处于有效状态。
    • 特别留意 “待处理”(Pending) 或 “已过期”(Expired) 标签页。这里绝对不能 有任何与你的应用类型(免费/付费)相关的未处理协议。
    • 查看是否有任何需要更新的 “已付费应用程序”(Paid Applications) 或 “免费应用程序”(Free Applications) 协议。即使是微小的条款更新,也需要重新同意。点击每个协议,确认没有需要你操作的按钮(比如 "Review and Agree")。
  4. 等待一段时间 :如果你刚刚才同意了协议,给苹果后台一点同步时间,比如半小时到一小时,然后再尝试上传。

安全建议
保护好你的 Apple Developer 账户凭证,启用双重认证。只有授权人员才能访问和同意协议。

方案二:更新 EAS CLI 配置与登录状态 (最关键!)

这个方案直接处理 Expo 构建服务与新账户的连接问题。

原理与作用
EAS CLI 是连接你的本地项目、Expo 构建服务和 Apple Developer 账户的桥梁。它需要知道当前应该使用哪个 Apple 账户(特别是哪个 Team ID)来进行构建签名和上传。账户转移后,必须强制 EAS CLI 刷新这个认知。

操作步骤

  1. 退出当前 EAS 登录
    打开终端(Terminal 或命令提示符),进入你的项目目录,运行:

    eas logout
    

    这将清除本地缓存的 EAS 登录凭证。

  2. 重新登录 EAS

    eas login
    

    按照提示,使用你的 Expo 账户登录。重要的是 ,在后续过程中如果被问到关联 Apple Developer 账户时,确保选择或输入的是新账户 的凭证和对应的 Apple Team ID

  3. 重新配置项目构建
    这一步非常关键,它会更新 Expo 云端关于你项目应使用哪个 Apple Team ID 的记录。

    eas build:configure
    

    这个命令会引导你完成平台的配置(iOS/Android)。在 iOS 部分,它会让你确认或选择 Apple Team ID。请务必选择新账户的 Team ID 。如果你不确定新的 Team ID,可以在 Apple Developer 网站 的 "Membership details" 下找到。

  4. 检查凭证同步情况 (可选但推荐)
    你可以运行 eas credentials 来查看和管理 EAS 为你项目存储的 Apple 凭证(证书和配置文件)。

    eas credentials
    

    进入 iOS 凭证管理界面,检查里面的 Distribution Certificate 和 Provisioning Profile 是否与你的新账户关联。如果不确定,可以考虑让 EAS 尝试为你重新生成或同步(谨慎操作,可能会影响现有 TestFlight 测试员)。

命令行指令示例
上面已经提供了 eas logout, eas login, eas build:configure, eas credentials 命令。

进阶使用技巧

  • 对于 CI/CD 环境,你可能需要更新环境变量,特别是 EXPO_TOKEN(如果使用)以及与 Apple 相关的认证信息(如 API Key 或 App-Specific Password,取决于你的认证方式)。确保 CI/CD 流程使用的是新账户的信息。
  • eas build:configure 会修改你项目中的 eas.json 文件(如果尚不存在则创建)。检查该文件,确认 ios.appleTeamId 指向的是新账户的 Team ID。例如:
    // eas.json
    {
      "cli": {
        "version": ">= 5.9.3" // 示例版本
      },
      "build": {
        "development": { ... },
        "preview": { ... },
        "production": {
          "ios": {
            "appleTeamId": "YOUR_NEW_TEAM_ID" // 确认这里是新 Team ID
          }
        }
      },
      "submit": { ... }
    }
    

方案三:检查并清理项目证书/配置文件

旧账户的签名证书和配置文件无法用于新账户。虽然 EAS 通常会尝试处理,但手动检查能确保万无一失。

原理与作用
iOS 应用的签名依赖于与特定 Apple Developer Team 关联的 Distribution Certificate 和 Provisioning Profile。应用转移后,必须使用新 Team 下生成的或重新关联的证书和配置文件。

操作步骤

  1. 使用 EAS Credentials 管理 (推荐)
    如方案二所述,运行 eas credentials

    • 选择 iOS 平台。
    • 查看 "Distribution Certificate" 和 "Provisioning Profile"。
    • EAS 通常会显示这些凭证关联的 Team ID。确认它们属于新账户。
    • 如果看起来是旧的,或者你不确定,可以尝试让 EAS 为你创建新的。选择相应的选项(如 "Generate new distribution certificate" 或让 EAS 自动处理)。注意 :生成新的分发证书可能会影响到现有通过该证书签名的其他应用或 TestFlight 版本。
  2. 手动检查 Apple Developer Portal (如果 EAS 无法解决或你想更深入了解)

    • 登录到 Apple Developer 网站 的 "Certificates, Identifiers & Profiles" 部分。
    • 证书 (Certificates) :检查 "Distribution" 类型的证书。确认有属于你的新 Team ID 的有效分发证书。如果没有,创建一个。
    • 配置文件 (Profiles) :检查 "Distribution" (App Store 类型) 的配置文件。找到与你的 App Bundle ID 匹配的配置文件。点击查看详情,确保它关联的是新 Team ID 下的分发证书,并且状态是 Active。如果配置有问题或关联了旧证书,可以编辑更新或重新创建一个。
    • 更新本地 Xcode (如果适用) :如果你曾使用 Xcode 管理过证书,确保在 Xcode 的 "Preferences" -> "Accounts" 中,旧账户已移除或不活跃,新账户已添加且证书已下载同步。

安全建议

  • 谨慎管理你的分发证书私钥。丢失私钥会导致无法更新应用。
  • 创建或吊销证书/配置文件前,了解其影响范围,特别是团队协作或有多个应用共享证书的情况。

方案四:清理本地构建缓存

有时候,本地残留的旧构建数据也会造成干扰。

原理与作用
清除本地项目依赖、Expo 预构建缓存以及可能的 Node.js 缓存,确保下次构建是从一个干净的状态开始。

操作步骤

  1. 清理项目依赖缓存

    # 如果使用 npm
    rm -rf node_modules package-lock.json
    npm install
    npm cache clean --force  # 清理 npm 缓存
    
    # 如果使用 yarn
    rm -rf node_modules yarn.lock
    yarn install
    yarn cache clean       # 清理 yarn 缓存
    
  2. 清理 Expo 预构建缓存 (如果使用了 expo prebuild)

    npx expo prebuild --clean
    

    这会删除 iosandroid 目录,并重新生成它们。注意 :如果你在原生目录 (ios/android) 中做了手动修改,这些修改会丢失,需要重新应用。

  3. 清理 EAS 构建缓存 (间接)
    EAS CLI 本身没有直接清理云端构建缓存的命令。但通过上述步骤(特别是重新登录和配置),后续的 eas build 会基于更新后的配置进行,相当于使用了“新鲜”的设置。

命令行指令示例
已在上方提供。

方案五:核对 app.json / app.config.js 配置

虽然不常见,但检查一下项目配置文件中是否硬编码了旧账户信息总是好的。

原理与作用
确保项目的基础配置文件 app.json 或动态配置文件 app.config.js 没有包含指向旧 Apple Developer 账户的硬编码值(特别是 Team ID)。通常 Expo 会自动处理或通过 eas.json 管理。

操作步骤

  1. 打开配置文件 :找到你项目根目录下的 app.jsonapp.config.js 文件。
  2. 查找 Apple 相关配置
    搜索与 iOS 或 Apple 相关的字段,特别留意 expo.ios.appleTeamId
    // app.json or app.config.js example snippet
    {
      "expo": {
        "name": "My Cool App",
        "slug": "my-cool-app",
        "version": "1.0.0",
        "orientation": "portrait",
        "icon": "./assets/icon.png",
        "ios": {
          "supportsTablet": true,
          "bundleIdentifier": "com.mycompany.mycoolapp",
          // "appleTeamId": "YOUR_OLD_TEAM_ID" // 确认这里没有硬编码旧 ID,或者根本没有这个字段 (推荐让 EAS 管理)
        },
        // ... 其他配置
      }
    }
    
    最佳实践 :通常不建议在 app.json / app.config.js 里硬编码 appleTeamId。让 EAS CLI 在 eas.json 中管理这个值会更灵活,不易出错。如果你在这里发现了旧 Team ID,要么删除这行(推荐),要么更新为新 Team ID。删除后,需确保运行了 eas build:configure

处理完这些步骤后,再次尝试运行 eas buildeas submit 来构建和上传你的应用。大概率,那个烦人的 403 错误就消失了。记住,关键往往在于让 EAS CLI 和相关的构建配置“认清”新的 Apple Developer 账户。