为SocketRocket添加SPM支持编译报错：找不到SRDelegateController.h

背景 #

我复刻了Facebook开源的Objective-C项目SocketRocket，正在为其添加Swift Package Manager（SPM）支持。

已配置的文件 #

1. Package.swift #

let package = Package(
    name: "SocketRocket",
    platforms: [
        .iOS(.v12)
    ],
    products: [
        .library(
            name: "SocketRocket",
            targets: ["SocketRocket"]
        )
    ],
    targets: [
        .target(
            name: "SocketRocket",
            path: "SocketRocket",
            publicHeadersPath: "."
        ),
        .testTarget(
            name: "SocketRocketTests",
            dependencies: ["SocketRocket"],
            path: "Tests"
        )
    ]
)

2. Umbrella头文件 SocketRocket.h #

#import <SocketRocket/NSRunLoop+SRWebSocket.h>
#import <SocketRocket/NSURLRequest+SRWebSocket.h>
#import <SocketRocket/SRSecurityPolicy.h>
#import <SocketRocket/SRWebSocket.h>

3. module.modulemap文件 #

module SocketRocket {
    header "SocketRocket.h"
    export *
}

编译问题 #

构建调试版本时出现以下错误：

Building for debugging...
fatal error: 'SRDelegateController.h' file not found
#import "SRDelegateController.h"
^~~~~~~~~~~~~~~~~~~~~~~~
1 error generated.

同时观察到每次重新编译时，已编译文件数量不稳定（比如0、3、4、19个），例如会输出[0/19] Compiling SRIOConsumerPool.m这类内容。

解决方案 #

问题根源 #

当前publicHeadersPath: "."仅暴露了根目录下的公共头文件，但项目中的私有头文件（如SRDelegateController.h）可能存放在子目录或未被纳入编译的头文件搜索路径，导致编译时无法找到。

修复步骤 #

1. 调整Package.swift的target配置，添加头文件搜索路径

.target(
    name: "SocketRocket",
    path: "SocketRocket",
    publicHeadersPath: ".",
    // 添加根目录及所有子目录到头文件搜索路径
    headerSearchPaths: ["."]
)

如果私有头文件集中在特定子目录（如Internal），可更精准指定：headerSearchPaths: [".", "Internal"]。

2. 修正私有头文件的导入路径
   对于项目内部使用的私有头文件，源文件中应使用相对路径导入，比如#import "./SRDelegateController.h"，而非直接#import "SRDelegateController.h"，避免依赖全局搜索路径。

3. 确保modulemap位置正确
   将module.modulemap放在SocketRocket根目录（与Umbrella头文件同目录），若位置特殊，需在target中显式指定：

.target(
    name: "SocketRocket",
    path: "SocketRocket",
    publicHeadersPath: ".",
    headerSearchPaths: ["."],
    moduleMapPath: "./module.modulemap"
)

4. 清理SPM缓存后重新构建
   缓存可能导致编译状态异常，执行以下命令重置：

swift package clean
swift build

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