[Bug]: iOS UIScene template starts a second web app instance when an external display or AirPlay mirroring connects

Đang mở
#8,648 0 bình luận 3 reaction 1 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 2 ngày

@theproducer đang làm issue này rồi.

Từ ngày 9/10/2026.

Đánh giá

Issue này chưa được đánh giá.

Mô tả

platform: ios
Capacitor Version
💊   Capacitor Doctor  💊

Latest Dependencies:

  @capacitor/cli: 8.5.3
  @capacitor/core: 8.5.3
  @capacitor/android: 8.5.3
  @capacitor/ios: 8.5.3

Installed Dependencies:

  @capacitor/cli: 8.5.2
  @capacitor/android: 8.5.2
  @capacitor/core: 8.5.2
  @capacitor/ios: 8.5.2

[success] iOS looking great! 👌
Other API Details
npm --version: 11.4.2
node --version: v22.16.0
pod --version: 1.16.2
Xcode 26.3 (17C529)
Plugins mentioned below: @capacitor-community/sqlite 8.1.1, @capacitor/screen-orientation 8.0.2
Platforms Affected
  • iOS
  • Android
  • Web
Current Behavior

Since the 8.5 iOS template adopted UIScene, an app made from it starts a second, independent copy of the web app when an external display is connected or AirPlay screen mirroring starts.

Cause, in ios-pods-template/App/App/ (the SPM template has the same code):

  • AppDelegate.application(_:configurationForConnecting:options:) returns a configuration with delegateClass = SceneDelegate.self for every session role.
  • SceneDelegate.scene(_:willConnectTo:options:) creates a UIWindow with a new CAPBridgeViewController() for every UIWindowScene.

When an external display connects, iOS calls configurationForConnecting with the role UIWindowSceneSessionRoleExternalDisplayNonInteractive, even though UIApplicationSupportsMultipleScenes is false. Apple DTS confirms this and says the app should not create a window for that scene unless it wants to stop mirroring: https://developer.apple.com/forums/thread/815376. (Info.plist declares the SceneDelegate only for UIWindowSceneSessionRoleApplication, but the AppDelegate method returns it for all roles.)

Result: a second CAPBridgeViewController with its own WKWebView, bridge and plugin instances, running in parallel to the main one:

  • The external display shows this separate copy of the app (it stays on the start page and does not follow the device) instead of mirroring the device screen.
  • Both instances share local storage. With @capacitor-community/sqlite this caused database is locked errors in production on iPads.
  • Plugins initialise twice (e.g. in-app purchase listeners).
Expected Behavior

Only the windowApplication scene gets a CAPBridgeViewController. Connecting an external display or starting AirPlay mirroring does not start a second web view, and iOS mirrors the device screen as usual.

Project Reproduction

any app created from the Capacitor 8.5 iOS template reproduces it

Additional Information

No separate repository needed: any app created from the Capacitor 8.5 iOS template reproduces it.

  1. Run the app in the iOS Simulator (we used iPad Air 11-inch (M3), iOS 18.5; same with iOS 26.2).
  2. Simulator menu I/O → External Displays → any resolution.
  3. The Xcode/simctl console shows a second ⚡️ Loading app at capacitor://localhost..., and Safari → Develop lists two inspectable pages for the app.

In our run iOS connected the external display scene, disconnected it and connected it again, which gave three web views.

On a real device (iPad, iPadOS 18.7.8, debug build from Xcode, AirPlay screen mirroring to a Mac):

  1. Start the app, then start screen mirroring from Control Center.
  2. The Xcode console shows another ⚡️ Loading app at capacitor://localhost... each time mirroring starts.
  3. The Mac shows the app's start page and does not follow what happens on the iPad.

Proposed fix (what we use now), in AppDelegate.swift:

func application(_ application: UIApplication,
                 configurationForConnecting connectingSceneSession: UISceneSession,
                 options: UIScene.ConnectionOptions) -> UISceneConfiguration {
    let config = UISceneConfiguration(name: "Default Configuration", sessionRole: connectingSceneSession.role)
    if connectingSceneSession.role == .windowApplication {
        config.delegateClass = SceneDelegate.self
    }
    return config
}

Verified with the fix:

  • Simulator, iOS 18.5 and 26.2: only one web app instance with an external display attached, and also on a cold start with the display already attached. The Simulator shows a black external display for every app, because it does not mirror.
  • Real iPad, iPadOS 18.7.8, AirPlay to a Mac:
    • Starting mirroring several times, and a cold start while mirroring, always gave exactly one Loading app at.
    • The Mac mirrors the iPad screen and follows it.

An alternative is a role guard at the top of SceneDelegate.scene(_:willConnectTo:options:): guard session.role == .windowApplication else { return }.

Where the same code lives:

  • Templates on main (checked on 2026-10-08, identical to 8.5.2 and 8.5.3): ios-pods-template/App/App/AppDelegate.swift, ios-spm-template/App/App/AppDelegate.swift, and the SceneDelegate.swift next to them.
  • The UIScene migrator (#8544) copies SceneDelegate.swift and the configurationForConnecting method from the template archive, so a template fix reaches newly migrated projects. It skips projects that already contain UISceneConfiguration(name:, so apps that already migrated keep the old code and need a note in the update guide.
  • The 8.5 update guide shows the same snippet (step 3 in docs/main/updating/8-5.md of capacitor-docs): https://capacitorjs.com/docs/updating/8-5

Makes it worse: @capacitor/screen-orientation 8.0.2 holds CAPBridgeViewController strongly (ScreenOrientation.capViewController), so a bridge is never released and the web views of disconnected external display scenes keep running after the display is removed. Already reported in ionic-team/capacitor-plugins#2462.

See also: the same bug class in SDL: libsdl-org/SDL#16465.

Ngôn ngữ chính
TypeScript
Star
17.1k
Fork
1.3k
Merge trung bình
2 ngày 1 giờ
Pull request đã merge (30 ngày)
32

Chuẩn bị môi trường

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của ionic-team/capacitor

Tất cả issue của ionic-team/capacitor

Issue tương tự

Thêm issue về TypeScript

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.