Capacitor 插件贡献指南

Capacitor 插件将 Web 技术与原生设备功能连接起来，从而实现跨平台 App 开发。本指南将帮助您：

搭建开发环境：诸如 Node.js, Xcode，以及 Android Studio 是必不可少的。
遵循 Code 标准：使用 TypeScript, Swift，以及 Kotlin 并保持一致的命名规范和错误处理。
充分测试: 为 JavaScript、iOS 和 Android 编写单元测试以确保可靠性。
清晰的文档说明: 使用 JSDoc 和 README 文件以降低使用门槛。
提交 Pull Request: 在贡献之前，请确保拥有高质量的 code、测试和文档。

开源指南详解 - 如何进行贡献

搭建开发环境

搭建完善的开发环境是高效插件开发的关键。准备充分的环境能让你的插件在编码、测试和部署过程中更加顺畅。

所需工具与技能

在开始之前，请确保已安装以下工具：

类别	环境要求
核心工具	Node.js (LTS), npm 6+, Git
IDE/编辑器	Visual Studio Code 或你偏好的编辑器
iOS 开发	Xcode, SwiftLint, CocoaPods
Android 开发	Android Studio, Android SDK, JDK

你还需要熟悉用于 Web 开发的 TypeScript，以及用于原生开发任务的 Swift (iOS) 或 Java/Kotlin (Android) [1][2].

配置 Monorepo

该 Capacitor 插件生态系统依赖于 monorepo 结构。这种方式能确保你的工作从一开始就符合社区标准。

Fork 并 Clone 仓库
首先在 GitHub 上 fork Capacitor plugins 仓库。然后，clone 你 fork 的仓库：
```
git clone https://github.com/your-username/capacitor-plugins.git
cd capacitor-plugins
npm install
```
安装依赖并 Build
运行以下命令来安装所有必需的依赖并 build 插件：
```
npm run build
```
设置版本控制
使用 feature branches 进行开发，并保持你的 fork 与 upstream 仓库同步。

准备 Native 平台

进行跨平台开发时，你需要配置 iOS 和 Android 环境。

针对 iOS：

从 Mac App Store 下载 Xcode。
使用以下命令安装命令行工具：
```
xcode-select --install
```
使用以下命令安装 CocoaPods：
```
sudo gem install cocoapods
```
设置 Apple Developer 账号及必要的证书。
可选择使用 SwiftLint 来维护 code 代码质量。

针对 Android：

安装 Android Studio、最新的 SDK 以及虚拟设备。
确保已安装 JDK。
在 Android Studio 中正确配置 Android SDK。

完成这些平台的配置后，你就可以遵循既定的编码规范，开始进行插件开发了。

Code 标准指南

开发环境搭建完成后，请遵循以下指南来构建易于维护和使用的插件。

遵循代码风格指南

该 Capacitor 插件生态系统使用以下工具强制执行严格的编码标准： ESLint, Prettier以及 SwiftLint。以下是要求的格式概览：

组件	格式
变量	`deviceInfo` (camelCase)
类	`BatteryManager` (PascalCase)
方法	`getLanguageCode()` (camelCase)
常量	`MAX_RETRY_COUNT` (SNAKE_CASE)

插件应使用 TypeScript，以获得更好的类型安全性和 ES6+ 特性，例如 async/await。此外，请遵循 Swift (iOS) 和 Kotlin (Android) 的平台特定编码规范。

错误与类型管理

统一的错误处理对跨平台兼容性至关重要。示例如下：

async checkPermissions(): Promise<PermissionStatus> {
  try {
    const result = await this.implementation.checkPermissions();
    return result;
  } catch (error) {
    throw new Error(`Permission check failed: ${error.message}`);
  }
}

为了保证类型安全：

针对特定用例，使用精简且专注的 Interface。
针对不同平台差异，使用 Union Types。

Code 文档

优秀的文档是让插件易于上手和使用的关键。请遵循以下实践：

API 文档：编写可配合以下工具使用的 JSDoc 注释 @capacitor/docgen结束。例如：

/**
 * @description Get the device's current battery level
 * @returns Promise with the battery level percentage
 */
async getBatteryLevel(): Promise<{ level: number }>;

README 结构：包含安装步骤、配置说明、平台特定要求、使用示例以及详细的 API 参考信息等核心内容。

编写良好的文档能确保插件易于采用，并为更广泛的 Capacitor 社区做出贡献。

sbb-itb-f9944d2

Plugin 测试指南

