macOS下Swift Package Manager链接归档库swift test报错排查

• 核心问题是Swift Package Manager的链接API误用，叠加macOS与Linux平台链接器的参数解析逻辑差异，最终导致macOS下测试链接失败。
• SPM的.linkedLibrary()配置对应链接器的-l参数，仅接受库的短名，不接受任何文件路径：短名指去掉库文件名的lib前缀、.a/.dylib/.so后缀后的部分，例如要链接libfoo.a，正确传值为"foo"，最终会被展开为-lfoo传递给链接器。
• 两个平台链接器的行为差异直接导致了现象不一致：
  • Linux环境使用的GNU ld/LLD对参数做了兼容扩展，如果-l后跟随路径格式的字符串，会直接尝试加载对应路径的库文件，因此错误配置在Linux下可以正常运行。
  • macOS环境使用的Apple ld严格遵循参数规范，不会识别-l后的路径，只会将传入的完整字符串作为库名，自动拼接lib前缀和平台对应的库后缀，到预设的搜索路径下查找文件。例如传入/path/to/libfoo.a时，链接器会尝试查找lib/path/to/libfoo.a.a、lib/path/to/libfoo.a.dylib这类不存在的文件，自然抛出"library not found"错误。
• swift build正常运行的原因是：SPM编译库类型Target时仅做源码编译，不会执行最终的符号解析与链接（允许外部依赖的符号暂时未定义），只有构建可执行文件、测试Bundle这类可运行产物时才会走完整链接流程，因此编译阶段不会触发错误，直到swift test需要生成测试可执行文件时才会暴露链接问题。

• 错误将库的完整路径传给了仅接受库短名的.linkedLibrary()API，不符合参数要求。
• 未通过.linkedLibrarySearchPath()配置外部库的搜索目录，链接器不知道要到项目下的Libraries文件夹查找依赖库。
• 之前尝试的相对路径、去掉文件后缀、替换为动态库等方案，本质上还是在给.linkedLibrary()传路径，没有修正API误用的核心问题，因此全部失效。

只需修改FooLibrary Target的linkerSettings配置即可，不需要给测试Target重复配置（SPM会自动将依赖Target的链接参数传递给上层构建产物）：

linkerSettings: [
    // 配置库搜索路径，路径相对于Package.swift所在的项目根目录
    .linkedLibrarySearchPath("Libraries"),
    // 传入去掉lib前缀和后缀的库短名
    .linkedLibrary("foo")
]

修改完成后重新执行swift test即可正常完成链接、运行测试。后续如果需要切换为Rust编译的动态库（macOS为.dylib、Linux为.so），不需要修改任何SPM配置，链接器会自动按平台规则匹配对应格式的库文件。

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