设置 Capacitor 本地环境

想使用 web 技术来开发 iOS 和 Android 应用？这里是如何快速高效地设置本地环境的。 Capacitor 安装必需软件

Node.js

(v20.0.0+):
- __CAPGO_KEEP_0__ (v9.0.0+) npm Git Git (v2.40.0+), 和一个现代的 IDE (例如, VS Code).
- 系统要求：8GB 内存，256GB 存储，Intel i5/AMD Ryzen 5 处理器。
iOS 设置 (macOS 只有):
- macOS 13.0+ (Ventura), Xcode 16.0+, CocoaPods 1.12.0+, 并且需要一个活跃的 Apple 开发者账户。
Android 设置:
- Android Studio Hedgehog (2023.1.1)+, Android SDK API 等级 23+, JDK 17, Gradle 8.0+.
- 为 Android 工具设置环境变量。

安装 Capacitor:

npm install @capacitor/core @capacitor/cli @capacitor/ios @capacitor/android

初始化项目:
- 使用或将 Capacitor 集成到现有应用中创建一个新项目 npx cap init.
添加平台:
```
npx cap add ios
npx cap add android
```
构建和同步:
- 构建 Web 资产 (npm run build) 并同步它们到本机平台 (npx cap sync).
启用实时更新:
- 使用 Capgo 实时更新的方式是：
```
npx @capgo/cli init
```
测试您的应用:
- 使用 iOS 模拟器 (npx cap open ios) 或 Android 模拟器 (npx cap open android).

快速提示：

更新 capacitor.config.ts 以管理环境并启用实时更新。例如：

const config: CapacitorConfig = {
  server: {
    url: process.env.NODE_ENV === 'development' ? 'http://localhost:3000' : 'https://production-url.com',
    cleartext: true
  }
};

此设置确保了您的 Capacitor 应用的开发、测试和部署流程顺畅。

Ionic Capacitor - 创建新应用 - 在 Android 和 iOS 上运行 …

必备设置

在继续之前，请确保您的系统满足必要的规范。

基本软件需求

安装以下工具:

软件	最低版本	注意
Node.js	__CAPGO_KEEP_0__	推荐使用LTS版本
npm	已内置于Node.js中	Git
v9.0.0+	v2.40.0+	用于版本控制的必备
VS Code/WebStorm	最新	任何现代的IDE都可以

您的机器应该至少有 8GB RAM, 256GB 存储,并且 Intel i5/AMD Ryzen 5 (或等效)处理器.

iOS 和 Android 设备的设置

iOS Requirements (macOS only):

macOS Ventura 13.0 或更高版本
Xcode 16.0 或更高版本 (从 Mac App Store 下载)
CocoaPods 1.12.0 或更高版本 (使用 sudo gem install cocoapods)
需要活跃的 Apple 开发者账户

Android Requirements (Windows/macOS/Linux):

Android Studio 2023.1.1 或更高版本
Android SDK API 23 或更高版本 (Android 6.0 或更高版本)
Java Development Kit (JDK) 17
Gradle 8.0+

通过在 shell 配置文件中添加这些行来设置 Android 环境变量：

export ANDROID_HOME=$HOME/Library/Android/sdk
export PATH=$PATH:$ANDROID_HOME/tools
export PATH=$PATH:$ANDROID_HOME/platform-tools

安装 Capacitor

使用 npm 安装 Capacitor

npm install @capacitor/core @capacitor/cli
npm install @capacitor/ios @capacitor/android

如果您正在使用像 Vue、React 或 Angular 这样的框架，安装相应的 Capacitor 插件。对于 Vue，运行：

npm install @capacitor/vue

确认安装，请通过运行来检查 Capacitor 版本：

npx cap --version

您应该看到当前 Capacitor 版本（例如，截至 2025 年 4 月的 5.x.x）。

最后，在项目目录中初始化 Capacitor：

npx cap init

完成后，您可以为您的项目配置这些组件。

设置说明

项目设置

开始前，创建一个 新 Capacitor 项目 或将Capacitor集成到现有的Web应用中：

npm init @capacitor/app
cd my-cap-app
npm install

如果您正在将Capacitor添加到现有的Web应用中，请在项目目录中初始化它：

cd your-web-app
npm install @capacitor/core @capacitor/cli
npx cap init [appName] [appId]

初始化后，您需要为原生开发添加必要的平台。

平台设置

将iOS和Android平台添加到您的项目中：

npm install @capacitor/ios @capacitor/android
npx cap add ios
npx cap add android

更新您的 capacitor.config.ts 文件以包含所需的配置：

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

const config: CapacitorConfig = {
    appId: 'com.example.app',
    appName: 'My Capacitor App',
    webDir: 'dist',
    bundledWebRuntime: false,
    plugins: {
      // Add plugin settings here
    }
};

export default config;

构建过程

通过运行： 同步您的项目与原生平台

npm run build

同步后，请确保配置环境和实时更新设置。:

npx cap sync

Platform Setup

环境设置

为了管理环境，更新你的 capacitor.config.ts 文件：

const config: CapacitorConfig = {
    server: {
      url: process.env.NODE_ENV === 'development'
        ? 'http://localhost:3000'
        : 'https://production-url.com',
      cleartext: true
    }
};

通过 Capgo 来实现实时更新：

npx @capgo/cli init

