想要通过一套代码构建 iOS 和 Android 应用吗？ Capacitor CLI 简化了这一流程，让你能用 Web 技术创建原生应用。下面是你将学到的内容：
- 快速设置: 在几分钟内安装 Capacitor CLI 并初始化你的项目。
- 平台集成：通过简单命令添加 iOS 和 Android 支持。
- Capgo Live Updates：使用 Capgo 实现即时空中更新。
- 常见修复：排查同步错误或构建失败等问题。
入门关键步骤：
- 安装 Node.js、npm、JDK、 Xcode 的 Mac，以及 Android Studio 中的错误日志.
- 运行
npm install @capacitor/core @capacitor/cli并初始化你的项目。 - 使用以下命令添加 iOS 和 Android 平台：
npx cap add ios以及npx cap add android. - 可选：配置 Capgo 用于实时 应用更新.
本指南涵盖设置 Capacitor CLI、配置平台以及部署应用所需的一切。让我们开始吧！
全新推出 Capacitor 配置
设置要求
开始之前，请确保已安装以下工具：
- Node.js （14 或更高版本）以及 npm
- Java JDK （11 或更高版本）
- Xcode 的 Mac （iOS 构建需 12 或更高版本）
- Android Studio 中的错误日志 （用于 Android 构建）
- Capacitor CLI （版本 6 或 7）
可选： 如需启用 Live Update，请查看下方的“Capgo 配置指南”。
CLI 安装步骤
开始前，请确保您已具备 Node.js, npm, JDK, Xcode 的 Mac，以及 Android Studio 中的错误日志 设置完成。准备好后，运行以下命令即可安装 Capacitor CLI：
npm install --save @capacitor/core @capacitor/cli
npx cap init这个命令会安装 Capacitor 并设置其核心组件。
完成此步骤后，请继续前往 创建新项目 来搭建你的应用程序。
创建新项目
开始使用你的项目 使用 Capacitor CLI，请按以下步骤操作：
mkdir my-app && cd my-app
npm init -y
npx cap init my-app com.company.app --web-dir dist更新配置文件
编辑 capacitor.config.json 文件，添加以下设置：
{
"appId": "com.company.app",
"appName": "My App",
"webDir": "dist",
"bundledWebRuntime": false,
"server": {
"hostname": "app.example.com",
"androidScheme": "https"
}
}更新完成后，使用此配置为项目设置 Capacitor。
平台配置
项目脚手架搭建完成后，接下来配置 iOS 和 Android 目标平台。
添加 iOS 和 Android
首先，使用 Capacitor CLI 安装必要的平台特定包：
npm install @capacitor/ios @capacitor/android
npx cap add ios
npx cap add android对于 iOS，请确保已安装 Xcode 14 或更高版本， CocoaPods 1.11 或更高版本，以及 macOS 12 或更高版本。对于 Android，您需要 Android Studio Giraffe (2022.3.1+)、JDK 17 或更高版本，以及 Gradle 7.5 或更高版本。
安装完成后，您需要将原生目标与 Web 应用程序的更改保持同步。
平台更新
要同步平台以获取最新的 Web 更改，请在更新 Web 应用后执行以下步骤：
npm run build
npx cap sync本指南中介绍的 cap sync 命令处理两个任务：
- 将更新的 Web 资源复制到原生平台
- 更新原生配置和插件以匹配最新更改
IDE 设置
在相应的 IDE 中打开特定平台的项目：
npx cap open ios # Opens Xcode
npx cap open android # Opens Android Studio在 Xcode 中：
- 选择您的开发团队。
- 配置签名证书。
- 更新你的 Bundle Identifier。
在 Android Studio 中：
- 修改以下文件中的 Application ID：
build.gradle. - 配置用于签名的 Keystore。
- 配置 Debug 和 Release 两种构建变体。
配置完成后，使用以下命令构建项目： npx cap build ios 或 npx cap build android。别忘了再次运行 npx cap sync 以确保所有资源都是最新的。
Capgo 设置指南
配置 Capgo，为你的应用启用即时 OTA 更新。
Capgo 的核心特性
Capgo 提供多种工具来简化应用更新流程：
- 端到端加密 确保更新安全下发。
- 更新会在 后台运行 ，并在应用启动时执行。
- 分析工具 有助于追踪更新成功率和用户参与度。
- 一套 一键回滚 该选项可让你快速从有问题的更新中恢复。
- 使用 channel 系统 适用于分阶段发布和 Beta 测试。
安装 Capgo
按照以下步骤开始使用 Capgo：
-
npm install --save @capgo/cli -
初始化 Capgo 在你的项目中：
npx capgo init -
构建并发布更新：
npm run build npx capgo release -
打开 App 以触发后台更新流程。
最佳实践
- 使用 channels 先测试更新，再推送给所有用户。
- 监控分析数据，确保更新成功送达并保持用户活跃。
- 启用错误追踪功能，以便及早发现并修复问题。
- 让回滚功能随时可用，以便快速处理问题。
Capgo 兼容 Capacitor 8，可无缝集成到 CI/CD pipeline 中，并符合 Apple 和 Google 应用商店的要求。
常见问题与技巧
完成平台和 Capgo 配置后，你可能会遇到一些常见错误。以下是快速解决这些问题的方法。
环境配置问题
-
未找到 CLI 错误：该命令
npx cap失败。 修复: 运行npm install --save @capacitor/cli @capacitor/core然后重试。 -
Node 版本不匹配 错误：由于 Node.js 版本错误，CLI 命令执行失败。 修复：请按照安装要求，安装 Node.js 14 或更高版本。
配置问题
-
配置不匹配 错误：更改
capacitor.config.json不会生效。 修复：请确保appId以及webDir的值与您项目的package.json以及 Web build 输出目录一致。 -
平台同步错误 错误：运行
npx cap sync会导致插件版本冲突。 修复：更新@capacitor/android以及@capacitor/ios到相同的主版本，然后重新运行 sync 命令。
构建与部署
-
构建签名失败 错误：由于缺少证书或 keystore，iOS 或 Android 构建失败。 修复：请按照 IDE 设置说明操作。对于 iOS，请在 Xcode 中添加你的开发团队。对于 Android，请在
build.gradle. -
未找到 Web 目录 错误:
npx cap sync无法找到 Web 资源。 修复：运行你的 web build 命令（例如：npm run build），然后再同步各平台。
Live Update 问题
- Capgo 更新失败
错误：生产环境的 App 中未显示更新。
修复：请仔细检查你的 Capgo API 密钥 中的
capacitor.config.json并确保你针对的是正确的 channel。
有关平台特定配置的更多详情，请重新查看 Platform Setup 部分。如果你在使用 live updates，请参考 Capgo Setup Guide 获取更多故障排查建议。
总结
配置回顾
使用 Capacitor CLI 启动你的 Web 应用，配置 iOS 和 Android 平台，并可选择加入 Capgo 来支持 live updates。
入门步骤如下：
- 使用 Capacitor CLI 初始化你的项目。
- 配置应用的 package ID，并指定 Web 输出目录。
- 添加对 iOS 和 Android 平台的支持。
- 使用以下命令安装并配置 Capgo：
npm install --save @capgo/cli && npx capgo init
如需详细的配置说明或故障排除，请查阅官方 Capacitor 和 Capgo 文档。
继续阅读 Capacitor CLI：项目设置指南
如果你正在使用 Capacitor CLI: 项目搭建指南 要规划 dashboard 和 API 操作，请将其连接到 API 概览 关于 API Overview 中的实现细节， 简介 关于 Introduction 中的实现细节， API 密钥 有关 API Keys 的实现细节， 设备 有关 Devices 的实现细节，以及 Bundle 有关 Bundles 中的实现细节。
