SQLDelight iOS编译问题：解决"Undefined symbols for architecture arm64"错误

问题背景

在使用SQLDelight进行Kotlin跨平台开发时，iOS平台编译过程中可能会遇到"Undefined symbols for architecture arm64"的错误。这个问题通常出现在多模块项目中，特别是当数据库模块与其他模块存在依赖关系时。

错误表现

编译失败时，控制台会输出大量未定义的SQLite3符号错误，例如：

Undefined symbols for architecture arm64:
  "_sqlite3_bind_blob", referenced from:
      _co_touchlab_sqliter_sqlite3_sqlite3_bind_blob_wrapper69 in CoreDi.framework.o
  "_sqlite3_bind_double", referenced from:
      _co_touchlab_sqliter_sqlite3_sqlite3_bind_double_wrapper71 in CoreDi.framework.o
  ...

问题根源

这个问题的本质是链接器无法找到SQLite3库的符号定义。在iOS平台上，SQLite3虽然是系统内置库，但在构建Kotlin/Native框架时，需要显式地告诉链接器使用这个库。

解决方案

方案一：使用SQLDelight的schema依赖配置

在多模块项目中，推荐使用SQLDelight提供的schema依赖功能。在依赖数据库模块的gradle配置中添加：

sqldelight {
    databases {
        create("MyDatabase") {
            packageName.set("com.core.di")
            dependency(projects.coreDatabase) // 指向数据库模块
        }
    }
}

这种方式会自动处理SQLite3的链接问题，是最推荐的解决方案。

方案二：显式启用SQLite链接

在gradle配置中直接启用SQLite链接：

sqldelight {
    linkSqlite = true
}

这个选项会确保SQLite3库被正确链接。

方案三：手动添加链接器标志

如果上述方法不奏效，可以手动添加链接器标志：

1. 在Xcode中：

   • 打开项目设置
   • 进入"Build Settings"
   • 找到"Other Linker Flags"
   • 添加-lsqlite3

2. 在gradle中：

   binaries.all {
       linkerOpts("-lsqlite3")
   }
   

多模块项目最佳实践

对于复杂的多模块Kotlin跨平台项目，建议：

1. 将数据库逻辑集中在一个独立模块中
2. 使用schema依赖让其他模块引用数据库模块
3. 避免在多个模块中重复定义数据库
4. 合理控制导出到框架的API范围，减少不必要的符号暴露

注意事项

1. 调试版本和发布版本的配置可能不同，需要确保两者都正确配置
2. 静态框架和动态框架的链接行为可能有差异
3. 清理构建缓存有时可以解决奇怪的问题，使用--no-build-cache参数进行测试
4. 注意SQLDelight版本与Kotlin版本的兼容性

总结

SQLDelight在iOS平台上的链接问题通常是由于SQLite3库未被正确链接导致的。通过合理配置schema依赖或显式启用SQLite链接，可以解决大多数此类问题。在多模块项目中，保持清晰的模块边界和依赖关系是预防这类问题的关键。