如何使用 Capacitor CLI 自定义 build 脚本

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

加速更新：即时推送更改，无需等待应用商店审核。
控制部署：回滚更新或针对特定用户组发布。
保护你的应用：使用加密保护更新。
优化构建：针对特定平台需求调整设置。

核心功能概览：

配置文件：使用 capacitor.config.json 以及 package.json 用于管理构建设置。
自定义脚本：添加 prebuild 和 postbuild 任务实现自动化。
构建钩子: 在构建流程的特定阶段运行 code。
环境变量: 简化针对特定环境的构建，使用 .env 文件。

Capgo，作为部署工具，通过以下功能增强这一流程：自动更新、版本追踪以及全局性能优化。继续阅读，了解如何设置和自定义构建脚本，以获得最高效率。

全新推出 Capacitor 配置

Capacitor 框架文档网站

Capacitor 中的默认构建流程

要想有效定制构建流程，理解 Capacitor 如何处理其默认构建过程至关重要。下面我们将拆解 Capacitor CLI 的构建流程及其关键配置文件。

标准构建步骤

Capacitor 采用分步流程，将你的 Web 应用转换为特定平台的构建产物。以下是默认构建过程中发生的情况：

阶段	描述	输出
Web 构建	使用框架工具编译 Web 资源	优化后的 Web bundle
复制资源	将 Web 资源移动到原生平台目录	平台专属资源目录
Native 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：配置开发服务器，包括 hostname 和导航权限。
android/ios：支持平台特定的构建设置，例如 Android 的 keystore 信息或 iOS 的 provisioning 选项。

创建 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 应用的平台特定命令。

通过添加 build hooks，你可以实现更高程度的自动化。

Build Hooks 设置

若需更高级的控制，可以使用 build hooks 在构建过程中的特定节点执行自定义 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;

通过 build hooks，你可以：

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

这种方法让你对整个 build 生命周期拥有更大的灵活性和控制权。

高级构建定制

在大型项目中，微调 build 流程往往能带来显著差异。以下是如何有效处理特定环境的 build 和平台定制。

环境变量

通过为每个环境创建单独的 .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 签名	Keystore 管理	Provisioning Profile
资源管理	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"
  }
}

测试的更多技巧：

使用 Docker 使用容器隔离构建。
在启动流程前验证配置文件。
使用多个 Node.js 版本进行测试。
确认已满足各平台特定要求。
留意构建性能，寻找优化空间。

Capgo 构建功能

Capgo Live Update Dashboard 界面

Capgo 通过自动化部署将构建脚本提升到新高度，从而提高效率并简化流程。

快速应用更新

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

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

该平台采用增量更新，仅下载变更部分。这种方式降低了带宽消耗并加快了更新速度。此外，整个构建流程完全自动化，节省时间和精力。

构建自动化

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

CI/CD 平台	集成特性	优势
GitHub 操作	自动化构建、部署触发	持续部署
GitLab CI	流水线自动化、版本控制	精简工作流
Jenkins	自定义工作流、构建钩子	企业级扩展性

搭建自动化构建通常花费约 $300/月，相比传统方案动辄高达的价格，这要实惠得多 每年 $6,000.

安全标准

Capgo 以强大的框架优先保障安全，包括：

更新包的端到端加密。
密钥安全管理。
符合 Apple 和 Google 的指南规范。

版本控制功能

即时回滚选项。
部署版本追踪。
分阶段发布的更新通道管理。

该安全框架已在数百个企业应用中经过严格测试。对于需要额外安全性的团队，Capgo 还提供可自定义配置的自托管方案。

Capgo 的 Channel 系统让更新分发更灵活。开发者可以针对特定用户群推送不同版本，非常适合 Beta 测试或渐进式发布。

总结

构建步骤概览

通过 build hooks、环境变量和平台专属命令，自定义构建脚本可以实现自动化且一致的部署。这些流程为借助 Capgo 实现的部署优化打下了坚实基础。

Capgo 的优势

Capgo 简化了部署流程，已成功为 750 个生产环境 App 交付超过 2350 万次更新 [1]。其增量更新系统同时降低了带宽消耗和部署时间。

该平台提供快速更新、全球性能优化、端到端加密，以及灵活的 Channel 分发系统。这套方案支持定向更新、Beta 测试，并符合应用商店指南，同时保持强大的安全框架。

继续阅读：如何使用 Capacitor 自定义构建脚本 CLI

如果你正在使用 如何使用 Capacitor CLI 自定义 build 脚本 规划 CI/CD 自动化，并将其与 Capgo CI/CD 集成用于 Capgo CI/CD 中的产品工作流， Capgo Native Build 用于 Capgo Native Builds 中的产品工作流， Capgo 集成用于 Capgo 集成中的产品工作流， CI/CD 集成了解 CI/CD 集成的实现细节，以及 GitHub Actions 集成有关 GitHub Actions 集成的实现细节。