capacitor-ci-cd

Capacitor 应用的 CI/CD

使用适用于当前 Capacitor 主版本的工具链，在 CI 中构建、签名和发布 Capacitor 应用。

适用场景

在以下情况下触发：

• 创建或修复 .github/workflows/*.yml、.gitlab-ci.yml、fastlane/Fastfile 或 Capgo Cloud Build 作业。
• 为 Capacitor 8 或 9 选择运行器镜像、Node/Xcode/JDK 版本。
• 自动执行签名、上传到 TestFlight/Play、版本升级或 Capgo OTA 上传。
• CI 构建失败，但本地构建正常。

以下情况不适用：

• 手动提交、应用商店页面、截图 -> capacitor-app-store。
• Capgo Cloud Build 凭据设置与故障排查 -> capgo-native-builds。
• 渠道推广、分阶段 OTA 发布 -> capgo-release-workflows。
• 编写单元测试/E2E 测试 -> capacitor-testing。
• 安全扫描规则 -> capacitor-security。

实时项目快照

Capacitor 版本、Node 引擎和脚本： !node -e "const fs=require('fs');if(!fs.existsSync('package.json'))process.exit(0);const pkg=JSON.parse(fs.readFileSync('package.json','utf8'));const out=[];if(pkg.engines)out.push('engines='+JSON.stringify(pkg.engines));if(pkg.packageManager)out.push('packageManager='+pkg.packageManager);for(const section of ['dependencies','devDependencies']){for(const [name,version] of Object.entries(pkg[section]||{})){if(name.startsWith('@capacitor/')||name==='@capgo/cli'||name==='@capgo/capacitor-updater')out.push(section+'.'+name+'='+version)}}for(const [name,cmd] of Object.entries(pkg.scripts||{})){if(/build|test|lint|sync|release/i.test(name))out.push('scripts.'+name+'='+cmd)}console.log(out.join('\n'))"

现有 CI、锁文件和原生构建文件： !find . -maxdepth 4 -not -path '*/node_modules/*' \( -path './.github/workflows/*' -o -name '.gitlab-ci.yml' -o -name 'Fastfile' -o -name 'Appfile' -o -name 'Matchfile' -o -name 'ExportOptions.plist' -o -name 'Podfile' -o -name 'Package.swift' -o -name 'gradle-wrapper.properties' -o -name 'variables.gradle' -o -name '.nvmrc' -o -name '.node-version' -o -name 'bun.lock' -o -name 'package-lock.json' -o -name 'pnpm-lock.yaml' -o -name 'yarn.lock' \)

工具链矩阵

	Capacitor 8.x（稳定版，latest）	Capacitor 9（next，尚未正式发布）
Node	22+	24+（附带 npm 11）
Xcode	26+（采用 UIScene 后，8.5+ 可使用 27）	27+
GitHub macOS 运行器	macos-26（默认 Xcode 26.x）	xcode-27 镜像（撰写本文时为预览版），或列有 Xcode 27 的 macos-* 镜像；请查看 actions/runner-images
iOS 部署目标	15.0	16.0
JDK	21	21（AGP 9 本身需要 17+，Capacitor 的 Android 库使用 Java 21 编译）
Gradle / AGP	8.14.3 / 8.13	9.5.1 / 9.2.1
compile/target SDK	36	37

应用商店方面的截止要求：Apple 目前要求使用 iOS 26 SDK，并将从 2027 年 4 月起要求使用 iOS 27 SDK；Google Play 自 2026 年 8 月 31 日起要求 target API 36。使用 macos-26 的 Capacitor 8 应用目前满足这两项要求。

安装了多个 Xcode 版本时，请明确指定：sudo xcode-select -s /Applications/Xcode_<version>.app（运行器镜像 README 中列有确切的文件夹名称）。

选择流水线方案

不确定时，询问用户：

1. Capgo Cloud Build - 无需 macOS 运行器或本地签名配置；任何 Linux 运行器都可以调用 npx @capgo/cli@latest build request <appId> --platform ios|android。凭据只需保存一次：使用 npx @capgo/cli@latest build credentials save ...（或使用 build init 引导完成 iOS 配置），并在 CI 中通过环境变量传入。详情请加载 capgo-native-builds。
2. 自托管 GitHub Actions / GitLab - 完全自主控制；由你管理 macOS 运行器、证书和密钥库。请参阅 references/github-actions.md、references/gitlab-ci.md。
3. 在上述任一方案中使用 Fastlane - 如果已经在使用 match/pilot/supply，这是最佳选择。请参阅 references/fastlane.md。

原生版本发布后的纯 Web 更改可以完全跳过原生构建：上传 Capgo bundle（npx @capgo/cli@latest bundle upload --channel <channel>，通过 CAPGO_TOKEN 进行身份验证）。原生更改（插件、权限、Capacitor 升级）始终需要原生构建。

流程

1. 查看项目快照：Capacitor 主版本、包管理器和锁文件、iOS 依赖管理器（Package.swift -> SPM，Podfile -> CocoaPods）、现有工作流。
2. 根据版本矩阵选择工具链版本。如果存在 .nvmrc/engines，则据此设置 Node 版本。
3. 组织作业：test（lint、类型检查、单元测试）-> build-web（产物 <webDir>）-> 并行运行 ios + android -> 由分支/标签控制的部署作业。恢复 Web 产物后，始终在原生作业中运行 npx cap sync <platform>；绝不要为了 CI 省事而提交同步后的资源。
4. 签名：遵循 references/signing-and-secrets.md。优先使用 App Store Connect API 密钥，而不是 Apple ID 密码；将 Android 密钥库和密码保存在机密中，在运行时解码，并在之后删除。
5. 构建号：从 CI 获取（GITHUB_RUN_NUMBER、CI_PIPELINE_IID），或让 Capgo Cloud Build 自动递增。绝不重复使用构建号。
6. 添加缓存（references/caching-and-versioning.md）。
7. 先在分支上运行流水线，仅上传到 TestFlight 内部测试 / Play 内部测试轨道。

验证

• 工作流在干净的运行器上连续通过两次（缓存冷启动和热启动）。
• 日志显示预期的工具版本：添加 node -v、xcodebuild -version、java -version、./gradlew --version 步骤。
• iOS 产物：unzip -l App.ipa | grep Payload/App.app，并且构建以预期的构建号显示在 TestFlight 中。
• Android 产物：bundletool dump manifest --bundle app-release.aab | grep -E "versionCode|targetSdkVersion" 与预期一致；构建显示在 Play 内部测试轨道中。
• Capgo：npx @capgo/cli@latest bundle list 显示已上传到目标频道的版本。
• 日志中没有打印任何机密值（GitHub 会屏蔽已注册的机密；绝不要 echo 解码后的文件）。

错误处理

CI 日志中的错误	修复方法
error ... The engine "node" is incompatible with this module. Expected version ">=22.0.0"（或 >=24）	将 actions/setup-node 的 node-version 提高到与 Capacitor 主版本匹配的版本
Could not find the web assets directory: ./dist.	未将 Web 构建产物下载到 webDir，或跳过了构建；修正构建产物路径
No signing certificate "iOS Distribution" found	证书未导入当前活动钥匙串，或团队不正确；参见签名参考文档
"App" requires a provisioning profile. Select a provisioning profile in the Signing & Capabilities editor.	安装配置描述文件，或搭配 API 密钥认证标志使用 -allowProvisioningUpdates
error: exportArchive: No profiles for 'com.x.y' were found	配置描述文件类型与 ExportOptions.plist 中的 method（app-store-connect）不匹配
xcodebuild: error: SDK "iphoneos27.0" cannot be located / Swift 6 中 @UIApplicationMain 报错	选错了 Xcode；用 xcode-select 选择所需版本；将 @UIApplicationMain 替换为 @main
Unsupported class file major version 65 / Android Gradle plugin requires Java 17 to run / invalid source release: 21	使用 actions/setup-java 安装 JDK 21（distribution: temurin，java-version: '21'）
升级到 Capacitor 9 后，Plugin [id: 'org.jetbrains.kotlin.android'] ... 出现冲突	AGP 9 已内置 Kotlin；根据 capacitor-app-upgrades 移除 kotlin-android 插件
SDK location not found. Define a valid SDK location with an ANDROID_HOME	使用包含 Android SDK 的镜像（ubuntu-latest 已包含），或使用 android-actions/setup-android
Play API：APK specifies a version code that has already been used.	根据 CI 运行编号生成 versionCode
Capgo：Cannot find API key in local folder or global, please login first	在该步骤的 env 中从密钥导出 CAPGO_TOKEN（或传入 -a）
Capgo：Cannot auth user with apikey	密钥已撤销或没有上传权限；在 Capgo 控制面板中创建新密钥
npm error 404 Not Found - GET https://registry.npmjs.org/capsec	安全扫描器包名为 @capgo/capgo-sec：npx @capgo/capgo-sec@latest scan --ci

参考资料

• references/github-actions.md - 完整工作流：测试、Web 构建、iOS（SPM/CocoaPods）、Android、Capgo OTA、Capgo Cloud Build 作业。
• references/gitlab-ci.md - 使用 macOS runner 标签的 GitLab 流水线。
• references/fastlane.md - 使用 API 密钥和 match 的 iOS 与 Android lanes。
• references/signing-and-secrets.md - 证书/配置描述文件导入、API 密钥认证、Android keystore 配置、密钥清单。
• references/caching-and-versioning.md - npm/Gradle/SPM/CocoaPods 缓存、构建编号、semantic-release。