Capacitor 最佳实践指南：项目结构、插件使用与性能优化

capacitor-best-practices by cap-go/capacitor-skills

396 周安装量

22 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-best-practices

开发 JavaScript 框架性能优化

🇨🇳中文介绍

Capacitor 最佳实践

构建生产就绪的 Capacitor 应用程序的全面指南。

何时使用此技能

设置新的 Capacitor 项目
审查 Capacitor 应用架构
优化应用性能
实施安全措施
准备应用商店提交

项目结构

配置最佳实践

capacitor.config.ts (正确)：

import type { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'com.company.app',
  appName: 'My App',
  webDir: 'dist',
  server: {
    // 仅用于开发环境
    ...(process.env.NODE_ENV === 'development' && {
      url: 'http://localhost:5173',
      cleartext: true,
    }),
  },
  plugins: {
    SplashScreen: {
      launchAutoHide: false,
    },
  },
};

export default config;

capacitor.config.json (避免)：

{
  "server": {
    "url": "http://localhost:5173",
    "cleartext": true
  }
}

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

关键：始终使用最新版 Capacitor

保持 Capacitor 核心包同步：

bun add @capacitor/core@latest @capacitor/cli@latest
bun add @capacitor/ios@latest @capacitor/android@latest
bunx cap sync

# 1. 安装包
bun add @capgo/capacitor-native-biometric

# 2. 同步原生项目
bunx cap sync

# 3. 对于 iOS：安装 pods（或使用 SPM）
cd ios/App && pod install && cd ../..

# 缺少同步步骤
bun add @capgo/capacitor-native-biometric
# 应用崩溃，因为原生代码未链接

正确 - 使用前检查可用性：

import { NativeBiometric, BiometryType } from '@capgo/capacitor-native-biometric';

async function authenticate() {
  const { isAvailable, biometryType } = await NativeBiometric.isAvailable();

  if (!isAvailable) {
    // 回退到密码验证
    return authenticateWithPassword();
  }

  try {
    await NativeBiometric.verifyIdentity({
      reason: '验证身份以访问您的账户',
      title: '生物识别登录',
    });
    return true;
  } catch (error) {
    // 用户取消或生物识别失败
    return false;
  }
}

错误 - 无可用性检查：

// 如果生物识别不可用，将导致崩溃
await NativeBiometric.verifyIdentity({ reason: '登录' });

关键：延迟加载插件

正确 - 动态导入：

// 仅在需要时加载
async function scanDocument() {
  const { DocumentScanner } = await import('@capgo/capacitor-document-scanner');
  return DocumentScanner.scanDocument();
}

错误 - 启动时导入所有内容：

// 增加初始包大小
import { DocumentScanner } from '@capgo/capacitor-document-scanner';
import { NativeBiometric } from '@capgo/capacitor-native-biometric';
import { Camera } from '@capacitor/camera';
// ... 还有 20 多个插件

高优先级：优化 WebView 性能

正确 - 使用硬件加速：

<!-- android/app/src/main/AndroidManifest.xml -->
<application
    android:hardwareAccelerated="true"
    android:largeHeap="true">

<!-- ios/App/App/Info.plist -->
<key>UIViewGroupOpacity</key>
<false/>

高优先级：最小化桥接调用

正确 - 批量操作：

// 单次调用，批量数据
await Storage.set({
  key: 'userData',
  value: JSON.stringify({ name, email, preferences }),
});

错误 - 多次桥接调用：

// 每次调用都会跨越 JS-原生桥接
await Storage.set({ key: 'name', value: name });
await Storage.set({ key: 'email', value: email });
await Storage.set({ key: 'preferences', value: JSON.stringify(preferences) });

中优先级：图像优化

import { Camera, CameraResultType } from '@capacitor/camera';

const photo = await Camera.getPhoto({
  quality: 80,           // 不是 100
  width: 1024,           // 合理的最大值
  resultType: CameraResultType.Uri,  // 对于大图像，不使用 Base64
  correctOrientation: true,
});

