Amplify DataStore无法正常启动、查询无响应是什么原因

问题现象 #

在React Native应用中使用DataStore和GraphQL时，执行任意数据读写操作，控制台仅输出以下日志后就无后续响应：

LOG  [DEBUG] 56:36.775 DataStore - Starting DataStore
LOG  [DEBUG] 56:36.776 DataStore - Starting Storage

以如下代码为例，Start日志可以正常打印，但End日志永远不会执行，await DataStore.query(User)语句一直处于pending状态：

console.log('Start');
const users = await DataStore.query(User);
console.log('End');

该问题在全新创建的React Native项目中也会复现，所有Amplify相关依赖为全新安装，多次从零重建项目后问题仍存在。

排查与解决步骤 #

按以下顺序逐一排查，绝大多数场景下可以解决该静默卡住的问题：

• 确认模型生成与云端部署流程正确
  执行amplify push后必须等待云端所有资源部署完全结束，再执行amplify codegen models重新生成本地模型文件。如果push流程未完成就生成模型、启动应用，Storage层初始化时会因为找不到匹配的模型定义直接挂起，且不会抛出显性报错。
• 对齐Amplify相关依赖版本
  所有Amplify相关依赖（包括aws-amplify以及所有@aws-amplify/开头的包）必须保持完全一致的版本号，不要单独升级某一个子包，也不要使用带next标签的测试版本。对齐版本后删除node_modules目录、对应的包管理锁文件（package-lock.json/yarn.lock/pnpm-lock.yaml），重新执行依赖安装命令。
• 修正Amplify初始化顺序
  必须在应用入口的最顶部执行Amplify.configure(awsconfig)，之后才能导入、调用任何DataStore相关的方法。如果在configure执行前就触发DataStore调用，会直接卡在初始化阶段。

  针对React Native 0.72及以上版本，严格模式会放大模块导入顺序的影响，建议把Amplify配置逻辑单独存为一个文件，在入口文件index.js的第一行导入该配置文件，之后再导入App根组件。

• 清除本地残留的不兼容缓存
  如果之前在设备上运行过旧版本应用，本地存储（SQLite/AsyncStorage）中残留的不兼容旧数据会导致Storage引擎初始化卡死。开发阶段可以直接卸载应用后重新安装，也可以在应用首次启动时先调用DataStore.clear()清空旧缓存，再执行后续的数据操作。
• 开启全量日志定位具体卡点
  调整DataStore日志等级为VERBOSE，同时配置显式错误捕获，可以看到初始化流程具体卡住的环节，配置方式如下：

  Amplify.configure({
    ...awsconfig,
    DataStore: {
      errorHandler: (err) => console.log('DataStore runtime error:', err),
      logLevel: 'VERBOSE'
    }
  })
  

  开启后如果存在模型关联配置错误、权限规则不匹配、本地数据库版本不兼容等问题，都会直接打印具体错误信息，不会静默挂起。

内容的提问来源于stack exchange，提问作者Stan Shvaika