安装 Capacitor CLI：分步指南

Capacitor CLI 助您通过一套代码将 Web 应用转换为原生 iOS 和 Android 应用。 以下是快速设置步骤：

前提条件: 安装 Node.js (v16+), npm 以及 Web 框架 (React, Vue, Angular 等)。
安装 Capacitor CLI: 运行 npm install @capacitor/cli @capacitor/core 并使用以下命令初始化你的项目： npx cap init.
准备平台: 添加 iOS (npx cap add ios) 和 Android (npx cap add android) 平台支持。
构建与同步: 使用 npm run build 和 npx cap sync 将 Web 资源传输到 Native Build 项目中。
可选的 Live Updates：使用如下工具 Capgo 即可实现即时推送更新，无需等待 App Store 审核。

Capacitor CLI 让 App 开发与维护更简单。请参考本指南进行顺畅的安装与故障排除。

快速构建移动 App！React + Capacitor + Tailwind + DaisyUI

Capacitor Framework 文档网站

开始之前

请按照以下步骤准备您的开发环境：

环境搭建 Node.js 以及 npm

Node.js

您需要 Node.js 16 或更高版本。建议使用最新的 LTS 版本。运行以下命令检查环境：

node --version
npm --version

如果需要更新，请从官网下载 Node.js（其中包含 npm）。

确认 Node.js 就绪后，请确保您的 Web 项目符合必要的 Capacitor 要求。

检查 Web 项目

您的 Web 项目应具备以下内容：

有效的 package.json：请确保其配置正确。
构建目录：这里存放你的 Web 资源（通常为 dist 或 www).
入口点：你的构建目录必须包含一个 index.html 文件中设置。

快速查看关键 package.json 字段：

必填字段	示例值	用途
name	“my-app”	识别项目
版本	“1.0.0”	指定 App 版本
构建目录	“dist” 或 “www”	指向 Web 资源

准备好 Node.js 和 Web 项目后，即可开始安装特定平台的工具。

安装所需软件

Android 开发环境：

下载并安装最新版本的 Android Studio.
设置 Android SDK，其 SDK 版本至少为 API level 22。
配置 ANDROID_HOME 环境变量。

iOS 开发环境 (仅限 Mac):

安装 Xcode 14 或更高版本。
安装 Command Line Tools。
使用使用 Homebrew 来安装 CocoaPods:
```
brew install cocoapods
```
接受 Xcode 许可协议：
```
sudo xcodebuild -license accept
```

稍后集成 Capgo 时，请确保您的网络连接稳定且 SSL 证书有效。

完成这些步骤后，您就可以开始顺畅的 Capacitor 开发流程了。接下来，您将安装 Capacitor CLI。

安装 Capacitor CLI

环境准备就绪后，即可开始安装并配置 Capacitor CLI。

添加 Capacitor Packages

首先使用 npm 安装 Capacitor CLI 和 Core packages：

npm install @capacitor/cli @capacitor/core

安装完成后，通过检查以下内容来确认配置是否成功： Capacitor CLI 版本:

npx cap --version

设置您的项目

使用以下命令在项目中初始化 Capacitor：

npx cap init

在初始化过程中，系统会提示您提供以下详细信息：

设置项	描述	示例
应用名称	在应用商店中显示的名称	“我的超赞应用”
App ID	应用的唯一标识符	“com.mycompany.myapp”
Web 目录	Web 资源所在的路径	“dist” 或 “www”

接下来，更新你的配置文件 (capacitor.config.ts 或 capacitor.config.json) 并配置相关设置：

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

const config: CapacitorConfig = {
  appId: 'com.mycompany.myapp',
  appName: 'My Awesome App',
  webDir: 'dist',
  bundledWebRuntime: false
};

export default config;

配置 iOS 和 Android

使用以下命令添加 iOS 和 Android 平台支持：

npx cap add ios
npx cap add android

这将生成 Native Build 项目：

iOS：创建一个包含 ios 文件夹，其中包含 Xcode 项目。
Android：创建一个包含 android 文件夹，用于 Android Studio 项目。

修改 Web 资源后，请运行以下命令进行 build 和 sync：

npm run build
npx cap sync

此过程会编译您的 Web 资源并将其传输到原生项目中，包括所有已安装的 Capacitor 插件.

若要打开原生项目进行进一步自定义：

npx cap open ios     # Opens Xcode
npx cap open android # Opens Android Studio

现在您可以开始测试配置并解决可能出现的问题了。

解决常见问题

在配置 Capacitor CLI 时，您可能会遇到一些常见问题。以下是解决方法：

Android Gradle 问题

