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

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

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

快速概览：关键功能

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

Capgo,部署工具，自动更新,版本跟踪和全球性能优化。继续阅读以了解如何设置和自定义您的构建脚本以实现最大效率。

介绍 Capacitor 配置

Capacitor 框架文档网站

默认构建过程在 Capacitor 中

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

标准构建步骤

Capacitor 使用一步一步的过程将您的web应用程序转换为平台特定的构建。以下是默认构建过程中发生的事情：

阶段	描述	输出
Web构建	使用您的框架工具编译web资产	优化的web包
复制资产	将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"
  }
}

The webDir 设置 capacitor.config.json 告诉Capacitor在哪里查找您的编译后的web资源以在native构建中包含。
修改 capacitor.config.json后，您需要运行 cap sync 以确保您的native项目得到更新。

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

修改构建脚本

您可以通过修改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使用这些来设置环境或在构建完成时发送通知。
build:platform: 平台特定的命令，用于构建 Android 或 iOS 应用。

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

构建 Hooks 设置

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

功能

This approach gives you greater flexibility and control over the entire build lifecycle.__CAPGO_KEEP_0__.	安卓	iOS
调试符号	ProGuard 映射文件	dSYM 文件
构建变体	debug,发布,测试	debug,发布
Code 签名	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 签名错误，请使用以下命令:

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实时更新仪表板界面

Capgo将构建脚本带到下一个水平，通过自动部署，提高效率并简化流程。

快速应用程序更新

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

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

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

构建自动化

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

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

通常情况下，设置自动化构建的成本约为 $300 每月远低于传统解决方案的成本，后者可能高达 每年 6,000 美元.

安全标准

Capgo优先考虑安全性，采用强大的框架，包括：

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

版本控制功能

即时回滚选项。
部署版本跟踪。
更新通道管理，适用于分阶段发布。

此安全框架已在数百个企业应用程序中进行了严格的测试。对于需要额外安全性的团队，Capgo还提供自托管解决方案，具有可自定义的配置。

Capgo的通道系统使更新分发更加灵活。开发人员可以针对不同版本的特定用户组，适合测试或逐步发布。

简介

构建步骤概述

自定义构建脚本允许通过利用构建钩子、环境变量和平台特定命令来实现自动化和一致的部署。这些过程为通过 Capgo 实现的部署改进奠定了坚实的基础。

Capgo 优势

Capgo 简化了部署，成功部署了超过 2,350 万次更新，覆盖了 750 个生产应用 [1]其部分更新系统减少了带宽使用量和部署时间。

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

How to Customize Build Scripts with Capacitor CLI