メインコンテンツまでスキップ
バージョン: v8

Capacitor 7からCapacitor 8へのアップデート

このガイドでは、プロジェクトを現在のCapacitor 8バージョンにアップデートする手順と、公式プラグインの破壊的変更の一覧を紹介します。

Capacitor設定ファイルの破壊的変更​

appendUserAgentにはiOSでユーザーエージェントを追加する前に2つの空白を追加するバグがありましたが、修正されました。ユーザーエージェントの変更を防ぎたい場合は、ios.appendUserAgentに余分な空白を追加してください。ルートのappendUserAgentには追加しないでください。Androidにも空白が追加されてしまいます。

@capacitor/cliの破壊的変更​

Capacitor CLIはデフォルトでiOS SPMプロジェクトを作成するようになりました。 既存のアプリには影響しませんが、iosフォルダを削除して再度npx cap add iosを実行すると、SPMテンプレートを使用して作成されます。CocoaPodsテンプレートを使用したい場合は、代わりにnpx cap add ios --packagemanager CocoaPodsを実行してください。

@capacitor/androidの破壊的変更​

bridge_layout_main.xmlファイルは削除されました。アプリコードやプラグインコードでこれを参照していた場合は、代わりにcapacitor_bridge_layout_main.xmlを使用してください。

@capacitor/iosの破壊的変更​

CapacitorはCAPBridgeViewControllerのviewDidAppearとviewWillTransitionの通知を発行するようになりました。これらのイベントを発行するためにCAPBridgeViewControllerの拡張機能を使用している場合は、削除してください。

NodeJS 22以上​

Capacitor 8にはNodeJS 22以上が必要です。（最新のLTSバージョンを推奨します。）

CLIを使用した移行​

プロジェクトにlatestバージョンのCapacitor CLIをインストールします：

npm i -D @capacitor/cli@latest

インストール後、以下を実行するだけでCLIが移行を処理します。

npx cap migrate

移行の手順が完了できない場合は、ターミナルの出力に追加情報が表示されます。手動で移行を行う手順は以下に記載されています。

iOS​

以下のガイドでは、Capacitor 7 iOSプロジェクトをCapacitor 8にアップグレードする方法を説明します。

Xcodeのアップグレード​

Capacitor 8にはXcode 26.0以上が必要です。

iOSデプロイメントターゲットの引き上げ​

Xcodeプロジェクトで以下を行います：プロジェクトエディター内でProjectを選択し、Build Settingsタブを開きます。Deploymentセクションで、iOS Deployment TargetをiOS 15.0に変更します。すべてのアプリTargetsに対して同じ手順を繰り返します。

次に、プロジェクトがCocoaPodsを使用している場合は、ios/App/Podfileを開いてiOSバージョンを15.0に更新します：

platform :ios, '15.0'

Android​

以下のガイドでは、Capacitor 7 AndroidプロジェクトをCapacitor 8にアップグレードする方法を説明します。

Android Studioのアップグレード​

Capacitor 8にはAndroid Studio Otter | 2025.2.1以降が必要です。

更新後、Android Studioはgradleに関連する更新やパッケージをビルドファイルに移動する作業を支援できます。開始するには、Tools -> AGP Upgrade Assistantを実行します。

APG Upgrade Assistant

Androidプロジェクト変数の更新​

variables.gradleファイルで、値を以下の新しい最小値に更新します

minSdkVersion = 24
compileSdkVersion = 36
targetSdkVersion = 36
androidxActivityVersion = '1.11.0'
androidxAppCompatVersion = '1.7.1'
androidxCoordinatorLayoutVersion = '1.3.0'
androidxCoreVersion = '1.17.0'
androidxFragmentVersion = '1.8.9'
coreSplashScreenVersion = '1.2.0'
androidxWebkitVersion = '1.14.0'
junitVersion = '4.13.2'
androidxJunitVersion = '1.3.0'
androidxEspressoCoreVersion = '3.7.0'
cordovaAndroidVersion = '14.0.1'

非推奨のGradleプロパティ名構文の置き換え​

Gradleはプロパティ名構文を非推奨とし、値の前に=を使用することを推奨しています。現時点では警告のみですが、将来的には動作しなくなります。

