How to Customize Build Scripts with Capacitor CLI

Capacitor CLI 可以让您自定义应用的构建过程，适用于 iOS、Android 和 web 平台。通过调整构建脚本，您可以：

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

快速概览：关键功能

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

Capgo, 一款部署工具，通过自动更新、版本跟踪和全局性能优化等功能，进一步优化了此过程。继续阅读以了解如何设置和自定义您的构建脚本以实现最高效率。 CapacitorCloudflare

介绍 Capacitor 配置

Capacitor 默认构建过程

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

标准构建步骤

Capacitor 使用逐步的过程将您的 web 应用程序转换为平台特定的构建。以下是默认构建过程的详细信息：

主配置文件

两个关键配置文件决定了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"
  }
}

• 的 webDir 设置 capacitor.config.json 告诉 Capacitor 在哪里找到你的编译好的 Web 资产，以便在原生构建中包含它们。
• 你对 capacitor.config.json进行了更改后， cap sync 你需要运行

以确保你的原生项目得到更新。

接下来，我们将探索如何修改这些设置来进一步定制你的构建。

You can tweak Capacitor’s default build process to better suit your project needs. Here’s how:

你可以调整 __CAPGO_KEEP_0__ 的默认构建过程以更好地适应你的项目需求。这里是如何做到的：

配置文件设置 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以下是你可以修改的关键设置：
• 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 应用程序。

您可以通过添加构建钩子来进一步自动化。构建钩子设置

为了获得更高级别的控制，使用构建钩子来执行自定义 __CAPGO_KEEP_0__ 在构建过程中的特定点。以下是一个示例设置在

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;

Build Hooks Setup

• 在构建开始之前验证需求
• 在过程中转换资产
• 在关键点触发通知
• 自动更新版本号
• 无缝运行自动化测试

这种方法为您提供了更大的灵活性和对整个构建生命周期的控制权。

高级构建定制

在处理更大的项目时，精细调整您的构建过程确实会带来很大差异。以下是如何有效地处理环境特定构建和平台定制的方法。

环境变量

通过为每个环境创建单独的文件来设置环境变量: .env 然后，配置您的构建脚本以根据环境加载适当的文件:

• .env.development
• .env.staging
• .env.production

Validate requirements before the build starts

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

这些配置允许您为每个平台定制构建，从而实现更平滑的部署。

优化构建的附加提示包括：

• 使用部分更新来节省部署时间
• 设置错误跟踪来快速识别问题
• 创建渠道系统来测试 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

修复后，请确保您的更改是稳定的，通过运行全面构建测试来验证。

测试构建脚本

一旦错误得到解决，使用以下步骤验证您的构建脚本：

• 自动验证: 运行关键命令以确认构建过程如预期工作。

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 Build Features

Capgo 将构建脚本推向了新的高度，通过自动部署，提高了效率并简化了流程。

快速应用更新

Capgo 的更新性能令人印象深刻：

• 95% 的活跃用户 在 24 小时内接收到更新。
• 82% 的成功率 全球更新分发率。
• 全球平均 API 响应时间为 434ms.

该平台使用部分更新，这意味着只下载更改。这一方法减少了带宽使用量并加快了更新过程。另外，整个构建过程都是完全自动化的，节省了时间和精力。

自动化构建

Capgo 与主要的 CI/CD 平台无缝集成，提供多种集成方案：

通常情况下，设置自动构建的成本约为 $300/月,远低于传统解决方案的 $6,000/年.

安全标准

Capgo 以安全性为首要考虑，提供了一个强大的框架，包括：

• 更新包的端到端加密。
• 安全密钥管理。
• 遵守苹果和谷歌的指南。

版本控制功能

• 立即回滚选项。
• 部署版本跟踪。
• 阶段发布的更新频道管理。

This security framework has been rigorously tested across hundreds of enterprise applications. For teams needing extra security, Capgo also offers self-hosted solutions with customizable configurations.

Capgo’s channel system makes update distribution flexible. Developers can target specific user groups with different versions, perfect for beta testing or gradual rollouts.

概要

构建步骤概览

Custom build scripts allow for automated and consistent deployments by leveraging build hooks, environment variables, and platform-specific commands. These processes create a solid foundation for deployment improvements made possible with Capgo.

Capgo Benefits

Capgo simplifies deployment, having successfully delivered over 23.5 million updates across 750 production apps [1]其部分更新系统减少了带宽使用量和部署时间。

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