iOS App启动后UIWindow上下出现黑边问题排查求助

安全阿岳

2026-9-25

解决方案

1 检查Launch Screen配置

iOS会通过Launch Screen的适配规则判断App是否支持全面屏分辨率，配置错误会导致全局上下留黑边，操作步骤：

打开Xcode项目设置，进入TARGETS → 你的App目标 → General选项卡
找到「App Icons and Launch Images」区块，确认「Launch Screen File」选中了正确的Launch Screen故事板，不可留空
不推荐使用旧版Launch Image资源集适配启动页，建议统一使用Launch Screen故事板

2 调整SwiftUI视图的安全区域适配

UIHostingController默认会预留安全区域边距，你可以给根SwiftUI视图添加全局安全区域忽略配置，修改HostingViewController代码如下：

class HostingViewController: UIHostingController<Text> {
    required init?(coder aDecoder: NSCoder) {
        super.init(coder: aDecoder, rootView: Text("text").edgesIgnoringSafeArea(.all))
    }
}

如果修改后黑边消失，可根据业务需求后续调整需要忽略的安全区域范围。

3 修正SceneDelegate的Window初始化逻辑

手动给Window设置UIScreen.main.bounds容易在多场景、分屏场景下出现尺寸适配错误，修改SceneDelegate代码如下：

class SceneDelegate: UIResponder, UIWindowSceneDelegate {
    var window : UIWindow?
    func scene(_ scene: UIScene, willConnectTo session: UISceneSession, options connectionOptions: UIScene.ConnectionOptions) {
        guard let windowScene = scene as? UIWindowScene else { return }
        self.window = UIWindow(windowScene: windowScene)
        // 无需手动设置frame，UIKit会自动根据windowScene适配正确尺寸
        let vc = UIStoryboard(name: "Main", bundle: .main).instantiateInitialViewController()
        self.window!.rootViewController = vc
        self.window!.makeKeyAndVisible()
    }
}