KaMPKit项目常见问题排查指南

KaMPKit项目常见问题排查指南

KaMPKit KaMP Kit by Touchlab. A collection of code & tools designed to get your mobile team started quickly w/Kotlin Multiplatform 项目地址: https://gitcode.com/gh_mirrors/ka/KaMPKit

关于Android SDK路径问题

问题现象：构建项目时出现"SDK location not found"错误提示，系统要求定义ANDROID_SDK_ROOT环境变量或在项目配置中指定SDK路径。

技术背景：Android开发需要配置SDK路径，这是Android开发环境的基础配置。Android Studio通常会在安装过程中建议将SDK安装在标准位置。

解决方案：

1. 推荐使用Android Studio打开项目，它会自动创建并配置local.properties文件
2. 如需手动配置：
   • 在项目根目录创建local.properties文件
   • 添加以下内容（替换[YOUR_USER_NAME]为你的实际用户名）：

     sdk.dir=/Users/[YOUR_USER_NAME]/Library/Android/sdk
     

注意事项：

• 该文件包含本地环境特有的配置，不应提交到版本控制系统
• 不同操作系统下SDK默认路径可能不同（Windows/Linux路径与macOS不同）

关于Xcode框架找不到问题

问题现象：在Xcode中运行时出现"Framework not found shared_umbrella"错误。

技术背景：当使用CocoaPods管理依赖时，必须使用.xcworkspace文件而非.xcodeproj文件打开项目，因为前者包含了所有Pod依赖的完整工作空间配置。

解决方案：

1. 关闭当前打开的.xcodeproj文件
2. 在项目目录中找到并打开.xcworkspace文件
3. 重新构建项目

深入理解：CocoaPods通过创建工作空间来整合主项目和所有Pod依赖，确保构建系统能找到所有必要的框架和资源。

关于Swift模块导入失败问题

问题现象：Xcode项目中import shared语句报错"no such module: 'shared'"。

技术背景：这通常是由于CocoaPods依赖解析或缓存问题导致的，特别是在多人协作或环境变更时容易出现。

解决方案步骤：

1. 完全关闭Xcode
2. 删除项目中的Pods目录（位于iOS项目根目录）
3. 在终端中导航到iOS项目目录
4. 执行pod install命令重新安装依赖
5. 重新打开.xcworkspace文件

可能原因分析：

• CocoaPods版本不一致
• Xcode版本差异
• 缓存文件损坏
• 项目文件被意外修改

关于iOS框架体积增大问题

问题现象：添加Kotlin/Native代码后，iOS框架二进制文件体积明显增大。

技术背景：Kotlin/Native编译到iOS平台时会生成额外的代码和元数据，特别是公共API会生成对应的Objective-C头文件，这些都会增加最终产物的体积。

解决方案：

1. 首先确认实际上传到App Store后的真实影响（调试符号和bitcode不会包含在最终用户下载的包中）
2. 优化共享代码的可见性：
   • 将不需要外部访问的代码标记为private或internal
   • 仅暴露必要的API给iOS平台
3. 考虑启用Kotlin的显式API模式，强制进行API可见性检查

最佳实践建议：

• 定期检查共享模块的公共API
• 使用模块化设计，分离核心逻辑和平台特定代码
• 进行产物大小分析，识别可优化的部分

问题排查通用建议

1. 环境一致性：确保团队成员使用相同版本的开发工具和依赖库
2. 清理重建：遇到奇怪问题时，尝试清理构建目录和缓存
3. 增量验证：在添加新功能时，分小步验证，便于定位问题
4. 日志分析：仔细阅读构建日志，往往包含解决问题的关键线索

后续支持

如果在使用过程中遇到本文未涵盖的问题，建议通过项目提供的联系方式反馈问题，包括：

• 详细的问题描述
• 重现步骤
• 相关错误日志
• 环境信息（操作系统版本、工具版本等）

希望本指南能帮助你顺利使用KaMPKit进行跨平台开发。随着项目的演进，可能会遇到新的问题场景，建议保持关注项目的更新和文档补充。

KaMPKit KaMP Kit by Touchlab. A collection of code & tools designed to get your mobile team started quickly w/Kotlin Multiplatform 项目地址: https://gitcode.com/gh_mirrors/ka/KaMPKit