测试设置

使用以下命令设置你的测试环境：

环境	命令	需求
iOS模拟器	`npx cap open ios`	Xcode已安装
Android模拟器	`npx cap open android`	已配置Android Studio
实时重载	`npx cap run [platform]`	开发服务器正在运行

在物理设备上进行测试:

确保您的iOS设备已在Apple Developer帐户中注册。
在Android设备上启用USB调试。
确认开发证书已正确设置。

“We practice agile development and @Capgo is mission-critical in delivering continuously to our users!” – Rodrigo Mantica [1]

Capgo’s channel system is a great tool for beta testing and staged rollouts. It lets you target specific user groups with different versions, helping you identify and fix issues before a broader release [1].

Additional Features

扩展您的Capacitor设置，使用工具来改进更新传递、简化自动化和允许定制配置。

Capgo 设置

Capgo实时更新控制台界面

使用Capgo的实时更新系统来简化您的工作流程。要开始，请运行：

npx @capgo/cli init

然后，调整您的 capacitor.config.ts 文件以启用实时更新：

{
  plugins: {
    CapacitorUpdater: {
      autoUpdate: true,
      statsUrl: 'https://your-stats-endpoint.com'
    }
  }
}

Capgo的全球CDN提供了出色的速度，5MB的捆绑包仅需114ms即可下载。 [1]一旦实时更新设置完成，您就可以自动化您的构建以实现更平滑的部署。

构建自动化

将Capgo与您的CI/CD管道集成以自动化构建和部署。它支持以下流行平台：

CI/CD平台	集成方式	关键优势
GitHub 动作	直接工作流	自动部署触发器
GitLab CI	管道集成	版本控制同步
Jenkins	插件支持	自定义构建步骤

这是一个 CI/CD pipeline 配置的示例：

build_and_deploy:
  steps:
    - run: npm run build
    - run: npx cap sync
    - run: npx @capgo/cli deploy

自定义设置

通过设置特定的配置项来定制您的应用程序，超出实时更新和自动化：

const config: CapacitorConfig = {
  ios: {
    contentInset: 'automatic',
    preferredContentMode: 'mobile'
  },
  android: {
    backgroundColor: '#ffffff',
    allowMixedContent: true
  },
  plugins: {
    SplashScreen: {
      launchAutoHide: true,
      backgroundColor: '#ffffffff',
      androidScaleType: 'CENTER_CROP'
    }
  }
};

为了更好的性能，考虑以下选项：

启用端到端加密
配置用户分配
设置分析跟踪
使用回滚功能

这些工具贡献了全球 750 个生产应用程序中的 82% 的成功率 [1].

问题解决

这是如何解决常见问题并改善您的设置以实现更流畅的工作流程的方法

常见问题

依赖项冲突
如果您遇到依赖项冲突，请尝试这些命令：

npm ls @capacitor/core
rm -rf node_modules
npm install

平台相关问题

平台	问题	解决方案
iOS	Xcode构建失败	更新CocoaPods并运行 `pod install`
Android	Gradle同步错误	清除Gradle缓存并更新Android Studio
两者都	Live reload 不工作	在 `capacitor.config.ts`

版本兼容性
确保您的配置与以下示例保持一致:

const config: CapacitorConfig = {
  appId: 'com.example.app',
  appName: 'My App',
  webDir: 'dist',
  bundledWebRuntime: false,
  plugins: {
    CapacitorUpdater: {
      autoUpdate: true
    }
  }
};

通过早期解决这些问题，可以避免不必要的障碍。

设置提示

以下是改善稳定性并避免反复出现问题的方法。

最佳实践

使用内置错误跟踪功能快速识别和解决问题 [1].
设置更新频道用于控制发布:

{
  channels: {
    beta: {
      percentage: 25,
      deviceId: ['test-device-1']
    },
    production: {
      percentage: 100
    }
  }
}

Automated Maintenance

Regularly update your dependencies.
Configure rollback settings to handle failed updates:

{
  rollback: {
    enabled: true,
    maxVersions: 3,
    timeout: 300000
  }
}

Use end-to-end encryption to secure updates [1].

Summary

Here’s a quick recap of how an optimized Capacitor environment can improve your development process. Setting up your local Capacitor environment the right way speeds up development, streamlines builds, and simplifies updates.

Key Advantages of Proper Setup

Instant updates make development cycles faster.
Automated and dependable build processes save time and effort.

These improvements come from following the setup and integration practices discussed earlier.

Performance Highlights

Capgo-增强 Capacitor 环境能够显示出显著的效果，包括快速响应时间、快速下载和更新成功率高 [1].

开发者优势

正确配置的环境使开发者能够专注于创建功能而不是处理基础设施。本指南中概述的设置确保您可以充分利用这些优势，同时满足平台要求

继续阅读：设置 Capacitor 本地环境

如果您正在使用 设置 Capacitor 本地环境 来规划原生插件工作，连接它到 Capgo 插件目录为 Capgo 插件目录中的产品工作流程 Capacitor 由 Capgo 提供的插件为 Capacitor 由 Capgo 提供的插件中的实现细节添加或更新插件为添加或更新插件的实现细节 Ionic 企业插件替代品为 Ionic 企业插件替代品的产品工作流程 Capgo 原生构建为 Capgo 原生构建的产品工作流程