const photo = await Camera.getPhoto({
  quality: 100,
  resultType: CameraResultType.Base64,  // 内存密集型
  // 无大小限制
});

关键：安全存储

正确 - 对敏感数据使用安全存储：

import { NativeBiometric } from '@capgo/capacitor-native-biometric';

// 安全存储凭据
await NativeBiometric.setCredentials({
  username: 'user@example.com',
  password: 'secret',
  server: 'api.myapp.com',
});

// 通过生物识别验证检索
const credentials = await NativeBiometric.getCredentials({
  server: 'api.myapp.com',
});

错误 - 明文存储：

import { Preferences } from '@capacitor/preferences';

// 切勿将敏感数据存储在明文偏好设置中
await Preferences.set({
  key: 'password',
  value: 'secret',  // 以明文存储！
});

关键：证书锁定

对于处理敏感数据的生产应用：

// capacitor.config.ts
const config: CapacitorConfig = {
  plugins: {
    CapacitorHttp: {
      enabled: true,
    },
  },
  server: {
    // 在生产环境中禁用明文传输
    cleartext: false,
  },
};

高优先级：Root/越狱检测

import { IsRoot } from '@capgo/capacitor-is-root';

async function checkDeviceSecurity() {
  const { isRooted } = await IsRoot.isRooted();

  if (isRooted) {
    // 显示警告或限制功能
    showSecurityWarning('设备似乎已 Root/越狱');
  }
}

高优先级：应用跟踪透明度 (iOS)

import { AppTrackingTransparency } from '@capgo/capacitor-app-tracking-transparency';

async function requestTracking() {
  const { status } = await AppTrackingTransparency.requestPermission();

  if (status === 'authorized') {
    // 启用分析
  }
}

关键：始终处理插件错误

import { Camera, CameraResultType } from '@capacitor/camera';

async function takePhoto() {
  try {
    const image = await Camera.getPhoto({
      quality: 90,
      resultType: CameraResultType.Uri,
    });
    return image;
  } catch (error) {
    if (error.message === 'User cancelled photos app') {
      // 用户取消，不是错误
      return null;
    }
    if (error.message.includes('permission')) {
      // 权限被拒绝
      showPermissionDialog();
      return null;
    }
    // 意外错误
    console.error('相机错误：', error);
    throw error;
  }
}

// 无错误处理
const image = await Camera.getPhoto({ quality: 90 });

使用 Capacitor Updater

import { CapacitorUpdater } from '@capgo/capacitor-updater';

// 通知应用已准备就绪
CapacitorUpdater.notifyAppReady();

// 监听更新
CapacitorUpdater.addListener('updateAvailable', async (update) => {
  // 在后台下载
  const bundle = await CapacitorUpdater.download({
    url: update.url,
    version: update.version,
  });

  // 在下次应用启动时应用
  await CapacitorUpdater.set(bundle);
});

正确 - 后台下载，重启时应用：

// 静默下载
const bundle = await CapacitorUpdater.download({ url, version });

// 用户继续使用应用...

// 当他们关闭/重新打开时应用
await CapacitorUpdater.set(bundle);

错误 - 打断用户：

// 不要在用户活跃时强制重新加载
const bundle = await CapacitorUpdater.download({ url, version });
await CapacitorUpdater.reload();  // 打扰用户

iOS：使用 Swift Package Manager (SPM)

现代方法 - 优先使用 SPM 而非 CocoaPods：

# Podfile - 移除插件 pods，改用 SPM
target 'App' do
  capacitor_pods
  # 插件依赖通过 Xcode 中的 SPM 管理
end

Android：Gradle 配置

// android/app/build.gradle
android {
    defaultConfig {
        minSdkVersion 22
        targetSdkVersion 34
    }

    buildTypes {
        release {
            minifyEnabled true
            proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
        }
    }
}

// 用于 Web 测试的模拟
jest.mock('@capgo/capacitor-native-biometric', () => ({
  NativeBiometric: {
    isAvailable: jest.fn().mockResolvedValue({
      isAvailable: true,
      biometryType: 'touchId',
    }),
    verifyIdentity: jest.fn().mockResolvedValue({}),
  },
}));

