问题
升级 Xcode 27 后,原本能正常编译的项目突然冒出大量错误,Issue Navigator 里全是这样一行:
python
The iOS Simulator deployment target 'IPHONEOS_DEPLOYMENT_TARGET' is set to 9.0,
but the range of supported deployment target versions is 15.0 to 27.1.x.
数字因 target 而异,可能是 8.0、9.0、11.0 或 12.0,但含义都一样。它通常是 error 而不是 warning,所以编译会直接失败。
先说结论:这不是你的代码写错了,也不是第三方库突然坏了。 看清这一点,能省下很多无用功。
为什么会这样
Deployment Target(最低部署版本)决定一个 target 最低能跑在哪个 iOS 系统上。苹果几乎每代大版本 Xcode 都会淘汰最老的一两个 iOS 版本,这道门槛也随之抬高。
Xcode 27 把门槛统一提到了 iOS 15.0。任何 target 只要声明的最低版本低于 15.0,就会被判为非法、直接报错。模拟器和真机都受这个限制,而且没有任何编译开关能绕过它。
所以最常见的情况是:你自己的 App target 本来就设得够高,但某个第三方库声明的最低版本还停留在 iOS 8 / 9 / 12。CocoaPods 会为每一个依赖单独生成一个 target,只要依赖链里有任何一个这样的 target,编译就过不去。
解决方案
情况一:报错指向你自己的 target
如果报错末尾写着 (in target 'xxx' from project 'xxx'),而这个 target 是你自己的,直接改它的部署版本:
- 在 Xcode 中选中项目,再选中对应 target;
- 打开 Build Settings,搜索
iOS Deployment Target; - 设为 15.0 或更高。
App Extension、Widget、测试 bundle 等其它 target 各自带一份设置,也要逐一检查,别漏掉。
情况二:报错指向第三方库(更常见)
在 Podfile 里加一个 post_install 钩子,遍历所有 Pod target,把低于 15.0 的统一抬到 15.0:
ruby
post_install do |installer|
installer.pods_project.targets.each do |target|
target.build_configurations.each do |config|
current = config.build_settings['IPHONEOS_DEPLOYMENT_TARGET']
if current.nil? || current.to_f < 15.0
config.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = '15.0'
end
end
end
end
注意:只对低于 15.0 的做抬升,不要无脑全部赋值,否则会把本来就要求更高版本的库错误地降级。
别忘了 platform 那一行
Podfile 顶部的 platform :ios, 'x.x' 决定的是 Pods 工程项目级 的默认配置,而 post_install 只能改到 target 级。如果这一行还停在低版本,工程里会残留项目级的旧设置。建议一起改:
ruby
platform :ios, '15.0'
进阶:如果你的 Podfile 里有两个 post_install
这是很多人卡住的地方。比如你之前为了解决某个库的私有头文件报错,已经写过一个 post_install;现在为了这次的部署版本问题,又想再加一个。结果一执行 pod install,直接报错:
swift
[!] An error occurred while processing the post-install hook of the Podfile.
Specifying multiple `post_install` hooks is unsupported.
这不是你的写法问题,而是 CocoaPods 的硬性限制。翻它的源码(cocoapods-core 的 podfile/dsl.rb)能看到:
ruby
def post_install(&block)
raise Informative, 'Specifying multiple `post_install` hooks is unsupported.' if @post_install_callback
@post_install_callback = block
end
它内部只用一个变量 @post_install_callback 保存回调,一旦检测到第二个就立刻抛错。所以正确做法不是写两个,而是把所有需要做的事合并进同一个 post_install 块。
下面是一个合并后的完整示例:既统一部署版本,又顺手修掉某个库引用私有头文件的问题,两段逻辑放进同一个块里:
ruby
post_install do |installer|
# 逻辑一:统一部署版本到 15.0,并清理老库残留的架构设置
installer.pods_project.targets.each do |target|
target.build_configurations.each do |config|
current = config.build_settings['IPHONEOS_DEPLOYMENT_TARGET']
if current.nil? || current.to_f < 15.0
config.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = '15.0'
end
config.build_settings.delete('VALID_ARCHS')
end
end
# 逻辑二:以某网络库为例,修复 Xcode 26+ 的私有头文件报错
installer.pods_project.targets.each do |target|
next unless target.name == 'AFNetworking'
target.source_build_phase.files.each do |file|
file_path = file.file_ref.real_path.to_s
next unless file_path.end_with?('.m', '.h')
content = File.read(file_path)
if content.include?('#import <netinet6/in6.h>')
new_content = content.gsub(
/#import\s+<netinet6\/in6\.h>\s*\n/,
"#import <netinet/in.h>\n"
)
File.chmod(0644, file_path)
File.write(file_path, new_content)
puts "[Fix] Replaced netinet6/in6.h in #{File.basename(file_path)}"
end
end
end
puts "✅ post_install 完成:部署版本已统一,头文件修复已执行"
end
要点:
- 一个
Podfile只允许一个post_install;有多个需求就全部塞进同一个块。 - 块内可以按需遍历多次
installer.pods_project.targets,不同逻辑各写一段,互不干扰。 - 依赖编译的产物会被脚本改写,所以合并后务必重新
pod install才会生效。
最后一步:重新 pod install + Clean Build
这是最容易被忽略、也最容易让人误以为"改了没用"的地方。
post_install 是 CocoaPods 在生成 Pods 工程时 才执行的脚本。改完 Podfile 如果不重新执行,脚本根本不会运行,工程里存的还是旧值。
bash
pod install
然后在 Xcode 里执行 Product > Clean Build Folder(Shift + Command + K),再重新编译。清理缓存这一步别省------失败的旧构建会留下脏数据,有时会让你误判修改到底有没有生效。
彻底清理缓存(顽固情况的最后手段)
如果改完、重装、Clean 之后问题依旧,可能是 CocoaPods 的本地缓存或锁定文件在作祟。执行以下命令清除深层缓存后重新安装 Pods:
bash
rm -rf ~/Library/Caches/CocoaPods
rm -rf Pods
rm Podfile.lock
pod deintegrate
pod setup
pod install
这套命令会删掉本地缓存、Pods 目录和 Podfile.lock,然后把 Pods 从工程中完全剥离再重装一遍。因为会重新解析和下载全部依赖,耗时较长 ,建议作为常规方法都无效后的最后手段。执行前确认 Podfile 已改好,否则重装后又得再来一次。
关于 Swift Package
如果依赖是用 Swift Package Manager 管理的,情况不同:即使某个包的 Package.swift 里声明了较低的 platform,Xcode 27 也不会因此报这个错。所以如果报错指向的是 SPM 包,先换个方向排查。
如果暂时不能支持 iOS 15
抬到 15.0 意味着放弃更老系统的用户。如果业务上实在不能丢,很遗憾,没有编译开关能让 Xcode 27 产出低于 15.0 的包。唯一可行的过渡方案是新旧 Xcode 共存:用 xcodes 之类的工具同时安装两个版本,需要出低版本包时用旧 Xcode 构建。
但要知道这只是缓冲。App Store 每年都要求用较新的 SDK 构建,窗口期有限。趁这段时间按自己的节奏完成升级,总好过被提交截止日逼着临时改。
小结
一句话记住:
这个错误是 Xcode 27 把最低部署版本门槛抬到了 15.0,而项目里某些 target 还低于这个值。把 App 及所有相关 target、Pod 依赖统一抬到 15.0 或以上,多个 hook 合并成一个,改完记得
pod install和 Clean Build。
参考:
- Xcode 27 Minimum Deployment Target Is iOS 15: How to Fix(部分结论参考了其测试现象,行文与解决方案均为原创)
- Apple Build Settings Reference