Capacitor 8 で SPM パッケージ特性を使用するには、設定 experimental.ios.spm.swiftToolsVersion と "6.1" とリストする experimental.ios.spm.packageTraits CapgoのCapacitor設定ファイルに記載されている設定を確認し、次に実行 bunx cap sync ios. Capgoは、生成されたCLIに特性を書き込む CapApp-SPM/Package.swift, and SwiftPM builds the plugin with the matching optional dependencies and code paths. This needs Capacitor CLI 8.3.0 or later and only applies to iOS projects that use Swift Package Manager.
プラグインの特性は、SPMとCocoaPodsの最後の大きな機能差を閉じるものです: これまでpodspec subspecとして使用されていたオプションのネイティブ依存関係。 このガイドでは、プラグインの作者側、コンシューマ側、現在の実験的なサポートの制限について説明します。
Capgoの特性とは何か
Capgoの特性はSwift Evolution提案SE-0450から来ています SE-0450特性を宣言します。 コンシューマは、パッケージに依存するときにどの特性を有効にするかを選択します。 特性は次のことができます: Package.swift依存関係をオプションにする('
- ターゲット依存関係に')
condition: .when(traits: [...])__CAPGO_KEEP_0__パスを有効にする、すべての有効な特性はコンパイル条件として利用できるため - codeパスは、Capgoのcode設定ファイルに記載されている設定を確認し、次に実行
#if TraitName), - ビルド設定の切り替え、定義やリンカフラグなど
- その他の特性を有効にします。
パッケージは特性をデフォルトとしてマークすることもできます。デフォルトでは有効ですが、ユーザーが明示的にリストを渡す場合にのみ無効になります。
もしCocoaPods subspecsやRustのCargo featuresを知っているのであれば、同じ考え方です。
Capacitorの重要性
Capacitor はアプリの Package.swift for you, so you can’t hand-edit dependency lines to pass traits. Before CLI 8.3, plugin authors with an optional native SDK had two bad choices on SPM: always link the SDK, increasing size and sometimes adding privacy or export compliance work, or publish a second plugin. Common cases:
- 広告識別子収集を含まない分析SDKsと含むSDKs
- 1つの支払いまたはログインプロバイダー用のオプションのベンダー
- 一時的なベンダー SDK 1 つの支払いまたはログインプロバイダーの場合。
- アプリの特性を有効にします
__CAPGO_KEEP_0__
1. バージョンを確認
bunx cap --version # 8.3.0 or later
xcodebuild -version # Xcode 26 (required by Capacitor 8 anyway)プロジェクトはSPMを使用している必要があります: ios/App/CapApp-SPM 存在します。CocoaPodsにいる場合は、 CapacitorアプリをSPMに移行する方法を参照してください.
2. プラグインの特性名を探す
プラグインの Package.swift in node_modules 配列を探してください、またはREADMEを確認してください。特性名はケース感受性です。 traits: 3. __CAPGO_KEEP_0__を設定
3. Configure Capacitor
import type { CapacitorConfig } from '@capacitor/cli';
const config: CapacitorConfig = {
appId: 'com.example.app',
appName: 'Example',
webDir: 'dist',
experimental: {
ios: {
spm: {
swiftToolsVersion: '6.1',
packageTraits: {
'@acme/capacitor-db': ['.defaults', 'SQLCipher'],
},
},
},
},
};
export default config;プラグインのnpmパッケージ名がキーです。値は有効にする特性のリストです。
4. 同期し、出力を確認
bunx cap sync ios生成された ios/App/CapApp-SPM/Package.swift は現在 // swift-tools-version: 6.1 そしてプラグインの依存関係の行には特性が含まれます:
.package(name: "AcmeCapacitorDb", path: "../../../node_modules/@acme/capacitor-db", traits: [.defaults, "SQLCipher"])はCLIが書き込む .defaults （または defaults, .default, default HTMLテキストのフラグメント（親キー `compare_step_build_text`）。ページ/エリア：Capgoのマーケティングウェブサイト。役割：長いマーケティングまたは法的文章。ページの代替品：expo.astro、page代替品：voltbuilder.astro。メッセージキー `compare_step_build_text` (Compare Step Build Text)。 .defaults ）SwiftPMの
値であり、他のすべての名前は引用符で囲まれた文字列です。 Xcodeでビルドする。Xcodeが古いグラフを表示している場合、.
Capacitor では CLI が規定しているルール
Capacitor CLI は同期中の設定を検証します。
- __CAPGO_KEEP_0____CAPGO_KEEP_1__はSync中の構成を検証します:
swiftToolsVersionは欠けているため、syncは “Package traits require an explicit Swift tools version of 6.1 or higher.” と表示され、syncが停止します。 - If
swiftToolsVersionは6.1未満の場合、syncが停止し、バージョンが低いことを通知します。 swiftToolsVersionは次の形式でなければなりません。6.1または6.1.0.- は空の配列の場合、プラグインのデフォルトの特性と同じ扱いになります。
デフォルトの特性を維持するか破棄する
特性のリストを表示することで、デフォルトの特性を上書きします。比較:
| 設定値 | 結果 |
|---|---|
| リストされていない | プラグインのデフォルトの特性 |
['SQLCipher'] |
ソロ SQLCipher, デフォルトがオフです。 |
['.defaults', 'SQLCipher'] |
defaults plus SQLCipher |
Capacitor プラグインのドキュメントを読んで、デフォルト値を削除する前に実行してください。プラグインはデフォルトの特性の背後にある標準のバックエンドを置くかもしれません。
プラグインに特性を追加する
もし、プラグインを管理し、任意のSDKを含む場合、ここでは完全な Package.swiftパッケージ名は、Capacitor CLI が得る npm 名から一致する必要があります。@acme/capacitor-db Capacitor AcmeCapacitorDb). ご覧の通り migrate a Capacitor plugin to SPM ルールのために。
// swift-tools-version: 6.1
import PackageDescription
let package = Package(
name: "AcmeCapacitorDb",
platforms: [.iOS(.v15)],
products: [
.library(name: "AcmeCapacitorDb", targets: ["DbPlugin"])
],
traits: [
.trait(name: "SQLCipher", description: "Link SQLCipher and enable encrypted databases."),
.default(enabledTraits: [])
],
dependencies: [
.package(url: "https://github.com/ionic-team/capacitor-swift-pm.git", from: "8.0.0"),
.package(url: "https://github.com/sqlcipher/SQLCipher.swift.git", from: "4.10.0")
],
targets: [
.target(
name: "DbPlugin",
dependencies: [
.product(name: "Capacitor", package: "capacitor-swift-pm"),
.product(name: "Cordova", package: "capacitor-swift-pm"),
.product(
name: "SQLCipher",
package: "SQLCipher.swift",
condition: .when(traits: ["SQLCipher"])
)
],
path: "ios/Sources/DbPlugin"
)
],
swiftLanguageModes: [.v5]
)CapacitorのパッケージのURL、製品名、バージョンは、SDKのリポジトリで確認してください。
目立たないポイント:
- ツールズバージョン 6.x は、デフォルトの言語モードを Swift 6 に変更します。 ターゲット用のためです。Capacitor はまだ Swift 6 を公式にサポートしていないので、Capacitor がストリクトコンカレNCY用に準備されていない限り、使用しないでください。
swiftLanguageModes: [.v5]Capacitorの場合、厳密な並行性に対応するには、code が準備されている必要があります。 - __CAPGO_KEEP_0__ はすでに 8 つのアプリが Xcode 26 を必要としているので、それは新しい制約ではありません。 Capacitor の特性を使用してください。
Use the trait in code
明確なエラーを返すようにしてください。アプリ開発者は、プラグインの静的なエラーを認識できず、プラグインを非難します。
#if SQLCipher
import SQLCipher
#endif
@objc func open(_ call: CAPPluginCall) {
let key = call.getString("encryptionKey")
#if SQLCipher
// open with key
#else
if key != nil {
call.unavailable("Encryption requires the SQLCipher trait. Enable it in experimental.ios.spm.packageTraits.")
return
}
#endif
// open without encryption
}もし、プレフィックス付きの名前を好むなら、独自のフラグを定義することもできます。
特性を設計する際は、追加的なものにしましょう swiftSettings: [.define("ACME_SQLCIPHER", .when(traits: ["SQLCipher"]))] __CAPGO_KEEP_0__ は __CAPGO_KEEP_0__ の特性を使用してください。
__CAPGO_KEEP_0__ の特性は、パッケージのターゲットのコンパイル条件です。
SwiftPMは依存グラフ全体で特性を統合します。2つのパッケージがあなたのプラグインに異なる特性で依存している場合、Unionが有効になります。つまり:
- 特性を有効にすることは機能を追加することであり、APIを削除したりデフォルト値を変更したりすることではありません。
- 相互に排他的な特性を避けるようにしてください。できなければ、ビルドを大きな声で失敗させてください:
#if TraitA && TraitB
#error("TraitA and TraitB cannot be enabled together")
#endifすべての組み合わせをテストする
swift build on its own builds for the Mac, and a plugin that depends on Capacitor only builds for iOS, so test the traits through a Capacitor test app built for an iOS Simulator. For each combination (no entry for the default traits, ['SQLCipher'], ['.defaults', 'SQLCipher'] 各組み合わせをCIに追加して、それぞれのジョブとしてビルドしてください。 packageTraits CocoaPodsユーザーをカバーする
bunx cap sync ios
xcodebuild build \
-project ios/App/App.xcodeproj \
-scheme App \
-destination 'generic/platform=iOS Simulator' \
CODE_SIGNING_ALLOWED=NO特性はSPMのみに存在します。プラグインもPodspecを配布している場合、Subspecと同じ選択肢を提供してください:
Subspecに同じコンパイル条件名を設定すると、__CAPGO_KEEP_0__パスを共有できます。CocoaPodsアプリはPodfileでSubspecを選択します。__CAPGO_KEEP_1__ __CAPGO_KEEP_2__は1つの
__CAPGO_KEEP_0__
s.default_subspec = 'Core'
s.subspec 'Core' do |core|
core.source_files = 'ios/Sources/DbPlugin/**/*.swift'
core.dependency 'Capacitor'
end
s.subspec 'SQLCipher' do |sc|
sc.dependency 'AcmeCapacitorDb/Core'
sc.dependency 'SQLCipher', '~> 4.10'
sc.pod_target_xcconfig = { 'SWIFT_ACTIVE_COMPILATION_CONDITIONS' => '$(inherited) SQLCipher' }
end__CAPGO_KEEP_1__ #if SQLCipher code path. CocoaPods apps then select the subspec in their Podfile. The Capacitor CLI は、1 つのファイルに書き込む。 pod プラグインごとに 1 行 capacitor_pods, したがって README に追加される Podfile の追加行をドキュメント化してください。 Capacitor を使用する方法: Capacitor 8 カスタム Pod の行の場所を示しています。
制限事項
- 実験的です。 オプションは
experimentalそして将来のメジャー バージョンではios.spm.*ここに移動する可能性があります。将来のバージョンで構成名の変更が行われることを予想してください。 - Swift 6 は公式にサポートされていません。 CLIの公式ドキュメントは、設定を変更するとエラーが発生する可能性があることを警告しています。
swiftToolsVersionplugins - iOS 限定です。 Android には Capacitor の等価物はありません。プラグインは、Gradle 変数を使用してオプションの Android SDK を管理します。
variables.gradleまたは、別のアーティファクト。 - プラグインはオプトインする必要があります。 ほとんどのプラグインは、特性を定義していません。使用する前に確認してください。
トラブルシューティング
Sync fails with “Swift tools version 6.1 or higher is required for package traits.” Add swiftToolsVersion: '6.1' 追加 packageTraits.
SwiftPMは未知の特性を報告しています。 次に Package.swift SwiftPM は、未知の特性を報告します。
機能がまだ未実装のままです。 Xcodeのパッケージキャッシュをリセットし、ビルドフォルダをクリーンし、生成された CapApp-SPM/Package.swift のサフィックスを持つ。 traits: ファイルを手動で編集しても反映されないのは、CLIが毎回Sync時にファイルを上書きするためです。
Swift codeでツールズバージョンを上げた後に出たエラー。 Swift 6の言語モードは、制御できるパッケージ内で実行できます。追加 swiftLanguageModes: [.v5].
プラグイン間で名前が衝突する。 CLI 8.4以降 experimental.ios.spm.packageOptions を設定できます。 symlink または moduleAliases context Capacitor iOS troubleshoot guide.
より大きなSPMのシナリオについては、 SPM vs CocoaPods for Capacitor. また、既にXcodeの最新版でSPMプロジェクトを実行するクラウドビルドについては、 Capgo ビルド.