import { Capacitor } from '@capacitor/core';

if (Capacitor.isNativePlatform()) {
  // 原生平台特定代码
} else {
  // Web 回退
}

// 或检查特定平台
if (Capacitor.getPlatform() === 'ios') {
  // iOS 特定代码
}

从配置中移除开发服务器 URL
为 Android 发布版本启用 ProGuard
设置适当的 iOS 部署目标
在真实设备上测试，而不仅仅是模拟器
验证所有权限都已声明
在网络条件差的情况下测试
验证深度链接正常工作
测试应用后台/前台切换
验证推送通知工作正常
测试生物识别身份验证的边缘情况

🇺🇸English

Capacitor Best Practices

Comprehensive guidelines for building production-ready Capacitor applications.

When to Use This Skill

Setting up a new Capacitor project
Reviewing Capacitor app architecture
Optimizing app performance
Implementing security measures
Preparing for app store submission

Project Structure

Recommended Directory Layout

my-app/
├── src/                      # Web app source
├── android/                  # Android native project
├── ios/                      # iOS native project
├── capacitor.config.ts       # Capacitor configuration
├── package.json
└── tsconfig.json

Configuration Best Practices

capacitor.config.ts (CORRECT):

import type { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'com.company.app',
  appName: 'My App',
  webDir: 'dist',
  server: {
    // Only enable for development
    ...(process.env.NODE_ENV === 'development' && {
      url: 'http://localhost:5173',
      cleartext: true,
    }),
  },
  plugins: {
    SplashScreen: {
      launchAutoHide: false,
    },
  },
};

export default config;

capacitor.config.json (AVOID):

{
  "server": {
    "url": "http://localhost:5173",
    "cleartext": true
  }
}

Never commit development server URLs to production

Plugin Usage

CRITICAL: Always Use Latest Capacitor

Keep Capacitor core packages in sync:

bun add @capacitor/core@latest @capacitor/cli@latest
bun add @capacitor/ios@latest @capacitor/android@latest
bunx cap sync

Plugin Installation Pattern

CORRECT :

# 1. Install the package
bun add @capgo/capacitor-native-biometric

# 2. Sync native projects
bunx cap sync

# 3. For iOS: Install pods (or use SPM)
cd ios/App && pod install && cd ../..

INCORRECT :

# Missing sync step
bun add @capgo/capacitor-native-biometric
# App crashes because native code not linked

Plugin Initialization

CORRECT - Check availability before use:

import { NativeBiometric, BiometryType } from '@capgo/capacitor-native-biometric';

async function authenticate() {
  const { isAvailable, biometryType } = await NativeBiometric.isAvailable();

  if (!isAvailable) {
    // Fallback to password
    return authenticateWithPassword();
  }

  try {
    await NativeBiometric.verifyIdentity({
      reason: 'Authenticate to access your account',
      title: 'Biometric Login',
    });
    return true;
  } catch (error) {
    // User cancelled or biometric failed
    return false;
  }
}

INCORRECT - No availability check:

// Will crash if biometrics not available
await NativeBiometric.verifyIdentity({ reason: 'Login' });

Performance Optimization

CRITICAL: Lazy Load Plugins

CORRECT - Dynamic imports:

// Only load when needed
async function scanDocument() {
  const { DocumentScanner } = await import('@capgo/capacitor-document-scanner');
  return DocumentScanner.scanDocument();
}

INCORRECT - Import everything at startup:

// Increases initial bundle size
import { DocumentScanner } from '@capgo/capacitor-document-scanner';
import { NativeBiometric } from '@capgo/capacitor-native-biometric';
import { Camera } from '@capacitor/camera';
// ... 20 more plugins

HIGH: Optimize WebView Performance

CORRECT - Use hardware acceleration:

<!-- android/app/src/main/AndroidManifest.xml -->
<application
    android:hardwareAccelerated="true"
    android:largeHeap="true">



<!-- ios/App/App/Info.plist -->
<key>UIViewGroupOpacity</key>
<false/>

