如何在 Capacitor 插件中添加依赖项

向以下内容添加依赖项： Capacitor 为插件添加依赖项可能会让人感到无从下手，但如果将其分解为清晰的步骤，就会变得简单许多。以下是您需要了解的内容：

1. 了解工具:

   • JavaScript：使用 npm 来管理依赖项。
   • iOS：使用 CocoaPods 或 Swift Package Manager (SPM)。
   • Android：使用 Gradle 进行依赖管理。

2. 配置开发环境:

   • 安装如下工具 Node.js, npm, Xcode, Android Studio、CocoaPods 和 JDK。

3. 开始您的 Capacitor 插件项目:

   • 使用 npm init @capacitor/plugin 以创建新插件。

4. 添加 JavaScript 依赖项:

   • 使用 npm install 用于生产和开发依赖。
   • 更新 package.json 以包含 peer dependencies，例如 @capacitor/core.

5. 处理平台特定依赖:

   • iOS: 使用 CocoaPods 或 SPM 配置如下库，例如 Alamofire 或 SwiftyJSON.
   • Android: 使用 Gradle 添加 Gson 或 AppCompat 等依赖。

6. 优化性能:

   • 锁定版本、审计依赖并解决冲突以确保稳定性。

7. 使用如下工具 Capgo 用于 Live Update:

   • 无需经过 App Store 审核，即可即时推送更新。

工具快速对比:

为什么这很重要: 高效管理依赖能确保插件在各平台无缝运行，节省时间并避免出错。下面我们深入了解具体步骤。

如何创建 Capacitor iOS/Android 插件

搭建开发环境

准备好必要的工具，以便高效处理 Capacitor 插件 依赖项。

必备开发工具

你需要以下工具：

创建新插件

使用 Capacitor CLI 来启动你的插件项目。这包括配置平台，以及使用反向域名格式为插件命名（例如： com.mycompany.plugin):

1. 运行以下命令：
   npm init @capacitor/plugin
2. 选择目标平台（iOS/Android）。
3. 用反向域名格式为插件命名。

项目配置步骤

1. 更新 package.json

   修改你的 package.json 以包含以下内容：

   {
     "capacitor": {
       "ios": {
         "src": "ios"
       },
       "android": {
         "src": "android"
       }
     },
     "peerDependencies": {
       "@capacitor/core": "^5.0.0"
     }
   }

2. 特定平台配置

   • 对于 iOS，确保你的 Podfile 包含：

     platform :ios, '13.0'
     use_frameworks!

   • 对于 Android，验证你的 build.gradle 包含：

     android {
         compileSdkVersion 33
         defaultConfig {
             minSdkVersion 22
         }
     }

3. 设置环境变量

   请为你的开发工具配置以下环境变量：

   变量	用途	示例值
   ANDROID_HOME	Android SDK 路径	/Users/username/Library/Android/sdk
   JAVA_HOME	JDK 安装路径	/Library/Java/JavaVirtualMachines/jdk-11.0.12.jdk/Contents/Home
   XCODE_SELECT	Xcode 命令行工具	/Applications/Xcode.app/Contents/Developer

项目配置完成后，你就可以开始管理 JavaScript 依赖项了。

JavaScript 依赖项

高效管理 JavaScript 依赖项是保持插件性能稳定的关键。

npm 安装依赖包

使用以下命令安装依赖项：

# Add a production dependency
npm install lodash --save

# Add a development dependency
npm install @types/lodash --save-dev

请务必手动将 peer dependencies 加入你的 package.json 文件中。测试所有依赖项，以确保在 Web 和 Native 平台上的兼容性。

管理 package.json

示例如下 package.json 配置：

{
  "name": "my-capacitor-plugin",
  "version": "1.0.0",
  "dependencies": {
    "lodash": "^4.17.21"
  },
  "devDependencies": {
    "@types/lodash": "^4.14.195",
    "@capacitor/core": "^5.0.0"
  },
  "peerDependencies": {
    "@capacitor/core": "^5.0.0"
  }
}

为了保持一致性，请合理锁定依赖版本：

使用 JavaScript 库

导入库时，请重点关注如何减小 bundle 体积：

// Import only the required function
import { isEqual } from 'lodash';

export class MyPlugin {
  async compare(options: { value1: any, value2: any }): Promise<boolean> {
    return isEqual(options.value1, options.value2);
  }
}

