如何在 Capacitor 插件中添加依赖

为插件添加依赖 Capacitor 可能会让人感到无从下手，但如果拆解成清晰的步骤就会简单很多。以下是你需要了解的内容：

1. 了解工具:

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

2. 配置开发环境:

   • 安装如下工具 Node.js, npm, Xcode 的 Mac, 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 用于实时更新:

   • 无需经过 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

请务必在你的 package.json 文件中手动包含 peer dependencies。测试所有依赖项，确认在 Web 和原生平台上都能兼容。

管理 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 依赖项

将以下配置添加到你的项目中： 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'
    }
}

最后，通过在 中启用缓存和并行执行来优化你的 build 流程 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 更新，无需经过应用商店审核。所有更新均采用端到端加密，符合 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 的通道系统允许针对特定用户组进行定向部署。

以下是 Capgo 性能的快速概览：

继续阅读《如何在 Capacitor 插件中添加依赖》

如果你正在使用 如何在 Capacitor 插件中添加依赖 要规划原生插件工作，请将其与 Capgo 插件目录 查看 Capgo 插件目录中的产品工作流， Capgo 提供的 Capacitor 插件 查看由 Capgo 提供的 Capacitor 插件中的实现细节， 添加或更新插件 查看添加或更新插件中的实现细节， Ionic Enterprise 插件替代方案 查看 Ionic Enterprise 插件替代方案中的产品工作流，以及 Capgo Native Build 查看 Capgo Native Builds 中的产品工作流。