HIGH: Minimize Bridge Calls

CORRECT - Batch operations:

// Single call with batch data
await Storage.set({
  key: 'userData',
  value: JSON.stringify({ name, email, preferences }),
});

INCORRECT - Multiple bridge calls:

// Each call crosses the JS-native bridge
await Storage.set({ key: 'name', value: name });
await Storage.set({ key: 'email', value: email });
await Storage.set({ key: 'preferences', value: JSON.stringify(preferences) });

MEDIUM: Image Optimization

CORRECT :

import { Camera, CameraResultType } from '@capacitor/camera';

const photo = await Camera.getPhoto({
  quality: 80,           // Not 100
  width: 1024,           // Reasonable max
  resultType: CameraResultType.Uri,  // Not Base64 for large images
  correctOrientation: true,
});

INCORRECT :

const photo = await Camera.getPhoto({
  quality: 100,
  resultType: CameraResultType.Base64,  // Memory intensive
  // No size limits
});

Security Best Practices

CRITICAL: Secure Storage

CORRECT - Use secure storage for sensitive data:

import { NativeBiometric } from '@capgo/capacitor-native-biometric';

// Store credentials securely
await NativeBiometric.setCredentials({
  username: 'user@example.com',
  password: 'secret',
  server: 'api.myapp.com',
});

// Retrieve with biometric verification
const credentials = await NativeBiometric.getCredentials({
  server: 'api.myapp.com',
});

INCORRECT - Plain storage:

import { Preferences } from '@capacitor/preferences';

// NEVER store sensitive data in plain preferences
await Preferences.set({
  key: 'password',
  value: 'secret',  // Stored in plain text!
});

CRITICAL: Certificate Pinning

For production apps handling sensitive data:

// capacitor.config.ts
const config: CapacitorConfig = {
  plugins: {
    CapacitorHttp: {
      enabled: true,
    },
  },
  server: {
    // Disable cleartext in production
    cleartext: false,
  },
};

HIGH: Root/Jailbreak Detection

import { IsRoot } from '@capgo/capacitor-is-root';

async function checkDeviceSecurity() {
  const { isRooted } = await IsRoot.isRooted();

  if (isRooted) {
    // Show warning or restrict functionality
    showSecurityWarning('Device appears to be rooted/jailbroken');
  }
}

HIGH: App Tracking Transparency (iOS)

import { AppTrackingTransparency } from '@capgo/capacitor-app-tracking-transparency';

async function requestTracking() {
  const { status } = await AppTrackingTransparency.requestPermission();

  if (status === 'authorized') {
    // Enable analytics
  }
}

Error Handling

CRITICAL: Always Handle Plugin Errors

CORRECT :

import { Camera, CameraResultType } from '@capacitor/camera';

async function takePhoto() {
  try {
    const image = await Camera.getPhoto({
      quality: 90,
      resultType: CameraResultType.Uri,
    });
    return image;
  } catch (error) {
    if (error.message === 'User cancelled photos app') {
      // User cancelled, not an error
      return null;
    }
    if (error.message.includes('permission')) {
      // Permission denied
      showPermissionDialog();
      return null;
    }
    // Unexpected error
    console.error('Camera error:', error);
    throw error;
  }
}

INCORRECT :

// No error handling
const image = await Camera.getPhoto({ quality: 90 });

Live Updates

Using Capacitor Updater

import { CapacitorUpdater } from '@capgo/capacitor-updater';

// Notify when app is ready
CapacitorUpdater.notifyAppReady();

// Listen for updates
CapacitorUpdater.addListener('updateAvailable', async (update) => {
  // Download in background
  const bundle = await CapacitorUpdater.download({
    url: update.url,
    version: update.version,
  });

  // Apply on next app start
  await CapacitorUpdater.set(bundle);
});

Update Strategy

CORRECT - Background download, apply on restart:

// Download silently
const bundle = await CapacitorUpdater.download({ url, version });

// User continues using app...

// Apply when they close/reopen
await CapacitorUpdater.set(bundle);

INCORRECT - Interrupt user:

