cross-platform

跨平台

目的

本技能将指导你选择和实现跨平台移动框架，例如搭配 Expo 的 React Native、使用 Dart 的 Flutter（采用 Bloc 或 Riverpod）、Capacitor 和 Kotlin Multiplatform Mobile (KMM)。本技能侧重于根据项目需求选择合适的框架，并提供分步集成指南，帮助高效开发移动应用。

适用场景

对于需要多平台部署（iOS/Android）以减少代码重复的项目，请使用本技能。构建共享业务逻辑的应用时也可使用，例如电商应用、社交网络或效率工具。对于资源有限的团队，或需要快速原型开发的场景（例如集成原生模块或处理跨平台状态管理），本技能也很适用。

主要能力

• 框架选择：JavaScript 占比高的应用选择 React Native；需要使用 Dart 构建自定义 UI 时选择 Flutter；需要将 Web 应用转换为移动应用时选择 Capacitor；需要共享 Kotlin 代码库时选择 KMM。
• Expo 集成：使用 EAS（Expo Application Services）简化构建流程，包括 OTA 更新和云服务。
• 状态管理：在 Flutter 中使用 Bloc 实现事件驱动状态管理，或在 Flutter/Dart 应用中使用 Riverpod 实现响应式状态管理。
• 跨平台功能：处理特定平台代码，例如通过 Capacitor 的桥接或 KMM 的 expect/actual 声明访问设备 API（如摄像头、GPS）。
• 配置：以 JSON/YAML 格式管理应用配置，例如使用 Expo 的 app.json 配置路由和权限。

使用模式

选择框架时，根据技术栈进行评估：如果团队熟悉 JS，就使用 React Native；如果需要高性能 UI，则使用 Flutter。首先初始化项目：

• 使用 Expo 的 React Native：运行 expo init MyApp --template blank，然后通过 npm install @react-navigation/native 添加依赖项。
• 使用 Riverpod 的 Flutter：通过 flutter create MyApp 创建项目，并在 Dart 文件中设置状态：final counterProvider = StateProvider((ref) => 0);。 始终封装特定平台代码：在 KMM 中，在通用代码中使用 expect fun platformFunction() {}，并在 iOS/Android 模块中实现。 对于 Capacitor，在设置好 Web 项目后，运行 npx cap add android 将 Web 应用转换为移动应用。

常用命令/API

• Expo (React Native)：使用 expo login（需要 $EXPO_API_KEY 环境变量）、使用 eas build --platform all 构建多平台应用，并使用 API 端点 POST https://api.expo.dev/v2/projects 管理项目。
• Flutter：运行 flutter pub add flutter_bloc 添加 Bloc，或运行 flutter run --device-id emulator-5554 指定模拟器；使用 BlocProvider.of(context).add(Event()) 等 API 更改状态。
• Capacitor：运行 npx cap sync 更新原生项目，或运行 npx cap open android 启动 Android Studio；使用 Capacitor 的 Plugins API，例如在 JavaScript 中调用 Capacitor.Plugins.Camera.getPhoto()。
• KMM：在共享模块中运行 ./gradlew build 进行构建，并通过 KMM Bridge 用于 iOS：在 Swift 中使用 import shared.Platform().hello()。 配置格式：编辑 Expo 的 app.json，例如 { "expo": { "name": "MyApp", "slug": "myapp", "platforms": ["ios", "android"] } }；对于 Flutter，通过 pubspec.yaml 修改依赖项：dependencies: flutter_riverpod: ^2.0.0。

集成说明

通过设置环境变量将这些框架与后端集成以进行身份验证，例如，为 API 调用导出 $BACKEND_API_KEY。对于 React Native，使用 Expo 的 Fetch API：fetch('https://api.example.com/data', { headers: { Authorization: Bearer ${process.env.BACKEND_API_KEY} } })。在 Flutter 中，添加 HTTP 包：http.get(Uri.parse('https://api.example.com/data'), headers: {'Authorization': 'Bearer $envVar'}).then((response) => ...);。对于 Capacitor，桥接 Web 请求：安装 @capacitor/core，并使用 CapacitorHttp.get({url: 'https://api.example.com/data', headers: {Authorization: $BACKEND_API_KEY}});。KMM 集成：通过通用模块共享网络代码，并从原生应用调用，同时确保已为依赖项同步 Gradle。

错误处理

通过检查平台不匹配问题来处理常见错误：在 React Native 中，如果 expo build 因为 "Invalid platform" 失败，请检查 app.json platforms 数组。对于 Flutter，如果 flutter run 报错 "No devices"，请使用 flutter emulators --launch Pixel_API_33，然后重试。对于 Capacitor，遇到 "Plugin not found" 错误时，需要运行 npx cap sync 并检查 package.json。在 KMM 中，如果构建失败且缓存已损坏，请使用 ./gradlew clean 解决。始终记录错误：在 Expo 中，使用 console.error(e) 并检查 EAS 构建日志；在 Flutter 中，使用 try-catch 包装：try { await http.get(...); } catch (e) { print(e.toString()); }。使用环境变量存储密钥，避免泄露。

图关系

• 连接到：移动端集群
• 相关技能：react-native skill、flutter skill、expo skill、capacitor skill
• 依赖：用于嵌入的跨平台标签
• 交互对象：移动端生态系统中的 kmm 框架