Xcode构建OC转Swift框架报LibcOverlayShims.h错误如何解决

该错误属于Darwin系统模块导入顺序错误引发的类型可见性冲突：

• Swift编译时会自动依赖SwiftOverlayShims、LibcOverlayShims这类系统shim模块桥接POSIX/C标准库API，其中sem_t类型要求必须从正式的模块化路径Darwin.sys.semaphore导入，才能被shim模块识别。
• 触发场景是：在Swift文件、对应Target的桥接头、框架伞头中，在系统shim模块完成导入前，通过非模块化的方式直接导入了<sys/semaphore.h>或其他依赖sem_t的底层C头，提前声明了sem_t类型但没有将其纳入正式的Darwin模块命名空间，导致shim模块编译时判定sem_t声明来源非法，终止构建。
• 对应到你定位到的VisualizationController.swift文件，通常是文件顶部导入顺序错误，或是其依赖的同模块OC头存在非模块化的信号量头导入，或是项目编译配置允许了非模块化头导入打乱了模块加载顺序。

按优先级依次排查处理：

• 修正导入逻辑
  • 删除桥接头、框架伞头中所有直接导入<sys/semaphore.h>、<semaphore.h>这类底层POSIX头的语句，不要通过非模块化路径引入信号量相关定义。
  • 在VisualizationController.swift文件的最顶部优先导入Darwin模块，再写其他导入语句，保证系统模块按正确顺序加载：

    import Darwin
    import Foundation
    // 后续再导入其他自定义框架、第三方库的内容
    

  • 如果同模块的OC头文件确实需要使用sem_t类型，不要直接导入对应头文件，改用模块化导入语句@import Darwin.sys.semaphore;，确保类型从正确模块导出。
• 修正编译配置
  • 打开对应Target的Build Settings，将Allow Non-modular Includes in Framework Modules选项设置为No，关闭非模块化头导入权限，避免底层头被无序加载。
  • 检查框架的modulemap配置，不要在模块定义中提前暴露sys路径下的系统底层头。
• 清理编译缓存
  • 按下Shift+Command+K清理当前构建产物，删除DerivedData目录下对应项目的缓存文件，避免旧的错误编译残留导致问题重复出现。

禁止通过修改Xcode SDK内置的shim头、系统头文件的方式临时规避问题，这类修改会破坏本地工具链，切换编译环境或更新Xcode后问题会再次复现。

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