// Don't force reload while user is active
const bundle = await CapacitorUpdater.download({ url, version });
await CapacitorUpdater.reload();  // Disrupts user

Native Project Management

iOS: Use Swift Package Manager (SPM)

Modern approach - prefer SPM over CocoaPods:

# Podfile - Remove plugin pods, use SPM instead
target 'App' do
  capacitor_pods
  # Plugin dependencies via SPM in Xcode
end

Android: Gradle Configuration

// android/app/build.gradle
android {
    defaultConfig {
        minSdkVersion 22
        targetSdkVersion 34
    }

    buildTypes {
        release {
            minifyEnabled true
            proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
        }
    }
}

Testing

Plugin Mocking

// Mock for web testing
jest.mock('@capgo/capacitor-native-biometric', () => ({
  NativeBiometric: {
    isAvailable: jest.fn().mockResolvedValue({
      isAvailable: true,
      biometryType: 'touchId',
    }),
    verifyIdentity: jest.fn().mockResolvedValue({}),
  },
}));

Platform Detection

import { Capacitor } from '@capacitor/core';

if (Capacitor.isNativePlatform()) {
  // Native-specific code
} else {
  // Web fallback
}

// Or check specific platform
if (Capacitor.getPlatform() === 'ios') {
  // iOS-specific code
}

Deployment Checklist

Remove development server URLs from config
Enable ProGuard for Android release builds
Set appropriate iOS deployment target
Test on real devices, not just simulators
Verify all permissions are declared
Test with poor network conditions
Verify deep links work correctly
Test app backgrounding/foregrounding
Verify push notifications work
Test biometric authentication edge cases

Resources

Capacitor Documentation: https://capacitorjs.com/docs
Capgo Documentation: https://capgo.app/docs
Ionic Framework: https://ionicframework.com/docs

Weekly Installs

279

Repository

cap-go/capacitor-skills

GitHub Stars

First Seen

Jan 25, 2026

Security Audits

Gen Agent Trust HubFail SocketPass SnykPass

Installed on

opencode225

codex213

gemini-cli208

github-copilot205

cursor178

kimi-cli172

React 组合模式指南：Vercel 组件架构最佳实践，提升代码可维护性

106,200 周安装

Capacitor 最佳实践指南：项目结构、插件使用与性能优化

🇨🇳中文介绍

Capacitor 最佳实践

何时使用此技能

项目结构

推荐的目录布局

配置最佳实践

相关 Skills

插件使用

关键：始终使用最新版 Capacitor

插件安装模式

插件初始化

性能优化

关键：延迟加载插件

高优先级：优化 WebView 性能

高优先级：最小化桥接调用

中优先级：图像优化

安全最佳实践

关键：安全存储

关键：证书锁定

高优先级：Root/越狱检测

高优先级：应用跟踪透明度 (iOS)

错误处理

关键：始终处理插件错误

实时更新

使用 Capacitor Updater

更新策略

原生项目管理

iOS：使用 Swift Package Manager (SPM)

Android：Gradle 配置

测试

插件模拟

平台检测

部署清单

资源

🇺🇸English

Capacitor Best Practices

When to Use This Skill

Project Structure

Recommended Directory Layout

Configuration Best Practices

Plugin Usage

CRITICAL: Always Use Latest Capacitor

Plugin Installation Pattern

Plugin Initialization

Performance Optimization

CRITICAL: Lazy Load Plugins

HIGH: Optimize WebView Performance

HIGH: Minimize Bridge Calls

MEDIUM: Image Optimization

Security Best Practices

CRITICAL: Secure Storage

CRITICAL: Certificate Pinning

HIGH: Root/Jailbreak Detection

HIGH: App Tracking Transparency (iOS)

Error Handling

CRITICAL: Always Handle Plugin Errors

Live Updates

Using Capacitor Updater

Update Strategy

Native Project Management

iOS: Use Swift Package Manager (SPM)

Android: Gradle Configuration

Testing

Plugin Mocking

Platform Detection

Deployment Checklist

Resources

最新 Skills