此外，请确保做好错误处理和类型检查：

import { Plugin } from '@capacitor/core';
import { validate } from 'your-validation-library';

@Plugin({
  name: 'MyPlugin',
  platforms: ['web', 'ios', 'android']
})
export class MyPlugin {
  async validateData(data: unknown): Promise<void> {
    try {
      if (!validate(data)) {
        throw new Error('Invalid data format');
      }
      // Continue processing if valid
    } catch (error) {
      throw new Error(`Validation failed: ${error.message}`);
    }
  }
}

接下来，我们将探讨如何处理 iOS 的平台特定依赖。

iOS 依赖项

本节将介绍如何在 Capacitor 插件中管理原生 iOS 依赖。配置好 JavaScript 依赖后，下一步就是处理原生 iOS 依赖。

CocoaPods 设置

首先，在您的 iOS 目录下初始化 CocoaPods：

cd ios
pod init

然后，更新您的 Plugin.podspec 包含以下配置的文件：

Pod::Spec.new do |s|
  s.name = 'MyCapacitorPlugin'
  s.version = '1.0.0'
  s.summary = 'Your plugin description'
  s.platform = :ios, '13.0'
  s.dependency 'Capacitor'
  # Include your iOS dependencies here
  s.dependency 'Alamofire', '~> 5.6.4'
end

Podfile 配置

初始化 CocoaPods 后，配置 Podfile 以包含 Capacitor 及任何其他第三方库：

platform :ios, '13.0'
use_frameworks!

def capacitor_pods
  pod 'Capacitor', :path => '../../node_modules/@capacitor/ios'
  pod 'CapacitorCordova', :path => '../../node_modules/@capacitor/ios'
end

target 'Plugin' do
  capacitor_pods
  # Add third-party dependencies
  pod 'KeychainAccess', '~> 4.2.2'
  pod 'SwiftyJSON', '~> 5.0.1'
end

target 'PluginTests' do
  capacitor_pods
end

以下是一些常见的依赖配置模式：

Swift Package 依赖项

如果你不想使用 CocoaPods，Swift Package Manager (SPM) 是一个不错的选择。直接在 Xcode 中通过以下配置添加 SPM 依赖： Package.swift 文件：

// Package.swift
dependencies: [
    .package(url: "https://github.com/Alamofire/Alamofire.git", .upToNextMajor(from: "5.6.4")),
    .package(url: "https://github.com/SwiftyJSON/SwiftyJSON.git", from: "5.0.1")
]

要在你的 code 插件中使用 SPM 依赖，请根据需要进行导入和集成。例如：

import Capacitor
import Alamofire

@objc(MyPlugin)
public class MyPlugin: CAPPlugin {
    @objc func makeRequest(_ call: CAPPluginCall) {
        AF.request("https://api.example.com/data").response { response in
            // Process the response
            call.resolve([
                "data": response.data
            ])
        }
    }
}

这种方法允许你根据项目需求，在 CocoaPods 和 Swift Package Manager 之间进行选择。

Android 依赖项

配置 Android 依赖以确保原生集成的顺畅。以下是管理 Capacitor 插件依赖的方法。

Gradle Dependencies

将以下配置添加到你的 build.gradle 文件：

android {
    defaultConfig {
        minSdkVersion 22
        targetSdkVersion 33
    }
}

dependencies {
    implementation "androidx.appcompat:appcompat:1.6.1"
    implementation "com.google.code.gson:gson:2.10.1"
    implementation "org.jetbrains.kotlin:kotlin-stdlib:1.8.20"
    implementation project(':capacitor-android')
}

在以下内容中定义其他版本： buildscript 代码块：

buildscript {
    ext {
        androidxCoreVersion = '1.10.1'
        kotlinVersion = '1.8.20'
    }
}

配置好依赖项后，请务必设置必要的仓库。

仓库配置

在项目级的 build.gradle中，包含所需的 Maven 仓库：

allprojects {
    repositories {
        google()
        mavenCentral()
        maven { url "https://jitpack.io" }
    }
}

如果你使用的是自定义或私有 Maven 仓库，请按如下方式添加凭据：

