Capacitor CLI lets you customize your app’s build process for iOS, Android, and web platforms. By tweaking build scripts, you can:
- Speed up updates: Push changes instantly without app store delays.
- Control deployments: Roll back updates or target specific user groups.
- Secure your app: Use encryption to protect updates.
- Optimize builds: Adjust settings for platform-specific needs.
快速概览：关键功能
- 配置文件: 使用
capacitor.config.json和package.json来管理构建设置。 - 自定义脚本: 为自动化添加预构建和后构建任务。
- 构建钩子: 在构建过程的特定阶段运行 code。
- 环境变量: 使用
.env文件简化环境特定构建。
全局性能优化 Capacitor 介绍
Capacitor 框架文档网站
Understanding how Capacitor handles its default build process is crucial if you want to customize it effectively. Below, we’ll break down the Capacitor CLI’s build process and its key configuration files.
默认构建过程在 __CAPGO_KEEP_0__ 中
Capacitor 使用一步一步的过程将您的 Web 应用程序转换为平台特定的构建。以下是默认构建过程中的发生事件：
| 阶段 | 描述 | 输出 |
|---|---|---|
| Web 构建 | 使用您的框架工具编译 Web 资产 | 优化的 Web 包 |
| 复制资产 | 将 Web 资产移动到本机平台文件夹 | 平台特定资产目录 |
| 本机构建 | 运行平台特定构建命令 | Ready-to-deploy binaries |
| 验证 | 检查构建完整性和依赖项 | 构建状态和警告 |
主配置文件
两个关键配置文件决定了Capacitor如何处理您的构建：
capacitor.config.json
这是您的Capacitor项目的核心配置文件。它设置了构建的重要参数：
{
"appId": "com.example.app",
"appName": "MyApp",
"webDir": "dist",
"bundledWebRuntime": false,
"plugins": {
"SplashScreen": {
"launchShowDuration": 3000
}
}
}appId：您的应用程序的唯一标识符。appName：您的应用程序的名称。webDir：指定Capacitor应该在哪里查找Web资产（例如：dist).plugins：允许您配置插件特定的设置，如SplashScreen选项。
package.json
本文件包含构建脚本和依赖项，影响构建过程：
{
"scripts": {
"build": "npm run build:web && cap sync",
"build:web": "vite build",
"cap:build": "cap build"
}
}- The
webDir设置capacitor.config.json告诉 Capacitor 在哪里查找您的编译 Web 资产，以便在本机构建中包含。 - 修改
capacitor.config.json后，您需要运行cap sync以确保您的本机项目已更新。
接下来，我们将探索如何修改这些设置以进一步定制您的构建。
修改构建脚本
您可以调整 Capacitor 的默认构建过程以更好地适应您的项目需求。以下是如何做到的：
配置文件设置
您可以通过编辑 capacitor.config.json 文件来调整构建过程。以下是示例配置：
{
"appId": "com.example.app",
"webDir": "www",
"server": {
"hostname": "localhost",
"androidScheme": "https",
"iosScheme": "https",
"allowNavigation": ["*.example.com"]
},
"android": {
"buildOptions": {
"keystorePath": "release.keystore",
"keystorePassword": "mypassword",
"keystoreAlias": "release",
"keystoreAliasPassword": "mypassword"
}
},
"ios": {
"scheme": "App",
"automaticProvisioning": true
}
}以下是您可以修改的关键设置：
webDir：指定您的编译后的Web资产所在位置。server：配置开发服务器，包括主机名和导航权限。android/ios：允许平台特定的构建设置，例如Android的keystore详细信息或iOS的分发选项。
创建NPM脚本
为了简化您的工作流程，添加自定义NPM脚本到您的 package.json 文件中。以下是示例：
{
"scripts": {
"prebuild": "node ./scripts/prepare-env.js",
"build": "npm run build:web && cap sync",
"build:web": "vite build",
"build:ios": "cap build ios --release",
"build:android": "cap build android --release",
"postbuild": "node ./scripts/notify-completion.js"
}
}prebuild和postbuild：用于任务，如设置环境或在构建完成时发送通知。build:platform：平台特定的命令，用于构建Android或iOS应用。
您可以通过添加构建钩子来进一步自动化.
构建钩子设置
为了实现更高级别的控制，使用构建钩子来执行自定义code，在构建过程的特定点。以下是一个示例设置在 capacitor.config.ts:
import { CapacitorConfig } from '@capacitor/cli';
const config: CapacitorConfig = {
appId: 'com.example.app',
plugins: {
CapacitorHooks: {
beforeBuild: async () => {
console.log('Running pre-build tasks...');
// Add your pre-build tasks here
},
afterBuild: async () => {
console.log('Running post-build tasks...');
// Add your post-build tasks here
}
}
}
};
export default config;使用构建钩子，您可以：
- 在构建开始之前验证要求
- 在过程中转换资产
- 在关键点触发通知
- 自动更新版本号
- 无缝运行自动化测试
这种方法为您提供了更大的灵活性和控制整个构建生命周期的能力.
高级构建定制
当处理更大的项目时，精细调整您的构建过程可以带来很大的不同。以下是如何有效地处理环境特定的构建和平台定制。
环境变量
通过创建每个环境的单独文件来设置环境变量: .env 然后，配置您的构建脚本以根据环境加载适当的文件:
.env.development.env.staging.env.production
您还可以根据平台的具体要求调整这些设置。
import { defineConfig } from '@capacitor/cli';
export default defineConfig({
ios: {
buildConfig: {
environment: process.env.BUILD_ENV || 'development',
configurations: {
development: {
signing: {
debug: true,
automaticProvisioning: true
}
},
production: {
signing: {
release: true,
provisioningProfile: 'dist/profile.mobileprovision'
}
}
}
}
}
});平台特定构建
要为 Android 和 iOS 自定义构建，请使用以下结构:
这些配置允许您为每个平台定制构建，从而实现更顺畅的部署。
const platformConfig = {
android: {
buildType: process.env.BUILD_TYPE || 'debug',
keystoreConfig: {
path: process.env.KEYSTORE_PATH,
password: process.env.KEYSTORE_PASSWORD,
alias: process.env.KEYSTORE_ALIAS
}
},
ios: {
scheme: process.env.APP_SCHEME || 'App',
xcodePreferences: {
automaticSigning: false,
developmentTeam: process.env.DEVELOPMENT_TEAM
}
}
};功能
| Android | iOS | 调试符号 |
|---|---|---|
| Environment Variables:__CAPGO_KEEP_0__ | ProGuard 映射文件 | dSYM 文件 |
| 构建变体 | debug,发布,测试 | debug,发布 |
| Code Signing | 密钥库管理 | 分发配置文件 |
| 资产管理 | res/drawable 优化 | 资产目录 |
优化构建的额外提示包括：
- 使用部分更新来节省部署过程中的时间
- 设置错误跟踪来快速识别问题
- 创建渠道系统来测试beta版本
- 启用端到端加密来实现安全的分布
与 Capgo 等工具配对使用时，分析和安全更新的这些技术可以让您更好地控制您的部署过程 [1].
构建脚本问题与解决方案
在使用自定义构建配置时，快速解决错误对于保持构建过程顺畅至关重要
修复常见错误
许多构建脚本问题源于环境设置或依赖问题。以下是如何解决一些常见问题的方法：
缺少环境变量
如果您遇到以下错误：
error: Cannot find environment configuration for BUILD_ENV您可以通过在项目根目录中创建一个 .env.local 文件来修复它。以下是一个示例：
BUILD_ENV=development
CAPACITOR_PLATFORM=ios
BUILD_TYPE=debug平台特定构建失败
对于 Android 签名错误，使用以下命令：
npx cap build android --keystorePassword=$KEYSTORE_PASSWORD --keystoreAlias=$KEYSTORE_ALIAS对于 iOS 配置文件问题，尝试以下：
npx cap build ios --configuration=release --type=development| 错误类型 | 常见原因 | 解决方案 |
|---|---|---|
| 签名配置 | 缺少 keystore 详细信息 | 设置 KEYSTORE_PATH 和凭证 |
| 环境构建 | 未定义的变量 | 创建平台特定的 .env 文件 |
| 依赖项 | 版本不符 | 更新 package.json 并同步 |
修复后，请确保您的更改是稳固的，通过运行全面构建测试来验证。
测试构建脚本
一旦错误得到解决，使用以下步骤验证您的构建脚本：
- 自动验证: 运行关键命令以确认构建过程如预期般正常工作。
npm run build
npx cap sync
npx cap copy- 环境验证: 在开始构建之前检查缺失的环境变量。
const requiredVars = ['BUILD_ENV', 'KEYSTORE_PATH'];
requiredVars.forEach(varName => {
if (!process.env[varName]) {
throw new Error(`Missing required env var: ${varName}`);
}
});- 构建脚本调试: 在构建过程中捕获潜在问题的详细脚本。
{
"scripts": {
"build:debug": "NODE_ENV=development npx cap build --verbose",
"build:release": "NODE_ENV=production npx cap build --verbose"
}
}测试的额外提示：
Capgo 构建功能
Capgo 将构建脚本推向下一个层次，通过自动部署提高效率并简化流程.
快速应用更新
Capgo 的更新性能令人印象深刻:
- 95% 的活跃用户 在 24 小时内接收更新.
- 82% 的成功率 全球配送更新。
- 全球平均 API 响应时间为 434ms.
该平台使用部分更新，这意味着只下载更改。这一方法减少了带宽使用量并加快了更新过程。另外，整个构建过程完全自动化，节省了时间和精力。
构建自动化
Capgo 与主要的CI/CD平台无缝整合，提供多种集成：
| CI/CD平台 | 集成功能 | 好处 |
|---|---|---|
| GitHub 动作 | 自动化构建、部署触发器 | 持续部署 |
| GitLab CI | 管道自动化、版本控制 | 流程化工作流 |
| Jenkins | 自定义工作流、构建钩子 | 适合企业级 |
通常设置自动构建的成本约为 $300/月,远低于传统解决方案的 $6,000/年.
安全标准
Capgo 以强大的框架优先考虑安全性，包括：
- 更新包的端到端加密。
- 安全密钥管理。
- 遵守苹果和谷歌的指南。
版本控制功能
- 即时回滚选项。
- 跟踪部署版本。
- 为阶段性发布设置的更新频道管理。
此安全框架已在数百个企业应用程序中进行了严格的测试。对于需要额外安全性的团队,Capgo还提供了自主托管的解决方案，具有可自定义的配置。
Capgo的频道系统使更新分发更加灵活。开发人员可以针对特定用户组使用不同的版本，适合测试或逐步发布。
概要
构建步骤概览
自定义构建脚本允许通过利用构建钩子、环境变量和平台特定命令来实现自动化和一致的部署。这些过程为通过Capgo实现的部署改进奠定了坚实的基础。
Capgo 的好处
Capgo 简化了部署，成功部署了超过 2,350 万次更新，覆盖了 750 个生产应用 [1]. 部分更新系统减少了带宽使用量和部署时间
该平台提供快速更新、全球性能优化、端到端加密以确保安全性，以及灵活的通道式分布系统。这一设置支持目标更新、beta 测试以及遵守应用商店指南，同时保持强大的安全框架
从 How to Customize Build Scripts with Capacitor CLI 中继续
如果您正在使用 How to Customize Build Scripts with Capacitor CLI 来规划 CI/CD 自动化，连接它与 Capgo CI/CD 在 Capgo CI/CD 中的产品工作流 Capgo 原生构建 在 Capgo 原生构建 中的产品工作流 Capgo 集成 为产品工作流程在 Capgo 集成中 CI/CD 集成 为 CI/CD 集成的实现细节 GitHub 动作集成 为 GitHub 动作集成的实现细节
