How to Customize Build Scripts with Capacitor CLI

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__CAPGO_KEEP_0__ ，一个部署工具，通过自动更新、版本跟踪和全球性能优化来增强此过程。继续阅读，了解如何设置和自定义您的构建脚本以实现最高效率。Capacitor CLI

介绍 Capacitor 配置

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 接下来，我们将探索如何修改这些设置以进一步定制您的构建。

修改构建脚本

您可以通过修改 __CAPGO_KEEP_0__ 的默认构建过程来更好地适应您的项目需求。以下是如何操作：

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

您可以通过编辑

文件来调整构建过程。以下是示例配置： 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
  }
}

: 指定您的编译好的 Web 资产所在位置。

webDir__CAPGO_KEEP_0__
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

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

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

功能	Android	iOS
调试符号	ProGuard 映射文件	dSYM 文件
构建变体	debug, release, 测试环境	debug, release
Code Signing	Keystore管理	分发配置文件
资源管理	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_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"
  }
}

Additional tips for testing:

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

Capgo 快速功能

Capgo 实时更新控制台界面

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

快速应用程序更新

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

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

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

自动化构建

Capgo 与主要的CI/CD平台Capgo无缝整合，提供多种集成:

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 集成中 CI/CD集成在CI/CD集成中 GitHub Actions Integration 为 GitHub Actions Integration 的实现细节。