如果您遇到 Gradle 相关问题，请尝试以下步骤：

进入 Android 目录并清理 build 缓存：
```
cd android
./gradlew cleanBuildCache
```

更新以下文件中的 Gradle 版本： android/build.gradle:

buildscript {
    ext {
        gradleVersion = '8.1.0'
    }
}

在以下内容中添加如下代码行： android/gradle.properties 以获得更佳性能：
```
org.gradle.jvmargs=-Xmx4608m
org.gradle.parallel=true
```

如果问题仍然存在，请重新检查配置或查阅其他故障排除资源。

App 显示白屏

白屏通常指向配置问题。请按照以下步骤进行排查：

检查 Web 目录路径: 请确保 webDir 与您的 build 输出一致。

const config: CapacitorConfig = {
    webDir: 'dist', // Adjust if necessary
};

验证服务器配置: 确认服务器设置是否正确。

server: {
    url: 'http://localhost:3000',
    cleartext: true
}

更新内容安全策略 (CSP): 在 HTML 中添加此 meta 标签，以确保资源能够正常加载。

<meta http-equiv="Content-Security-Policy" content="default-src 'self' 'unsafe-inline' 'unsafe-eval' data: *">

Plugin 无法工作

如果插件运行异常，请按照以下步骤操作：

重新进行依赖项的全新安装：

rm -rf node_modules
npm cache clean --force
npm install

检查以下位置的插件设置， capacitor.config.ts 以确保配置正确：

plugins: {
    PluginName: {
        option: 'value'
    }
}

对于使用 Capgo 原生插件的用户，它会在更新期间自动同步插件并保持兼容性。

应用这些修复后，请重新构建项目以验证更改：

npm run build && npx cap copy && npx cap sync

一切运行正常后，即可通过 Capgo 开始探索 live update 的各项功能。

Live Updates with Capgo

Capgo Live Update Dashboard 界面

简化应用更新使用 Capgo。它允许你直接向用户推送更新，无需经过应用商店审核。

上手非常简单。 首先，安装必要的软件包：

npm install @capgo/cli @capgo/capacitor-updater
npx cap sync

然后，在你的项目中初始化 Capgo：

npx @capgo/cli init

价格方案

Capgo 提供多种价格层级以满足不同需求：

方案	月活跃用户数	带宽	存储空间	价格（年付）
个人版	1,000	50 GB	2 GB	$12/月
创客版	10,000	500 GB	5 GB	$33/月
团队版	100,000	2,000 GB	10 GB	$83/月

对于企业用户，PAYG 方案起步价为 $249/月，包含 API 访问权限、自定义域名以及专属技术支持等权益。

Live Updates 配置

若要启用 Live Updates，请在以下内容中添加： capacitor.config.ts 文件：

{
  plugins: {
    CapacitorUpdater: {
      autoUpdate: true,
      updateUrl: 'https://api.capgo.app/updates'
    }
  }
}

核心特性

Capgo 提供以下几项卓越特性：

安全更新 支持端到端加密
自动化部署 通过集成的 CI/CD 实现
精准更新 通过用户分配
即时回滚 具备版本控制
实时分析 追踪更新

部署命令

在正式部署前，先在开发环境中测试更新。请使用以下命令：

部署到 staging 环境：
```
npx @capgo/cli deploy --channel staging
```

部署到 production 环境：

npx @capgo/cli deploy --channel production

Capgo 确保符合 Apple 和 Android 的指南，从而避免您的 Live Update 违反 App Store 规则。这是安装后管理 Capacitor 应用的高效方式。

总结

只要具备正确的先决条件，设置 Capacitor CLI 就非常简单。此配置可确保更顺畅的应用更新和高效的开发工作流。

现代化的工具让应用维护变得前所未有的简单。例如，Capgo 现在提供实时更新，取代了旧方法。它与 CLI 安装流程的集成，让它成为开发 Capacitor 应用的理想选择。

该 Capacitor 生态系统正通过不断推出的新工具和功能持续进化。安装 CLI 只是开发移动应用的第一步，你还将受益于详尽的文档和活跃的开发者社区。

请务必保持 Capacitor CLI 及其相关包处于最新版本，以避免兼容性问题。

继续阅读：安装 Capacitor CLI 分步指南

如果你正在使用 安装 Capacitor CLI：分步指南 来规划 dashboard 和 API 操作，请将其连接至 API 概览关于 API 概览中的实现细节，简介有关 Introduction 中的实现细节， API 密钥关于 API Keys 中的实现细节，设备关于 Devices 中的实现细节，以及 Bundle 关于 Bundles 中的实现细节。