To use SPM package traits in Capacitor 8, set experimental.ios.spm.swiftToolsVersion to "6.1" 그리고 experimental.ios.spm.packageTraits Capgo 설정에서 Capacitor을 찾고, 다음에 Capacitor을 실행합니다. bunx cap sync ios . CLI은 그 트레이드를 생성된 CLI에 기록합니다. CapApp-SPM/Package.swift, 그리고 SwiftPM은 매칭되는 선택적 의존성과 code 경로를 사용하여 플러그인을 빌드합니다. 이 기능은 iOS 프로젝트에서만 Swift Package Manager를 사용할 때만 작동하며, Capacitor CLI 8.3.0 이상이 필요합니다.
플러그인 개발자와 앱 개발자, 그리고 현재 실험적인 지원의 한계를 다룹니다.
트레이트는 무엇입니까?
트레이트는 Swift Evolution 제안인 SE-0450에서 왔습니다. SE-0450 패키지는 자신의 __CAPGO_KEEP_0__에 이름이 지정된 트레이드를 선언합니다. Package.swift 소비자는 패키지를 의존할 때 어떤 트레이드를 활성화할지 선택합니다.
- 트레이트는 다음과 같은 기능을 제공할 수 있습니다:
condition: .when(traits: [...])의존성을 선택적으로 사용할 수 있습니다 (on a target dependency) - code 경로를 활성화합니다. 활성화된 모든 트레이드는 컴파일러 조건으로 사용할 수 있습니다 (
#if TraitName), - Capacitor에서 SPM 패키지 특성
- 설정이나 링커 플래그와 같은 빌드 설정을 토글할 수 있습니다.
패키지 또한 특성을 기본으로 설정할 수 있습니다. 그들은 사용자가 명시적인 목록을 전달하지 않는 한 기본적으로 활성화됩니다.
CocoaPods subspecs 또는 Rust의 Cargo feature와 같은 아이디어입니다.
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:
- encrypted vs plain SQLite (SQLCipher)
- 앱에서 특성을 활성화하세요.
- optional vendor SDK for one payment or login provider
- __CAPGO_KEEP_2__
__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에 있다면 SPM으로 Capacitor 앱을 마이그레이션하는 방법을 참조하세요.
2. 플러그인 트레이트 이름을 찾으세요
플러그인 __CAPGO_KEEP_0__을 열고 Package.swift in node_modules 3. __CAPGO_KEEP_0__을 구성하세요 traits: 플러그인 __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;Capacitor 플러그인의 키는 패키지 이름을 npm으로, 값은 활성화할 특성을 목록으로 합니다.
exists. If you’re on CocoaPods, see how to migrate your __CAPGO_KEEP_0__ app to SPM
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"])Capacitor는 CLI를 작성합니다. .defaults (또는 defaults, .default, default HTML 텍스트 조각의 경우 (부모 키 `compare_step_build_text`). 페이지/영역: Capgo 마케팅 웹사이트. 역할: 긴 마케팅 또는 법률 문단. 페이지 대체/expo.astro, 페이지 대체/voltbuilder.astro. 메시지 키 `compare_step_build_text` (Compare Step Build Text). .defaults SwiftPM
값으로, 그리고 다른 모든 이름은 따옴표로 묶인 문자열로. Xcode에서 빌드합니다. Xcode가 여전히 이전 그래프를 표시한다면, .
Capacitor는 CLI을 규정한다.
Capacitor CLI은 동기화 중에 설정을 검증합니다.
- The __CAPGO_KEEP_0__ __CAPGO_KEEP_1__가 동기화 중에 구성이 유효한지 검증합니다:
swiftToolsVersion는 없으면, sync가 “Package traits는 명시적인 Swift tools 버전 6.1 이상이 필요합니다.”라는 메시지를 표시합니다. - If
swiftToolsVersion6.1보다 낮은 경우, sync가 중단되고 버전이 너무 낮다고 알려줍니다. swiftToolsVersionmust look like6.1or6.1.0.- 플러그인에 빈 배열이 있는 경우는 목록에 포함되지 않은 것과 같이 처리됩니다.
Appflow 비교/이동 마케팅 복사본. 역할: 장기 마케팅 또는 법적 문구. Seen in: page alternatives/ionic-appflow.astro. Capgo 제품/브랜드 및 개발자 용어를 정확하게 유지합니다.
리스트 트레이트로 대체합니다. 비교:
| Consulting 서비스 페이지. 역할: 섹션 서브 타이틀 또는 태그 라인. Seen in: page consulting.astro. Capgo 제품/브랜드 및 개발자 용어를 정확하게 유지합니다. | Result |
|---|---|
| not listed | 기본 속성을 유지하거나 삭제합니다. |
['SQLCipher'] |
only SQLCipher, 기본값 비활성화 |
['.defaults', 'SQLCipher'] |
기본값 활성화 SQLCipher |
플러그인 문서를 읽기 전에 기본값을 끄세요. 플러그인은 표준 백엔드를 기본 특성 뒤에 두어야 합니다.
자신의 플러그인에 특성을 추가하세요
관리하는 플러그인이 optional SDK를 가지고 있다면, 여기서 완전한 SDK를 찾을 수 있습니다. Package.swift. 패키지 이름은 Capacitor가 CLI에서 npm 이름으로부터 유도하는 이름과 일치해야 합니다.@acme/capacitor-db 이것이 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의 저장소로 이동하세요.
놓치기 쉬운 점:
- Tools 버전 6.x는 기본 언어 모드가 Swift 6으로 변경되었습니다. 대상에 대한 Swift 6을 지원하지 않기 때문에, Capacitor는 아직 공식적으로 지원하지 않습니다. 따라서 Capacitor가 strict concurrency를 지원할 때까지는
swiftLanguageModes: [.v5]unless your code is ready for strict concurrency. - __CAPGO_KEEP_0__는 이미 8개의 앱이 Xcode 26을 필요로 하므로, 이는 새로운 제약이 아닙니다. Capacitor에서 이 특성을 사용하세요.
Use the trait in code
기능이 꺼져 있는 경우 특성 이름을 명확하게 오류 메시지를 반환하세요. 앱 개발자는 플러그인에 대한 silent failure로 인해 오류를 찾지 못합니다.
#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
}만약 prefixed 이름을 선호한다면,
만약 prefixed 이름을 선호한다면, swiftSettings: [.define("ACME_SQLCIPHER", .when(traits: ["SQLCipher"]))] 특성을 디자인할 때는 더하기 연산을 사용하세요
디자인 특성은 추가적인 것일 수 있습니다.
SwiftPM은 의존성 그래프에서 특성을 통합합니다. 두 패키지가 플러그인을 사용하는 경우 서로 다른 특성을 사용하는 경우 union이 활성화됩니다. 그래서:
- 특성을 활성화하면 API 또는 기본값을 변경하지 않아야 합니다.
- 상호 배타적인 특성을 피하십시오. 만약 피할 수 없다면, 다음과 같이 빌드를 실패하십시오:
#if TraitA && TraitB
#error("TraitA and TraitB cannot be enabled together")
#endif모든 combination을 테스트하십시오
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'] 테스트 앱의 config를 변경하고, sync하고 빌드하십시오: packageTraits 각 combination을 CI에 추가하십시오. 각 combination은 별도의 작업으로 추가하십시오.
bunx cap sync ios
xcodebuild build \
-project ios/App/App.xcodeproj \
-scheme App \
-destination 'generic/platform=iOS Simulator' \
CODE_SIGNING_ALLOWED=NOCocoaPods 사용자를 지원하십시오
특성은 SPM에서만 존재합니다. 플러그인이 podspec도 배포하는 경우, subspec과 동일한 선택지를 제공하십시오:
Traits는 SPM에서만 존재합니다. 플러그인도 podspec을 포함한다면 subspec과 같은 선택지를 제공하십시오.
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_0__ #if SQLCipher code 경로입니다. CocoaPods 앱은 그 다음 Podfile에서 subspec을 선택합니다. Capacitor CLI은 하나의 __CAPGO_KEEP_3__를 작성합니다. pod __CAPGO_KEEP_0__ 플러그인당 라인 capacitor_pods, README에 추가 Podfile 라인에 대한 설명을 포함하십시오. Capacitor 8을 사용하는 방법: CocoaPods __CAPGO_KEEP_0__ 플러그인에 대한 제한 사항
실험적입니다.
- 설정은 그리고 미래의 주요 업데이트로 옮길 수 있습니다. 설정 이름이 변경될 수 있으므로 대비하십시오.
experimentalSwift 6은 공식적으로 지원되지 않습니다.ios.spm.*미래의 주요 버전에서. 설정 이름이 변경될 것으로 예상됩니다. - 설정은 CLI의 공식 문서는 설정을 변경할 때 주의를 주고 있습니다.
swiftToolsVersionSwift 6은 공식적으로 지원되지 않습니다. - iOS 전용. 안드로이드에는 Capacitor과 같은 대안이 없습니다. 플러그인은 Gradle 변수를 사용하여 옵션 Android SDK를 처리합니다.
variables.gradle또는 별도의 아티팩트. - 플러그인은 옵트인해야 합니다. 대부분의 플러그인은 아직 특성을 정의하지 않았습니다. 사용하기 전에 확인하세요.
문제 해결
Sync 오류: '패키지 특성은 명시적인 Swift 도구 버전 6.1 이상이 필요합니다.' Add swiftToolsVersion: '6.1' 추가 packageTraits.
SwiftPM은 알려지지 않은 특성을 보고합니다. 다음에 Package.swift SwiftPM이 알려지지 않은 특성을 보고합니다.
기능이 아직도 활성화된 트레이트 후에도 누락되어 있습니다. Xcode에서 패키지 캐시를 리셋하고 빌드 폴더를 정리한 후 생성된 CapApp-SPM/Package.swift 에 traits: suffix. 그 파일을 수동으로 편집해도 유지되지 않습니다. 왜냐하면 CLI은 매 싱크마다 다시 작성하기 때문입니다.
Swift 에서 code 에러가 발생한 후 도구 버전을 높였습니다. 이유는 swiftLanguageModes: [.v5].
에서 CLI 8.4 experimental.ios.spm.packageOptions 이러한 오류가 발생합니다. symlink or moduleAliases 플러그인 간의 이름 충돌입니다. Capacitor iOS 문제 해결 가이드.
더 큰 SPM 그림을 보려면 SPM vs CocoaPods for Capacitor. 현재 Xcode를 사용하는 SPM 프로젝트의 클라우드 빌드가 이미 실행되려면 Capgo 빌드.
