Vapor项目Package文件添加APNS依赖出现Circular reference错误求助

在Vapor项目的Package文件中添加APNS依赖后出现"Circular reference"错误，移除该依赖则恢复正常，当前依赖配置如下：

dependencies: [
        // 💧 A server-side Swift web framework.
        .package(url: "https://github.com/vapor/vapor.git", from: "4.0.0"),
        .package(url: "https://github.com/vapor/fluent.git", from: "4.0.0"),
        .package(url: "https://github.com/vapor/fluent-postgres-driver.git", from: "2.0.0"),
        .package(url: "https://github.com/vapor/leaf.git", from: "4.0.0"),
        .package(url: "https://github.com/vapor/jwt.git", from: "4.0.0"),
        .package(url: "https://github.com/vapor/apns.git", from: "3.0.0"), <=== 新增的依赖
        .package(url: "https://github.com/m-barthelemy/vapor-queues-fluent-driver.git", from: "3.0.0-beta1"),
        .package(url: "https://github.com/vapor-community/mailgun.git", from: "5.0.0")
    ],

错误成因分析 #

循环引用错误本质是Swift Package Manager（SPM）在解析依赖树时发现包之间形成了闭环依赖（比如A依赖B，B依赖C，C又依赖A）。你的情况大概率是版本范围冲突引发的间接循环，而非直接的依赖闭环：

• APNS 3.x本身依赖Vapor 4.x、JWT 4.x等包，这些你已经直接引入。如果APNS依赖的子包版本范围和你现有依赖的版本范围不兼容，SPM可能会尝试拉取同一包的不同版本，进而在解析时误判为循环引用。
• vapor-queues-fluent-driver 3.0.0-beta1或mailgun 5.0.0的依赖链中，可能存在与APNS依赖的包版本范围冲突的情况，导致SPM无法构建合法的依赖树，最终抛出循环引用错误。

排查步骤 #

• 执行swift package show dependencies命令，查看完整的依赖树，重点检查APNS的依赖项是否与现有依赖形成闭环。
• 将APNS依赖锁定到具体版本，避免SPM自动拉取可能存在冲突的新版本：

  .package(url: "https://github.com/vapor/apns.git", exact: "3.0.0"),
  

• 逐个临时移除其他第三方依赖（比如先去掉vapor-queues-fluent-driver），测试是否还会出现循环引用，定位到冲突的依赖包。
• 查看APNS 3.x仓库的Package.swift文件，确认其依赖的版本要求，确保与你项目中对应包的版本范围一致。

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