如何自定义Capacitor中的构建脚本CLI

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

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

快速概览：关键功能

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

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

介绍 Capacitor 配置

Capacitor 框架文档网站

默认构建过程在 Capacitor

了解 Capacitor 如何处理其默认构建过程对于有效定制至关重要。以下，我们将分解 Capacitor CLI 的构建过程及其关键配置文件。

标准构建步骤

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

阶段	描述	输出
Web Build	使用您的框架工具编译 web 资产	优化的 web 包
复制资产	将 web 资产移动到本机平台文件夹	平台特定的资产目录
本机 Build	运行平台特定的构建命令	可部署的二进制文件
验证	检查构建完整性和依赖项	构建状态和警告

主配置文件

两个关键配置文件决定了如何处理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 以确保你的原生项目得到更新。

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

修改构建脚本

你可以调整 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: 构建 Android 或 iOS 应用的平台特定命令。
build:platform您可以通过添加构建钩子来进一步自动化。构建钩子设置

为了获得更高级别的控制，使用构建钩子来执行自定义__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;

构建钩子

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

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

高级构建定制

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

环境变量

通过为每个环境创建单独的文件来设置环境变量： .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, staging	debug, release
Code Signing	__CAPGO_KEEP_0__ Signing	__CAPGO_KEEP_0__ 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"
  }
}

测试时的额外提示：

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

Capgo Build Features

Capgo 实时更新控制台界面

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

快速应用程序更新

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

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

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

自动构建

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

CI/CD 平台	集成功能	好处
GitHub 动作	自动构建、部署触发	持续部署
GitLab CI	管道自动化、版本控制	流程化工作流
Jenkins	自定义工作流程, 构建钩子	企业级可扩展

通常情况下, 设置自动构建的成本约为 $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测试和遵守应用商店指南，同时保持强大的安全框架。

继续使用如何自定义构建脚本的Capacitor CLI

如果您正在使用 如何自定义构建脚本的Capacitor CLI 来规划CI/CD自动化，连接它与 Capgo CI/CD 在Capgo CI/CD中， Capgo 原生构建在Capgo 原生构建中， Capgo 集成在Capgo 集成中， CI/CD集成在CI/CD集成的实现细节中， GitHub Actions 集成为 GitHub Actions 集成的实现细节。

如何自定义构建脚本：Capacitor CLI