# app/build.gradle
android {
-    namespace "com.getcapacitor.myapp"
-    compileSdk rootProject.ext.compileSdkVersion
+    namespace = "com.getcapacitor.myapp"
+    compileSdk = rootProject.ext.compileSdkVersion
...
     defaultConfig {
...
         aaptOptions {
-            ignoreAssetsPattern '!.svn:!.git:!.ds_store:!*.scc:.*:!CVS:!thumbs.db:!picasa.ini:!*~'
+            ignoreAssetsPattern = '!.svn:!.git:!.ds_store:!*.scc:.*:!CVS:!thumbs.db:!picasa.ini:!*~'

google servicesプラグインの更新​

# build.gradle

    dependencies {
        classpath 'com.android.tools.build:gradle:8.7.2'
-       classpath 'com.google.gms:google-services:4.4.2'
+       classpath 'com.google.gms:google-services:4.4.4'

gradleプラグインを8.13.0に更新​

# build.gradle

    dependencies {
-       classpath 'com.android.tools.build:gradle:8.7.2'
+       classpath 'com.android.tools.build:gradle:8.13.0'

gradleラッパーを8.14.3に更新​

# gradle-wrapper.properties

distributionBase=GRADLE_USER_HOME
distributionPath=wrapper/dists
- distributionUrl=https\://services.gradle.org/distributions/gradle-8.11.1-all.zip
+ distributionUrl=https\://services.gradle.org/distributions/gradle-8.14.3-all.zip
zipStoreBase=GRADLE_USER_HOME
zipStorePath=wrapper/dists

kotlinバージョンの更新​

プロジェクトでkotlinを使用している場合は、kotlin_version変数を'2.2.20'に更新してください。

configChangesにdensityを追加​

アプリのリサイズ時にwebViewが再読み込みされるのを防ぐため、AndroidManifest.xmlのアプリactivityのconfigChangesにdensityを追加します。

- android:configChanges="orientation|keyboardHidden|keyboard|screenSize|locale|smallestScreenSize|screenLayout|uiMode|navigation"
+ android:configChanges="orientation|keyboardHidden|keyboard|screenSize|locale|smallestScreenSize|screenLayout|uiMode|navigation|density"

プラグイン​

プラグインはバージョン8.0.0に更新されました。最新バージョンを使用するように更新してください。

以下のプラグイン機能が変更または削除されました。それに応じてコードを更新してください。

Action Sheet​

  • androidxMaterialVersion変数が1.13.0に更新されました。

Barcode Scanner​

scanOrientationオプションは、Android 16以降の大画面デバイス（タブレットなど）では効果がありません。アプリのAndroidManifest.xmlの<application>または<activity>内に<property android:name="android.window.PROPERTY_COMPAT_ALLOW_RESTRICTED_RESIZABILITY" android:value="true" />を追加することで、この動作をオプトアウトできます。ただし、このオプトアウトは一時的なものであり、Android 17では機能しなくなることに注意してください。Androidは大画面での特定の向きの設定を推奨していません。通常のAndroidスマートフォンはこの変更の影響を受けません。詳細については、https://developer.android.com/about/versions/16/behavior-changes-16#adaptive-layouts のAndroidドキュメントを確認してください。

Browser​

  • androidxBrowserVersion変数が1.9.0に更新されました。

Camera​

  • androidxExifInterfaceVersion変数が1.4.1に更新されました。
  • androidxMaterialVersion変数が1.13.0に更新されました。

Geolocation​

  • kotlinxCoroutinesVersion変数が1.10.2に更新されました。
  • timeoutプロパティは、以前のWebとAndroidのgetCurrentPositionのみではなく、AndroidとiOSのすべてのリクエストに適用されるようになりました。これはプラグインのドキュメントに記載されている内容と一致しています。アプリで位置情報をリクエストする際にタイムアウトが発生し始めた場合は、より高いtimeout値の使用を検討してください。AndroidのwatchPositionでは、バージョン8.0.0で導入されたintervalパラメータを使用できます。

Google Maps​

  • googleMapsPlayServicesVersion変数が19.2.0に更新されました。
  • googleMapsUtilsVersion変数が3.19.1に更新されました。
  • googleMapsKtxVersion変数が5.2.1に更新されました。
  • googleMapsUtilsKtxVersion変数が5.2.1に更新されました。
  • kotlinxCoroutinesVersion変数が1.10.2に更新されました。
  • androidxCoreKTXVersion変数が1.17.0に更新されました。
  • kotlin_version変数が2.2.20に更新されました。

Push Notifications​

  • firebaseMessagingVersion変数が25.0.1に更新されました。

Screen Orientation​

lockメソッドは、Android 16以降の大画面デバイス（タブレットなど）では効果がありません。アプリのAndroidManifest.xmlの<application>または<activity>内に<property android:name="android.window.PROPERTY_COMPAT_ALLOW_RESTRICTED_RESIZABILITY" android:value="true" />を追加することで、この動作をオプトアウトできます。ただし、このオプトアウトは一時的なものであり、Android 17では機能しなくなることに注意してください。Androidは大画面での特定の向きの設定を推奨していません。通常のAndroidスマートフォンはこの変更の影響を受けません。詳細については、https://developer.android.com/about/versions/16/behavior-changes-16#adaptive-layouts のAndroidドキュメントを確認してください。

Splash Screen​

  • coreSplashScreenVersion変数が1.2.0に更新されました。

Status Bar​

.capacitorViewDidAppearと.capacitorViewWillTransitionイベントを発行していたCAPNotifications.swiftとCAPBridgeViewController.swiftが削除されました。 これらは@capacitor/iosからリッスンできます。

Contents

このページを編集