主题
常见问题
Expo Go 中模块不可用
Expo Go 只能使用其内置原生模块。依赖包含自定义原生代码时，应安装 expo-dev-client 并重新创建 development build。
检查依赖兼容性：
bash
npx expo-doctor安装依赖后仍提示找不到原生模块
Metro 重新加载只能更新 JavaScript。新增原生依赖、Config Plugin 或权限配置后，需要重新构建并安装 development build。
Metro 无法解析模块
依次检查：
- 包是否存在于当前工作区的
package.json； - 导入名称和文件大小写是否正确；
- 依赖版本是否与当前 Expo SDK 兼容；
- monorepo、Babel 或 Metro 配置是否改变了解析范围。
确认配置正确后再清理缓存：
bash
npx expo start --clear真机无法连接开发服务器
- 手机与电脑应处于可互通的网络；
- 防火墙不能阻止 Metro 端口；
- 企业网络或访客网络可能隔离设备；
- 局域网不可用时可以切换 Expo 提供的 tunnel 连接方式。
真机无法访问本地 API
真机中的 localhost 是手机自身，不是开发电脑。应使用电脑的局域网 IP，并确保服务监听局域网接口。Android 模拟器访问宿主机时通常使用模拟器提供的特殊地址，不能直接照搬真机配置。
Android 正常、iOS 异常
检查平台权限、文件名大小写、系统 API 支持范围、安全区域、键盘行为和原生配置。不能以单个平台运行成功推断跨平台行为一致。
修改 app.json 后没有生效
只有 JavaScript 层读取的配置能随 Metro 刷新。涉及图标、启动页、权限、包标识或 Config Plugin 的变化，需要重新运行 Prebuild 或重新构建客户端。
Prebuild 覆盖原生修改
npx expo prebuild --clean 会重新生成原生目录。原生修改应表达为应用配置、Config Plugin 或 Expo Module；如果选择直接维护 android、ios，则应提交原生目录并停止把它们当作可丢弃产物。
EAS Build 失败
从完整日志中定位第一个实际错误，不以最后的通用失败消息作为根因。重点检查：
- Gradle、CocoaPods 或 Xcode 依赖错误；
- Expo SDK 与原生库版本不兼容；
- Config Plugin 输出无效；
- Android Keystore 或 Apple 证书、Provisioning Profile 异常；
- EAS 环境变量缺失。
本地 expo start 成功只说明 JavaScript 开发服务可运行，不代表原生 release 构建一定成功。
Fast Refresh 状态异常
Fast Refresh 会尽量保留组件状态。模块导出方式、Hook 顺序或组件签名发生变化时可能执行完整重载。需要验证初始化逻辑时，应主动重新加载应用，不能只依赖热更新结果。