Capacitor CLI lets you customize your app’s build process for iOS, Android, and web platforms. By tweaking build scripts, you can:
- 加速更新: 立即推送更改，无需等待应用商店延迟。
- 控制发布: 回滚更新或针对特定用户组。
- 保护应用安全: 使用加密保护更新。
- 优化构建: 根据平台需求调整设置。
快速概览：关键功能
- 配置文件: 使用
capacitor.config.json和package.json为了管理构建设置。 - 自定义脚本: 为自动化添加预构建和后构建任务。
- 构建钩子: 在构建过程的特定阶段运行 code。
- 环境变量: 使用文件简化环境特定的构建。
.env__CAPGO_KEEP_0__
Capgo自定义脚本 : 为自动化添加预构建和后构建任务。Cloudflare、Capacitor、GitHub、Capgo、code、API、SDK、CLI、npm、bun
介绍 Capacitor 配置
默认构建过程在 Capacitor
了解 Capacitor 如何处理其默认构建过程对于有效定制至关重要。以下，我们将分解 Capacitor CLI 的构建过程及其关键配置文件。
标准构建步骤
Capacitor 使用逐步过程将您的 web 应用程序转换为平台特定的构建。以下是默认构建过程的描述：
| 阶段 | 描述 | 输出 |
|---|---|---|
| Web Build | 使用框架工具编译 web 资产 | 优化的 web 包 |
| 复制资产 | 将 web 资产移动到本机平台文件夹 | 平台特定的资产目录 |
| 本机构建 | 运行平台特定的构建命令 | 可部署的二进制文件 |
| 验证 | 检查构建完整性和依赖项 | 构建状态和警告 |
主配置文件
Two key configuration files shape how Capacitor handles your builds:
capacitor.config.json
This is the core configuration file for your Capacitor project. It sets important parameters for your builds:
{
"appId": "com.example.app",
"appName": "MyApp",
"webDir": "dist",
"bundledWebRuntime": false,
"plugins": {
"SplashScreen": {
"launchShowDuration": 3000
}
}
}appId:应用程序的唯一标识符。appName:应用程序的名称。webDir: Specifies where Capacitor should look for the web assets (e.g.,dist).plugins:允许您配置插件特定的设置，例如SplashScreen选项。
package.json
该文件包含构建脚本和依赖项，影响构建过程:
{
"scripts": {
"build": "npm run build:web && cap sync",
"build:web": "vite build",
"cap:build": "cap build"
}
}- :
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 的分发选项。
Creating NPM Scripts
To streamline your workflow, add custom NPM scripts to your 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 应用。
您可以通过添加构建钩子来进一步自动化。
构建钩子设置
For more advanced control, use build hooks to execute custom code at specific points during the build process. Here’s an example setup in 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 |
|---|---|---|
| 调试符号 | ProGuard 映射文件 | dSYM 文件 |
| 构建变体 | debug, release, 测试环境 | debug, release |
| 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签名错误，请使用以下命令:
__CAPGO_KEEP_0__
npx cap build android --keystorePassword=$KEYSTORE_PASSWORD --keystoreAlias=$KEYSTORE_ALIASiOS 配置文件问题，请尝试以下方法：
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 Actions | __CAPGO_KEEP_0__ 动作 | 自动化构建，部署触发器 |
| 持续部署 | GitLab CI | 管道自动化，版本控制 |
| 流程化工作流程 | 自定义工作流程，构建钩子 | 适合企业级 |
设置自动构建通常需要约 $300/月,远低于传统解决方案的 $6,000/年.
安全标准
Capgo
- 优先考虑安全性，包括
- 更新包的端到端加密。
- 安全密钥管理。
遵守苹果和谷歌的指南。
- 即刻回滚选项。
- 部署版本跟踪。
- 管理发布频道以实现分阶段发布。
此安全框架经过了对数百个企业应用程序的严格测试。对于需要额外安全性的团队，Capgo还提供了自主托管的解决方案，具有可自定义的配置。
Capgo的频道系统使更新分发更加灵活。开发人员可以针对特定用户组使用不同的版本，适合beta测试或逐步发布。
概要。
构建步骤概览。
自定义构建脚本允许通过利用构建钩子、环境变量和平台特定命令来实现自动化和一致的部署。这些过程为通过Capgo实现的部署改进奠定了坚实的基础。
Capgo优势。
Capgo简化了部署，成功部署了超过2.35亿次更新，涵盖了750个生产应用程序。 [1]。其部分更新系统减少了带宽使用量和部署时间。
该平台提供快速更新、全球性能优化、端到端加密以实现安全性，以及灵活的基于频道的分发系统。这一设置支持目标更新、beta测试和遵守应用商店指南，同时保持强大的安全框架。
继续阅读《如何自定义Capacitor CLI》
如果您正在使用 《如何自定义Capacitor CLI》 来规划CI/CD自动化，连接它与 Capgo CI/CD 为Capgo CI/CD中的产品工作流 Capgo 原生构建 为Capgo 原生构建中的产品工作流 Capgo 集成 为Capgo 集成中的产品工作流 __CAPGO_KEEP_0__ 集成 CI/CD集成 GitHub Actions Integration 为 GitHub Actions Integration 的实现细节。
