Xcode 13内置Swift包管理器如何使用.netrc凭证下载鉴权二进制Swift包

问题描述 #

我使用的是Xcode 13.1内置的Swift Package Manager，而非基于Package.swift的命令行版本。

我的其中一个依赖是仅二进制包，该包的Package.swift内容如下：

// swift-tools-version:5.5

import PackageDescription

let package = Package(
    name: "MyLibrary",
    products: [
        .library(
            name: "MyLibrary",
            targets: ["MyLibrary"]),
    ],
    dependencies: [],
    targets: [
        .binaryTarget(
            name: "MyLibrary",
            url: "https://gitlab.example.com/api/v4/projects/85/packages/generic/mylibrary/1.0.1/MyLibrary.xcframework.zip",
            checksum: "..."
        )
    ]
)

该二进制文件存储在GitLab通用包仓库中。

我已经将托管该包的Git仓库添加到项目的「包依赖」中，生成了具备API和仓库访问权限的个人访问令牌，并将其添加到.netrc文件中，配置如下：

machine gitlab.example.com
login gitlab-token
password MY_TOKEN_HERE

当我运行xcodebuild -resolvePackageDependencies命令，或是在Xcode图形界面中点击「文件」→「包」→「解析包版本」时，Git仓库可以成功克隆，但会弹出如下报错：

failed downloading 'https://gitlab.example.com/api/v4/projects/85/packages/generic/mylibrary/1.0.1/MyLibrary.xcframework.zip' which is required by binary target 'MyLibrary': badResponseStatusCode(401)

我尝试将相同的凭证添加到macOS钥匙串中，期望Xcode可以从中读取凭证，但仍然出现相同报错。

我在Swift Package Manager CLI的源码中看到，其本身是支持二进制下载场景的凭证处理的，但Xcode似乎不支持该能力。

由于项目中的其他开发者难以接受基于Package.swift的包管理方式，我无法切换到命令行包管理模式。

请问是否有办法让Xcode也可以使用.netrc中的凭证完成上述二进制文件的下载？

备注：本问题同步发布于Apple Developer Forum

解决方案 #

1. 优先升级Xcode版本 #

该问题是Xcode 13.1~13.2版本的已知缺陷，苹果在Xcode 13.3版本正式修复了这个问题：内置的Swift Package Manager已经支持下载二进制目标时读取.netrc文件中的凭证，升级到Xcode 13.3及以上版本后，你现有的配置即可直接生效，不需要额外改动。

需要额外注意：.netrc文件的权限必须设置为仅当前用户可读可写（权限值600），否则Swift Package Manager会出于安全考虑忽略该文件，执行以下命令修改权限即可：

chmod 600 ~/.netrc

2. 无法升级Xcode的替代方案 #

如果受项目约束无法升级Xcode，可以选择以下两种临时方案：

• 修改下载URL拼接令牌：GitLab通用包仓库支持在URL中直接拼接私有令牌参数，将你的Package.swift中的二进制目标地址修改为如下格式即可：

  .binaryTarget(
      name: "MyLibrary",
      url: "https://gitlab.example.com/api/v4/projects/85/packages/generic/mylibrary/1.0.1/MyLibrary.xcframework.zip?private_token=你的个人访问令牌",
      checksum: "..."
  )
  

  该方案的缺点是令牌会明文写在Package.swift中，仅适合内部私有仓库使用，不要提交到公开仓库。
• 预下载二进制包本地引用：提前手动下载对应版本的MyLibrary.xcframework.zip解压到本地项目目录，把binaryTarget的配置改为本地路径引用：

  .binaryTarget(
      name: "MyLibrary",
      path: "./Frameworks/MyLibrary.xcframework"
  )
  

  该方案不需要修改鉴权配置，适合临时应急使用。

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