How to Customize Build Scripts with Capacitor CLI

Capacitor CLI 允许您定制 iOS、Android 和 Web 平台的应用构建过程。通过调整构建脚本，您可以：

加速更新: 立即推送更改，无需等待应用商店延迟。
控制部署: 回滚更新或针对特定用户组。
保护您的应用使用加密保护更新。
优化构建: 根据平台需求调整设置。

快速概览功能特点:

配置文件: 使用 capacitor.config.json 和 package.json 管理构建设置。
自定义脚本: 为自动化添加预构建和后构建任务。
构建钩子: 在构建过程特定阶段运行code。
环境变量: 简化环境特定构建 .env 文件。

CapgoCapacitor CLI 文件。__CAPGO_KEEP_0__

Capacitor CLI Capacitor 文件。

Capacitor Framework Documentation Website

Default Build Process in Capacitor

了解如何 Capacitor 处理其默认构建过程至关重要，如果您想自定义它，必须了解。以下，我们将分解 Capacitor CLI 的构建过程及其关键配置文件。

标准构建步骤

Capacitor 使用逐步过程将您的 Web 应用程序转换为平台特定的构建。以下是默认构建过程的描述：

Phase	Description	Output
Web 构建	编译 Web 资产使用您的框架工具	优化 Web 包
复制资源	将 Web 资产移动到本机平台文件夹中	平台特定资产目录
原生构建	构建原生应用	运行平台特定构建命令
可部署二进制文件	验证	检查构建完整性和依赖

构建状态和警告

两种关键配置文件决定了Capacitor如何处理你的构建。

两个关键配置文件决定了如何处理capacitor的构建:
Capacitor.config.json

{
  "appId": "com.example.app",
  "appName": "MyApp",
  "webDir": "dist",
  "bundledWebRuntime": false,
  "plugins": {
    "SplashScreen": {
      "launchShowDuration": 3000
    }
  }
}

appId这是您的__CAPGO_KEEP_0__项目的核心配置文件。它设置了构建的重要参数：
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脚本

To streamline your workflow, add custom NPM scripts to your package.json 文件中添加自定义__CAPGO_KEEP_0__脚本。以下是一个示例：

{
  "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
    }
  }
};

功能

Live Update	Android	iOS
调试符号	ProGuard 映射文件	dSYM 文件
构建变体	debug, 发布, 测试环境	debug, 发行版
Code 签名	密钥管理	分发配置文件
资源管理	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_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"
  }
}

测试时的额外提示:

使用 docker 容器来隔离构建。
在开始过程之前，验证配置文件。
测试多个 Node.js 版本。
确认满足平台特定要求。
关注构建性能以进行改进。

Capgo 构建功能

Capgo Live Update 控制台界面

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 简化了部署，已成功在 750 个生产应用中推送超过 2,350 万次更新 [1]。其部分更新系统减少了带宽使用量和部署时间。

该平台提供快速更新、全球性能优化、端到端加密以确保安全性，以及灵活的基于通道的分发系统。这一设置支持目标更新、beta 测试以及遵守应用商店指南，同时保持强大的安全框架。

Keep going from 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 动作集成的实现细节

如何自定义 Capacitor CLI 构建脚本