maven {
    url "https://maven.example.com/releases"
    credentials {
        username = project.findProperty("mavenUsername") ?: System.getenv("MAVEN_USERNAME")
        password = project.findProperty("mavenPassword") ?: System.getenv("MAVEN_PASSWORD")
    }
}

仓库设置完成后，请处理可能出现的依赖冲突。

修复兼容性问题

要处理依赖冲突，请在你的 build.gradle:

configurations.all {
    resolutionStrategy {
        force "org.jetbrains.kotlin:kotlin-stdlib:1.8.20"
        force "androidx.core:core-ktx:1.10.1"
    }
}

中应用版本解析。以下是解决常见依赖问题的策略：

例如，你可以通过以下方式排除冲突模块：

dependencies {
    implementation('library:name:1.0.0') {
        exclude group: 'com.conflicting.dependency'
    }
}

Finally, optimize your build process by enabling caching and parallel execution in gradle.properties:

org.gradle.caching=true
org.gradle.parallel=true
org.gradle.jvmargs=-Xmx2048m

Capgo 集成

结合原生与 JavaScript 依赖管理，使用 Capgo 可以让您的插件更新变得更快、更简单。

关于 Capgo

Capgo 是一个专为 Capacitor 插件和应用设计的 live update 平台。目前已为 750 个生产环境应用提供了超过 2350 万次更新 [1]，Capgo 让开发者能够即时推送依赖项和 code 更新，无需经过 App Store 审核。所有更新均采用端到端加密，符合 Apple 和 Android 的合规标准。

Capgo 更新功能

Capgo 通过以下功能简化了插件依赖管理：

来源： [1]

Capgo 可与 GitHub Actions、GitLab CI 和 Jenkins 等 CI/CD 工具无缝集成，自动更新依赖并确保插件版本一致。这些工具能让您更轻松地将 Capgo 集成到工作流中。

配置 Capgo

按照以下步骤将 Capgo 集成到您的项目中：

1. 安装 Capgo CLI

   在终端中运行以下命令：

   npx @capgo/cli init

2. 配置更新偏好

   使用 Capgo dashboard 设置部署渠道和偏好。支持云端托管和自托管配置。

3. 添加更新逻辑

   将 code 添加到主插件文件以启用更新：

   import { Capgo } from '@capgo/capacitor-updater';
   
   // Initialize Capgo
   const capgo = new Capgo({
     appId: 'YOUR_APP_ID',
     channel: 'production'
   });
   
   // Check for updates
   await capgo.checkForUpdate();

“我们采用敏捷开发模式，@Capgo 对我们持续为用户交付功能至关重要！” —— Rodrigo Mantica

Capgo 还提供数据分析 dashboard，可实时洞察更新成功率和用户活跃度。一键回滚和错误追踪等功能有助于快速解决问题，让插件更新保持顺畅。

总结

流程回顾

管理 Capacitor 插件的依赖项时，需要确保原生组件（iOS 和 Android）与其 JavaScript 部分保持一致，以实现无缝集成。该过程包括针对特定平台的配置以及管理 JavaScript 包，从而获得最佳性能。遵循以下步骤将有助于保持插件功能的稳定与高效。

最佳实践

为了有效管理依赖项，请参考以下实践：

使用 live update 工具（如 Capgo）可以通过实现实时更新，进一步简化并优化这些实践。

Capgo 的优势

Capgo 在提供强劲性能的同时，简化了依赖管理流程。它实现了令人惊叹的 24 小时内 95% 的用户更新率 并保持 API 全球响应时间为 434ms [1]。通过端到端加密，它确保了符合 Apple 和 Android 指南的安全更新。对于管理多个插件版本的团队，Capgo 的 channel 系统支持针对特定用户群体的定向部署。

以下是 Capgo 的性能概览：

继续阅读：如何在 Capacitor Plugins 中添加依赖

如果你正在使用 如何在 Capacitor 插件中添加依赖项 要规划原生插件工作，请将其连接到 Capgo 插件目录 用于 Capgo 插件目录中的产品工作流， 由 Capgo 提供的 Capacitor 插件 有关 Capgo 编写的 Capacitor 插件实现细节， 添加或更新插件 关于“添加或更新插件”中的实现细节， Ionic Enterprise 插件替代方案 了解 Ionic Enterprise 插件替代方案的产品工作流，以及 Capgo Native Build 关于 Capgo Native Builds 中的产品工作流。