测试 Capacitor 插件时，需要重点关注几个关键领域，以确保功能的顺畅与可靠。

Native Bridge 测试

Native bridge 测试旨在确保 JavaScript 与原生 code 之间的通信正常。首先，请使用针对各平台定制的框架来搭建测试环境。

以下是一个 Jest JavaScript 端的单元测试示例：

// Example of a Jest unit test for the JavaScript bridge
describe('DeviceInfo Plugin', () => {
  test('getBatteryLevel returns valid percentage', async () => {
    const result = await DeviceInfo.getBatteryLevel();
    expect(result.level).toBeGreaterThanOrEqual(0);
    expect(result.level).toBeLessThanOrEqual(100);
  });
});

若要进行原生端测试，iOS 请使用 XCTest，Android 请使用 JUnit。以下是 Android 的示例：

@Test
fun testBatteryLevel() {
    val plugin = DeviceInfo()
    val result = plugin.getBatteryLevel()
    assertTrue(result.level in 0..100)
}

在确认核心 bridge 功能符合预期后，即可开始测试完整的用户工作流。

完整的插件测试

为确保插件在不同场景下表现良好，请测试以下各类场景：

测试类别	重点关注领域
集成测试	跨平台功能
性能测试	资源占用与响应时间
安全性测试	数据处理与权限检查

对于功能复杂的插件，请模拟真实用户场景。例如，在测试 DeviceInfo 插件时，需检查：

不同网络环境下的上传成功率
进度报告的准确性
大文件传输期间的内存占用

OTA Testing with Capgo

Capgo Live Update Dashboard 界面

Capgo 的开源工具让快速部署和测试更新变得轻而易举。以下是使用方法：

设置更新通道例如 dev、staging 和 production 环境。
使用 CI/CD 工具实现自动化部署。
即时推送更新。
通过以下方式监控性能与问题 Capgo dashboard.

对于分阶段发布，Capgo 允许你将更新限制在小部分用户中。例如，你可以每 24 小时向 25% 的用户推送一个新版本：

// Example configuration for staged rollout
{
  "plugin": "camera-plugin",
  "version": "1.2.0",
  "rollout": {
    "percentage": 25,
    "interval": "24h"
  }
}

这种分阶段发布的方法可以在全面发布前利用社区反馈，从而及早发现问题。

Pull Request 流程

在对更改进行充分测试后，请按照以下步骤提交您的 pull request：

PR 提交检查清单

提交之前，请确保您已涵盖以下关键领域：

类别	检查项
Code 质量	- 确保 Swift/Kotlin 实现与 Web 端 API 一致。
测试	- 为任何新功能添加单元测试。 - 确认 CI/CD pipeline 检查已成功通过。
文档	- 根据需要更新 README、内联文档和 CHANGELOG。

社区准则

协作时，请遵循以下最佳实践：

快速响应审核人员的反馈。
确保讨论集中在技术细节上。
使用 GitHub 的建议功能来提交 code 变更。
提交小而聚焦的 pull request，每次只解决一个功能或问题。

对于较大的变更，建议先创建一个 issue 并讨论你的方案。Capacitor 团队依赖 GitHub Actions 进行自动化检查，所有检查必须通过，你的 pull request 才能进入审核。

Capgo 集成指南

如果你的插件涉及 Live Updates，请在提交前确保它能与 Capgo 无缝协作：

版本控制
为你的插件使用清晰的语义化版本号，并在 changelog 中记录所有变更。Capgo 的系统可以帮助追踪用户设备上的版本采用情况。
CI/CD 集成
将 Capgo 集成到您的 CI/CD pipeline 中，实现更新部署自动化。
更新监控
监控部署成功率，并确保符合 App Store 指南。

总结

若想通过插件做出有意义的贡献，遵循既定流程并符合社区标准至关重要。这包括遵守 Capacitor 的代码规范并对工作进行彻底测试。

PR checklist 强调了高质量提交的重要性。如果您的插件支持 Live Update，集成 Capgo（如前所述）可以帮助您快速发布更新，无需等待 App Store 审核。

PR 合并后，请通过跟踪 Issue 和发布版本更新保持活跃。与社区定期互动、持续维护以及紧跟 Capacitor 的更新将确保您的插件保持实用性和相关性。

关注用户反馈并根据需要进行更新。这种持续的投入有助于维护生态系统的整体质量，并让您的插件对开发者保持价值。

继续阅读 Capacitor 插件贡献指南

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