1. 问题定位：ITMS-91053 到底在拦什么
第一次在提交构建版本时看到 ITMS-91053 这串报错，很多人的第一反应是“代码是不是写错了”。实际上这条邮件跟业务代码几乎没关系，它属于苹果在隐私合规层面的一道硬门槛。报错原文大意是：你的应用引用了某些 API，但PrivacyInfo.xcprivacy文件里没有声明对应的“已批准理由”（approved reasons）。换句话说，系统检测到你在用某些被归类为“可能涉及用户隐私”的接口，却没在隐私清单里交代清楚用途，于是直接把你挡在审核门外。
这个机制从 2024 年春季开始逐步收紧，对 Flutter 项目影响尤其明显。原因很直接：Flutter 应用不是纯原生工程，它由 Dart 代码、Flutter 引擎、以及一堆通过 pub 引入的第三方插件共同组成，最终打包成一个 iOS 应用。苹果的静态扫描会遍历整个二进制，只要任何一个插件、任何一个传递依赖里调用了被标记的 API，而你整体的隐私清单没有覆盖到，就会触发 ITMS-91053。所以这不是“我自己的代码干净就行”的问题，而是整条依赖链的合规问题。
先把这条报错涉及的核心概念讲清楚，不然后面全是瞎试。苹果把需要声明理由的 API 分成几大类，常见的有：文件时间戳相关（比如creationDate、modificationDate）、系统启动时间相关（systemUptime）、磁盘空间相关（volumeAvailableCapacity）、用户偏好读取（UserDefaults）等。每一类在隐私清单里对应一个具体的“API 类别键”，你必须为每一类填写至少一条苹果认可的用途理由，比如“用于应用功能”“用于分析”“用于第三方广告”等。填错类别、漏填类别、或者理由和实际用途对不上，都会被拦。
对 Flutter 开发者来说，最坑的地方在于：报错邮件通常只告诉你“缺少声明”，但不会精确指出是哪个插件、哪个 API 触发的。你拿到的是一个笼统的拒绝理由，得自己像侦探一样去定位。这也是为什么很多人反复提交、反复被拒，因为没找对源头，只是盲目往隐私清单里堆内容。
我先把整体解决思路摆出来，后面再逐层拆解。核心逻辑是三步：第一步，搞清楚苹果到底要求声明哪些 API 类别；第二步，定位你的 Flutter 工程里哪些依赖触发了这些类别；第三步，在正确的位置补上PrivacyInfo.xcprivacy，并确保打包后它真的进了最终的 app bundle。这三步任何一步走偏，问题都解决不了。下面按这个顺序展开，中间穿插我踩过的坑和实测有效的排查手法。
2. 前置认知：隐私清单的组成与生效逻辑
2.1 隐私清单文件到底长什么样
PrivacyInfo.xcprivacy本质上是一个 plist 格式的 XML 文件，结构固定，主要包含几个顶层键：NSPrivacyTracking（是否用于追踪）、NSPrivacyTrackingDomains（追踪域名列表）、NSPrivacyCollectedDataTypes（收集的数据类型）、NSPrivacyAccessedAPITypes（访问的 API 类型）。ITMS-91053 直接对应的是最后一个键NSPrivacyAccessedAPITypes，它是一个数组，每个元素描述一类被访问的 API 以及对应的理由。
一个最小可用的片段大概是这样：
<key>NSPrivacyAccessedAPITypes</key> <array> <dict> <key>NSPrivacyAccessedAPIType</key> <string>NSPrivacyAccessedAPICategoryFileTimestamp</string> <key>NSPrivacyAccessedAPITypeReasons</key> <array> <string>C617.1</string> </array> </dict> </array>这里的C617.1是苹果给“文件时间戳”类别预定义的批准理由代码之一，含义大致是“应用内部用于展示或管理用户可见的文件”。注意，理由不是随便写一句话，而是要用苹果规定的代码。每个 API 类别都有一组固定的理由代码，选错代码等于没声明。这一点很多人第一次做会忽略，以为写个中文说明就行，结果照样被拒。
2.2 为什么 Flutter 项目特别容易中招
纯原生项目里，开发者对自己调用的 API 心里有数，补清单相对直接。Flutter 项目的复杂性在于依赖树太深。你 pubspec 里写的是some_plugin: ^1.2.3，但这个插件背后可能依赖了原生 SDK，原生 SDK 里又调用了文件时间戳或UserDefaults。这些调用在 Dart 层完全看不见，只有打包成 iOS 二进制后才会被扫描到。
更麻烦的是，Flutter 引擎本身、以及一些基础插件（比如路径处理、缓存、日志类插件）都可能触碰这些 API。所以哪怕你的业务代码一行原生都没写，照样可能收到 ITMS-91053。我见过一个项目，业务上只是做了个本地缓存图片的功能，结果因为缓存插件读取了文件修改时间，直接触发文件时间戳类别的缺失声明。
理解这一点很关键：解决 ITMS-91053 不是“改我自己的代码”，而是“梳理整个依赖链并补齐声明”。心态上要把它当成一次依赖审计，而不是一次代码修 bug。
2.3 清单的生效位置与打包路径
还有一个高频误区：文件建了、内容也写了，但提交后依然被拒。原因往往是文件没被正确打进 app bundle。PrivacyInfo.xcprivacy必须位于最终.app包的根目录下（和Info.plist同级），而不是躺在 Xcode 工程的某个文件夹里就算数。Xcode 只有在把该文件加入对应 target 的 “Copy Bundle Resources” 构建阶段后，才会把它拷进产物。
Flutter 工程的结构又比较特殊，iOS 部分在ios/目录下，用 Xcode 打开的是Runner.xcworkspace。你新建的隐私清单要加到 Runner target 的资源里。如果是通过 CocoaPods 引入的插件自带隐私清单，那由 pod 的 resource bundle 机制处理，但前提是插件作者确实提供了。很多老插件没有提供，就得靠你在主工程里统一兜底声明。这个“兜底”思路是解决 Flutter 场景 ITMS-91053 的核心策略，后面会详细讲怎么落地。
3. 精准定位：找出是哪个依赖触发了报错
3.1 从审核邮件里榨取有效信息
苹果的拒绝邮件虽然笼统，但不是完全没线索。仔细看邮件正文，通常会列出“missing an approved reason for a required reason API”这样的描述，有时会附带具体的 API 类别名称，比如提到 file timestamp 或 system boot time。把这些关键词记下来，它至少告诉你缺的是哪一大类。如果邮件里连类别都没提，那就得靠下面的方法自己扫。
我的习惯是先把邮件里所有出现的类别词提取出来，做成一个待办清单。比如邮件提到“disk space”和“file timestamp”，那我这次就重点排查这两类。不要一上来就把所有类别全填一遍，那样虽然可能蒙混过关，但清单会变得臃肿且难以维护，而且如果理由和实际用途不符，后续还可能引发别的合规问题。
3.2 用二进制扫描反查调用来源
最靠谱的定位手段是直接扫打包后的二进制。具体做法：先在本地打一个 Release 包（flutter build ipa或通过 Xcode Archive），拿到.xcarchive里的.app，然后用otool或nm这类工具去查符号引用。比如查文件时间戳相关，可以搜creationDate、modificationDate、contentModificationDate这些 selector 名。命令大致如下：
# 进入 .app 目录后，对主二进制做符号扫描 nm -u Runner.app/Runner | grep -i "modificationDate"如果主二进制里没有，但某个 framework 里有，那就说明是那个 framework 引入的。Flutter 项目里常见的 framework 包括App.framework（Dart 代码编译产物）、Flutter.framework（引擎）、以及各插件的 framework。逐个扫一遍，基本能锁定嫌疑对象。这一步稍微费点时间，但比盲目试错高效得多。
提示：扫描时注意大小写和命名差异，不同 SDK 对同一 API 的调用写法可能略有不同，建议用不区分大小写的模糊匹配。
3.3 借助依赖清单做交叉验证
二进制扫描能定位到 framework，但要精确到具体插件，还得结合pubspec.lock和 Podfile.lock 做交叉验证。思路是：先看哪个 framework 命中了敏感符号，再回溯这个 framework 是哪个 pod 产出的，pod 又对应哪个 Flutter 插件。Podfile.lock里记录了每个 pod 的版本和来源，对照着看就能理清链路。
我一般会建一张小表来记录排查结果，避免自己绕晕：
| 命中符号 | 所在 framework | 对应 pod | 对应 Flutter 插件 | 处理方式 |
|---|---|---|---|---|
| modificationDate | 某缓存插件 framework | 某 cache pod | 某 cache 插件 | 升级或兜底声明 |
| systemUptime | Flutter.framework | 引擎内置 | 无 | 主工程兜底声明 |
这张表不用多正式，自己看得懂就行。它的价值在于把“模糊的报错”转化成“可执行的清单”，每处理完一行就划掉，进度一目了然。实测下来，大部分 ITMS-91053 的触发源集中在缓存类、文件管理类、日志类、统计类插件上，业务 UI 类插件反而很少中招。
3.4 一个容易忽略的排查盲区
有个坑我踩过：只扫了.app里的 framework，却漏了 app 扩展（extension）或者某些动态库。如果你的项目带了通知扩展、分享扩展，这些扩展也是独立二进制，同样会被扫描。排查时要把.appex目录也纳入范围。另外，某些插件会把代码编进静态库再链进主二进制，这种情况下符号会出现在主二进制里，而不是独立 framework，扫描时别只盯着 framework 看。
4. 补齐声明：主工程兜底与插件升级的取舍
4.1 兜底声明的正确写法
定位清楚类别后，最直接的做法是在主工程的PrivacyInfo.xcprivacy里把对应类别补上。这里的关键是“理由代码要选对”。以文件时间戳为例，苹果提供的理由代码有C617.1（应用内部展示或管理用户可见文件）、3B52.1（应用功能需要访问用户授权选择的文件）等。你得根据实际用途选，选一个最贴近的即可，不必把所有代码都列上。
下面是一个覆盖常见类别的兜底清单示例，注意这只是模板，实际要按你的项目情况裁剪：
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> <plist version="1.0"> <dict> <key>NSPrivacyTracking</key> <false/> <key>NSPrivacyAccessedAPITypes</key> <array> <dict> <key>NSPrivacyAccessedAPIType</key> <string>NSPrivacyAccessedAPICategoryFileTimestamp</string> <key>NSPrivacyAccessedAPITypeReasons</key> <array> <string>C617.1</string> </array> </dict> <dict> <key>NSPrivacyAccessedAPIType</key> <string>NSPrivacyAccessedAPICategorySystemBootTime</string> <key>NSPrivacyAccessedAPITypeReasons</key> <array> <string>35F9.1</string> </array> </dict> <dict> <key>NSPrivacyAccessedAPIType</key> <string>NSPrivacyAccessedAPICategoryDiskSpace</string> <key>NSPrivacyAccessedAPITypeReasons</key> <array> <string>E174.1</string> </array> </dict> <dict> <key>NSPrivacyAccessedAPIType</key> <string>NSPrivacyAccessedAPICategoryUserDefaults</string> <key>NSPrivacyAccessedAPITypeReasons</key> <array> <string>CA92.1</string> </array> </dict> </array> </dict> </plist>写完后务必确认这个文件被加进了 Runner target 的 Copy Bundle Resources。验证方法是打完包后进.app根目录看文件在不在，别只信 Xcode 界面上的勾选状态。
4.2 升级插件 vs 主工程兜底
遇到触发问题的插件，第一反应可能是“升级到最新版，作者应该修了”。这个思路对，但不总能成。有些插件维护不活跃，最新版也没带隐私清单；有些插件升级会引入 breaking change，牵一发动全身。这时候主工程兜底就是更务实的选择。
我的判断标准是这样的：如果插件活跃维护、升级成本低，优先升级，因为作者提供的清单通常更精确；如果插件停更、或者升级风险大，就在主工程兜底声明，同时记录一笔技术债，等后续有空再处理。兜底声明虽然“粗暴”，但它是合法的——苹果允许应用在主工程统一声明所有用到的 API 类别，只要理由真实即可。
注意：兜底声明不要无脑全填。填了某类别就意味着你声明“我确实用了这类 API”，如果实际没用，虽然一般不会因此被拒，但清单会失真，后续维护的人容易被误导。按实际扫描结果填，干净利落。
4.3 插件自带清单与主工程清单的合并问题
这里有个细节值得单独说：当多个来源都提供隐私清单时（主工程一份、若干插件各一份），打包后它们会被合并。合并规则大致是取并集，但前提是各份清单格式合法、键名正确。如果某个插件的清单写错了格式，可能导致合并异常，甚至让主工程的声明失效。我遇到过插件清单里理由代码拼错的情况，结果整个合并结果出问题，排查了很久。
所以补完主工程清单后，建议做一次“合并后验证”：打包，解包.app，找到最终的PrivacyInfo.xcprivacy（合并后的产物），用plutil检查格式是否合法：
plutil -lint Runner.app/PrivacyInfo.xcprivacy如果报错，说明某份来源清单有问题，得逐个排查。这个步骤花不了几分钟，但能省掉一轮被拒的往返。
5. 实操全流程：从改文件到成功过审
5.1 完整操作步骤拆解
把前面的分析串成一条可执行的流水线，按顺序做：
- 提取报错类别：从审核邮件里记下缺失的 API 类别关键词。
- 本地打 Release 包：用
flutter build ipa --release产出归档，拿到.app。 - 二进制扫描定位：用
nm/otool扫主二进制和各 framework，锁定命中符号。 - 交叉验证依赖：对照
Podfile.lock和pubspec.lock，确定具体插件。 - 决策处理方式：能升级的升级，不能升级的主工程兜底。
- 编写或修改隐私清单：按类别填理由代码，确保格式合法。
- 确认资源打包：检查文件在 Copy Bundle Resources 里。
- 本地验证合并结果：解包检查最终清单，
plutil -lint过一遍。 - 重新归档提交：走正常提交流程，等待审核结果。
这套流程我跑过好几遍，稳定有效。关键在于第 3、4 步不要偷懒，定位准了后面都是顺水推舟；定位不准就会陷入“改了还被拒”的循环。
5.2 参数与理由代码的选择依据
理由代码不是随便挑的，每个代码背后对应苹果定义的具体场景。以UserDefaults类别为例，CA92.1表示“仅访问应用自身写入的偏好数据”，1C8F.1表示“访问应用组内共享的偏好数据”。如果你的应用用了 App Group 做数据共享，却填了CA92.1，严格来说是不准确的。虽然审核不一定逐条核对，但填准确是基本素养，也能避免后续复查出问题。
选择方法：先明确你的 API 调用属于哪个场景（自身数据、共享数据、用户可见文件、应用功能必需等），再去苹果的批准理由文档里找对应代码。文档里每个类别下列了所有可用代码及含义，对着选就行。这一步不需要背，需要的是耐心核对。
5.3 打包现场的实操记录
说一个我最近处理的实例（项目信息做虚构处理）。某 Flutter 应用提交后被拒，邮件提到 file timestamp 类别缺失。我按流程打包扫描，发现主二进制里没有相关符号，但某个缓存插件的 framework 里命中了contentModificationDate。查Podfile.lock确认是该缓存插件引入。该插件最新版依然没带隐私清单，升级也无济于事，于是走主工程兜底，在PrivacyInfo.xcprivacy里补了NSPrivacyAccessedAPICategoryFileTimestamp和理由C617.1。
改完后本地验证：解包.app，确认清单在根目录，plutil -lint通过，且合并后的内容里能看到我补的类别。重新归档提交，这次顺利过审。整个过程从定位到过审大概花了半天，其中扫描定位占了大头，真正改文件只花了几分钟。这也印证了一个判断：ITMS-91053 的难点在定位，不在修改。
5.4 提交前的自检清单
为了避免反复提交浪费时间，我整理了一份提交前自检项，每次走一遍：
- 报错邮件里的类别是否都已覆盖
- 每个类别的理由代码是否与真实用途匹配
- 隐私清单是否在 Copy Bundle Resources 中
- 打包后
.app根目录是否存在该文件 plutil -lint是否通过- 合并后的清单是否包含所有预期类别
- 是否有扩展 target 也需要单独处理
这份清单看着琐碎，但每一条都对应一次真实的被拒经历。尤其是扩展 target 那条，很多人主工程处理好了，扩展忘了，结果还是被拒。
6. 常见问题与排查技巧实录
6.1 高频问题速查表
| 现象 | 可能原因 | 排查与解决 |
|---|---|---|
| 补了清单仍被拒 | 文件没进 bundle | 解包.app确认根目录有文件 |
| 补了清单仍被拒 | 理由代码类别不对 | 核对类别键与代码是否匹配 |
| 补了清单仍被拒 | 扩展 target 未处理 | 检查.appex是否也需声明 |
| 合并后清单异常 | 某插件清单格式错误 | plutil -lint逐份检查来源 |
| 升级插件后新报错 | 新版本引入新 API | 重新扫描定位，补新类别 |
| 扫描找不到符号 | 符号被 strip 或混淆 | 用未 strip 的构建或查静态库 |
这张表覆盖了我遇到过的绝大多数情况。实际排查时按“先确认文件在不在，再确认内容对不对，最后确认范围全不全”的顺序走，效率最高。
6.2 几个反直觉的坑
第一个坑：以为 Debug 包能验证。Debug 构建的产物结构和 Release 不同，符号也没 strip，扫描结果可能和线上不一致。验证隐私清单一定要用 Release 归档，别图省事用 Debug。
第二个坑：以为改了 Xcode 工程就完事。Flutter 的构建流程里，flutter build会重新生成部分工程配置，某些手动改动可能被覆盖。稳妥做法是把隐私清单文件放在固定路径，并在 Xcode 里正确引用，构建后务必解包复核，别只信工程配置。
第三个坑：忽略 Flutter 引擎自身的调用。有些类别（比如 system boot time）是引擎或底层库调用的，跟你的业务和插件都无关，但照样要声明。这种情况只能主工程兜底，没有别的办法。
6.3 独家避坑心得
说几条文档里不会写、但实战中很有用的经验。其一，建立一份“隐私清单变更记录”，每次因为 ITMS-91053 改了什么都记一笔，包括日期、类别、理由代码、触发插件。时间一长你会发现规律，比如某类插件特别容易触发某类 API，下次引入新插件时就能提前预防。其二，把二进制扫描脚本化，写个小 shell 脚本一键扫所有 framework 的敏感符号，比手动一个个查快得多，也避免遗漏。其三，和团队约定插件引入规范，新插件进来先看它有没有带隐私清单，没有的话评估是否接受主工程兜底的成本，从源头减少问题。
这些经验的价值在于把“救火”变成“防火”。ITMS-91053 本身不难解，难的是它反复出现、每次都要重新定位。建立机制之后，后续的维护成本会低很多。
7. 长效治理：把合规检查前置到开发流程
7.1 在 CI 里加一道扫描关卡
与其等提交被拒再回头查，不如在持续集成里加一步扫描。思路很简单：每次构建 Release 包后，自动跑一遍敏感符号扫描，命中就报警。脚本可以这样组织：解包.app，遍历所有 framework 和主二进制，用一组预定义的敏感符号列表去匹配，有命中就输出文件名和符号名。这样问题在提测阶段就暴露，不用等到审核环节。
敏感符号列表不用一开始就很全，从你实际遇到过的类别开始积累，慢慢补全。我现在的列表覆盖了文件时间戳、启动时间、磁盘空间、UserDefaults 这几大类的主要符号，基本够用。CI 报警不一定要阻断构建，先做成提醒，观察一段时间误报率，稳定后再考虑阻断。
7.2 插件准入与清单台账
团队协作场景下，建议维护一份插件清单台账，记录每个插件的版本、是否自带隐私清单、触发的 API 类别、处理方式。新插件引入时先查台账，同类问题不重复踩。台账不用多复杂，一个表格就够，关键是持续更新。
另外，插件升级时把“隐私清单是否变化”纳入检查项。有些插件升级会新增 API 调用，清单却没同步更新，这种隐蔽变化最容易在提交时才暴露。升级后跑一遍 CI 扫描，能提前发现。
7.3 对 Flutter 生态的一点观察
从这几轮处理下来，我的感受是 Flutter 生态在隐私合规上的成熟度参差不齐。头部插件跟进得快，中小插件往往滞后。作为使用者，短期内只能靠主工程兜底来保证过审；长期看，社区需要更统一的规范，比如在插件模板里默认带上隐私清单骨架。在那之前，把兜底和扫描做成团队的标准动作，是最务实的应对。
我个人在实际操作中的体会是，ITMS-91053 这类问题最怕的不是难，而是乱。只要把“定位—声明—验证”这条链路固定下来，每次按流程走，基本都能一次过。真正浪费时间的是没有章法地乱改，改完也不知道对不对，只能靠提交去试。把流程沉淀成脚本和清单，后面再遇到同类问题，处理起来就是十几分钟的事。
原理与实践)