macOS下Swift CLI开发环境配置问题：SwiftPM执行报错

问题场景 #

只做CLI开发，没装Xcode，发现swift --version能正常运行，就没按官方《Install Swift》流程装Swift。跟着教程创建CLI项目后，swift run MyCLI报链接错误，但直接跑单个Swift文件没问题。

环境信息 #

swift --version
swift-driver version: 1.120.5 Apple Swift version 6.1 (swiftlang-6.1.0.110.21 clang-1700.0.13.3)
Target: arm64-apple-macosx15.0

swift package --version
Swift Package Manager - Swift 6.1.0

操作与报错详情 #

创建项目并运行的命令：

➜  MyCLI swift package init --name MyCLI --type executable
Creating executable package: MyCLI
Creating Package.swift
Creating .gitignore
Creating Sources/
Creating Sources/main.swift
➜  MyCLI swift run MyCLI

报错输出：

error: 'mycli': Invalid manifest (compiled with: ["/Library/Developer/CommandLineTools/usr/bin/swiftc", "-vfsoverlay", "/var/folders/ht/yq7cghwx62x_dsm_q6qbtfp40000gn/T/TemporaryDirectory.JZ0Atb/vfs.yaml", "-L", "/Library/Developer/CommandLineTools/usr/lib/swift/pm/ManifestAPI", "-lPackageDescription", "-Xlinker", "-rpath", "-Xlinker", "/Library/Developer/CommandLineTools/usr/lib/swift/pm/ManifestAPI", "-target", "arm64-apple-macosx14.0", "-F", "/Library/Developer/CommandLineTools/Library/Developer/Frameworks", "-sdk", "/Library/Developer/CommandLineTools/SDKs/MacOSX.sdk", "-swift-version", "6", "-I", "/Library/Developer/CommandLineTools/usr/lib/swift/pm/ManifestAPI", "-sdk", "/Library/Developer/CommandLineTools/SDKs/MacOSX.sdk", "-package-description-version", "6.1.0", "/Users/bifuhong/Documents/code/MyCLI/Package.swift", "-o", "/var/folders/ht/yq7cghwx62x_dsm_q6qbtfp40000gn/T/TemporaryDirectory.IGmE3P/mycli-manifest"])
error: link command failed with exit code 1 (use -v to see invocation)
Undefined symbols for architecture arm64:
  "PackageDescription.Package.__allocating_init(name: Swift.String, defaultLocalization: PackageDescription.LanguageTag?, platforms: [PackageDescription.SupportedPlatform]?, pkgConfig: Swift.String?, providers: [PackageDescription.SystemPackageProvider]?, products: [PackageDescription.Product], dependencies: [PackageDescription.Package.Dependency], targets: [PackageDescription.Target], swiftLanguageVersions: [PackageDescription.SwiftVersion]?, cLanguageStandard: PackageDescription.CLanguageStandard?, cxxLanguageStandard: PackageDescription.CXXLanguageStandard?) -> PackageDescription.Package", referenced from:
      _main in Package-1.o
ld: symbol(s) not found for architecture arm64
clang: error: linker command failed with exit code 1 (use -v to see invocation)
error: 'mycli': Invalid manifest (compiled with: ["/Library/Developer/CommandLineTools/usr/bin/swiftc", "-vfsoverlay", "/var/folders/ht/yq7cghwx62x_dsm_q6qbtfp40000gn/T/TemporaryDirectory.79oKx4/vfs.yaml", "-L", "/Library/Developer/CommandLineTools/usr/lib/swift/pm/ManifestAPI", "-lPackageDescription", "-Xlinker", "-rpath", "-Xlinker", "/Library/Developer/CommandLineTools/usr/lib/swift/pm/ManifestAPI", "-target", "arm64-apple-macosx14.0", "-F", "/Library/Developer/CommandLineTools/Library/Developer/Frameworks", "-sdk", "/Library/Developer/CommandLineTools/SDKs/MacOSX.sdk", "-swift-version", "6", "-I", "/Library/Developer/CommandLineTools/usr/lib/swift/pm/ManifestAPI", "-sdk", "/Library/Developer/CommandLineTools/SDKs/MacOSX.sdk", "-package-description-version", "6.1.0", "/Users/bifuhong/Documents/code/MyCLI/Package.swift", "-o", "/var/folders/ht/yq7cghwx62x_dsm_q6qbtfp40000gn/T/TemporaryDirectory.ANIb7j/mycli-manifest"])
error: link command failed with exit code 1 (use -v to see invocation)
Undefined symbols for architecture arm64:
  "PackageDescription.Package.__allocating_init(name: Swift.String, defaultLocalization: PackageDescription.LanguageTag?, platforms: [PackageDescription.SupportedPlatform]?, pkgConfig: Swift.String?, providers: [PackageDescription.SystemPackageProvider]?, products: [PackageDescription.Product], dependencies: [PackageDescription.Package.Dependency], targets: [PackageDescription.Target], swiftLanguageVersions: [PackageDescription.SwiftVersion]?, cLanguageStandard: PackageDescription.CLanguageStandard?, cxxLanguageStandard: PackageDescription.CXXLanguageStandard?) -> PackageDescription.Package", referenced from:
      _main in Package-1.o
ld: symbol(s) not found for architecture arm64
clang: error: linker command failed with exit code 1 (use -v to see invocation)

单个Swift文件运行正常：

cat temp.swift && swift temp.swift
print(1)
1

原因分析 #

问题出在Swift版本与Command Line Tools中的Swift Package Manager组件不兼容。你用的是Swift 6.1，但仅靠Command Line Tools提供的SPM缺少该版本PackageDescription库中对应的初始化符号，导致解析Package.swift时链接失败。而单个文件运行不需要处理Package.swift，所以能正常执行。

解决方案 #

1. 安装官方Swift工具链：下载对应版本的官方Swift工具链（无需安装Xcode），安装后配置环境变量让系统优先使用该工具链的组件。
2. 更新Command Line Tools：执行xcode-select --install更新到最新版，确保其SPM组件支持当前Swift版本。
3. 指定匹配的SDK运行：运行时手动指定与Swift目标版本一致的SDK，命令示例：

   swift run --sdk /Library/Developer/CommandLineTools/SDKs/MacOSX15.0.sdk MyCLI
   

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