Skip CLI 参考

Skip 命令行界面（CLI）是一个可以在 macOS、Linux 或 Windows 终端中运行的工具。它提供了创建新 Skip 项目（框架和应用项目）、为 Android 构建和测试、管理 Swift Android SDK 和模拟器，以及导出构建产物用于发布的功能。

安装

skip CLI 通过 Homebrew ↗ 安装。Skip 以二进制 Homebrew “Cask” 的形式分发，支持 macOS、Linux 和 Windows（通过 WSL 2 ↗）。完整详情请参阅入门指南。

Homebrew 设置完成后，可以通过运行以下终端命令来安装（和更新）Skip：

brew install skip

这将下载并安装 skip 工具本身，以及构建和测试应用的 Kotlin/Android 部分所需的 Android SDK 依赖项。

升级到最新版本：

skip upgrade

命令概览

USAGE: skip <subcommand>

SUBCOMMANDS:
  version                 Print the skip version
  doctor                  Evaluate and diagnose Skip development environment
  checkup                 Run tests to ensure Skip is in working order
  upgrade                 Upgrade to the latest Skip version
  create                  Create a new Skip project interactively
  init                    Initialize a new Skip project
  verify                  Verify Skip project
  icon                    Create and manage app icons
  app                     Build, run, and manage Skip apps
  android                 Build, run, and test Swift packages for Android
  export                  Export the Gradle project and built artifacts
  meta                    App metadata and SBOM tools
  devices                 List connected devices and emulators/simulators
  test                    Run parity tests and generate reports

运行 skip help <subcommand> 获取任何命令的详细帮助，或运行 skip <subcommand> --help 获取完整的标志列表。

通用标志

大多数命令共享一组通用选项组：

输出选项 控制结果的显示方式：

标志	描述
`-v, --verbose`	显示详细消息
`-q, --quiet`	抑制输出
`-J, --json`	以格式化的 JSON 输出
`-j, --json-compact`	以紧凑的 JSON 输出
`-M, --message-plain`	以纯文本显示消息
`--plain/--no-plain`	禁用颜色和进度动画
`--log-file <path>`	将日志输出写入文件

工具选项 覆盖外部工具的默认路径：

标志	描述
`--swift <path>`	Swift 命令路径
`--gradle <path>`	Gradle 命令路径
`--adb <path>`	ADB 命令路径
`--emulator <path>`	Android 模拟器路径
`--sdkmanager <path>`	Android SDK Manager 路径
`--avdmanager <path>`	Android AVD Manager 路径
`--java-home <path>`	JAVA_HOME 路径

项目命令

skip create

通过交互式提示创建新的 Skip 项目。它会要求你选择原生（Fuse）或转译（Lite）项目、应用或库，并引导你完成配置选项。

skip create

对于非交互式项目创建，请使用 skip init。

skip init

使用单个命令初始化新的 Skip 项目。这是 skip create 的非交互式替代方案。

# 创建原生 (Fuse) 应用项目
skip init --native-app --appid=com.example.myapp my-app MyApp

# 创建转译 (Lite) 应用项目
skip init --transpiled-app --appid=com.example.myapp my-app MyApp

# 创建原生库项目
skip init --native-model my-lib MyModule

# 创建转译库项目
skip init --transpiled-model my-lib MyModule

# 创建包含多个模块的应用
skip init --native-app --appid=com.example.myapp my-app MyApp DataModel

主要标志：

标志	描述
`--native-app`	创建 Skip Fuse（原生编译）应用
`--transpiled-app`	创建 Skip Lite（转译）应用
`--native-model`	创建原生库模块
`--transpiled-model`	创建转译库模块
`--appid <bundleID>`	应用项目的 Bundle 标识符
`--open-xcode`	创建后在 Xcode 中打开项目
`--icon <path>`	图标图片路径（SVG、PDF 或 PNG）
`-c, --configuration <c>`	构建配置：`debug` 或 `release`

skip verify

验证 Skip 项目的结构和配置。检查 Package.swift 布局、skip.yml 文件和模块依赖项。

# 验证当前项目
skip verify

# 验证指定项目
skip verify --project path/to/project

# 尝试自动修复问题
skip verify --fix

skip icon

为 iOS 和 Android 创建和管理应用图标。从单个输入图片生成所有必需的尺寸。

# 为所有必需的图标尺寸调整 PNG 大小
skip icon app_icon.png

# 使用彩色背景和 SVG 叠加生成图标
skip icon --background #5C6BC0-#3B3F54 symbol.svg

# 预览生成的图标
skip icon --open-preview --random-icon --random-background

主要标志：

标志	描述
`--background <color>`	背景颜色或渐变（例如 `skyblue` 或 `#3E8E41-#2F4F4F`）
`--inset <decimal>`	图片周围的内缩量
`--shadow <decimal>`	图标周围的阴影半径
`--android <path>`	Android 的单独图标文件
`--darwin <path>`	iOS/macOS 的单独图标文件

skip export

构建并导出 Skip 模块为可分发的产物。库导出为 .aar 文件，应用导出为 .apk/.aab 文件。

# 导出调试归档
skip export --debug

# 导出指定模块
skip export --module ModuleName

# 导出到自定义输出文件夹
skip export --dir output/

skip app launch

一步构建并在已启动的 iOS 模拟器和运行中的 Android 模拟器上启动传统 Skip 应用。从 Skip.env 读取 PRODUCT_NAME 和 PRODUCT_BUNDLE_IDENTIFIER，然后驱动 xcodebuild、xcrun simctl install 和 xcrun simctl launch 用于 iOS，同时让 Skip 构建插件处理 Android Gradle 构建并通过 adb 安装。

# 在 iOS 模拟器和 Android 模拟器上构建并启动（默认）
skip app launch

# 构建并启动 release 版本
skip app launch --configuration release

# 仅在已启动的模拟器上构建并启动 iOS 应用
skip app launch --ios

# 仅通过 Skip 插件构建并启动 Android 应用
skip app launch --android

前置条件：

项目必须是传统 Skip 应用项目，即包含 Project.xcworkspace、Skip.env 配置文件，以及 Package.swift 旁边的 Darwin/ 和 Android/ 文件夹。skip init --transpiled-app 和 skip init --native-app 会生成这种格式的项目。
你需要自行启动 iOS 模拟器（xcrun simctl boot <UDID>；open -a Simulator）并启动 Android 模拟器（emulator -avd <name> 或 skip android emulator launch）。skip app launch 不会为你启动其中任何一个。如果没有模拟器启动，iOS 安装步骤会失败；如果没有模拟器运行，Android 安装步骤会失败。

标志	用途
`-c, --configuration <config>`	构建配置，`debug`（默认）或 `release`。
`--ios`	仅构建并启动 iOS 应用。在 xcodebuild 环境中设置 `SKIP_ACTION=none`，使构建插件跳过 Android 阶段。
`--android`	仅构建并启动 Android 应用。iOS 会被构建但不会安装或启动。
`--project <dir>`	项目文件夹。默认为当前目录。

当你同时拥有 USB 连接的 Android 设备和运行中的模拟器时，使用标准的 ANDROID_SERIAL 环境变量将安装范围限定到模拟器：

ANDROID_SERIAL=emulator-5554 skip app launch

skip app launch 没有 --android-serial 标志；环境变量是定位特定 Android 设备的标准方式。

元数据命令

skip meta 子命令为 Skip 应用生成元数据目录和软件物料清单（SBOM）文档。

skip meta index

生成一个结构化 JSON 目录，包含 Skip 应用的所有面向用户的元数据。目录合并了：

来自 Darwin/fastlane/metadata/（App Store）和 Android/fastlane/metadata/android/（Google Play）的本地化标题、副标题、描述、关键词和发布说明。
来自 Darwin/Info.plist 和 Darwin/InfoPlist.xcstrings 的 iOS 应用权限及其本地化描述。
来自 Android/app/src/main/AndroidManifest.xml 的 Android 权限和清单元数据。
来自 Skip.env 的版本号、构建号、Bundle ID 和商店 ID。
来自两个平台树的图标和手机截图。
来自 .git/config 和项目 LICENSE 文件的源代码仓库 URL 和许可证。

# 将目录 JSON 打印到标准输出
skip meta index

# 将目录写入文件
skip meta index -O appindex.json

# 在输出中包含两个平台的 SBOM
skip meta index --sbom -O appindex.json

标志	用途
`-O, --catalog-output <path>`	将目录 JSON 写入指定文件而非标准输出。
`--sbom`	在目录中包含两个平台的软件物料清单。
`--project <dir>`	项目文件夹。默认为当前目录。

输出使用 BCP 47 规范语言环境代码（zh-Hans、pt、fr），无论源目录使用了哪种 fastlane 约定（zh-CN 与 zh-Hans、pt-PT 与 pt、fr-FR 与 fr）。两个平台中出现的具有相同内容的共享元数据字段会被提升到顶级 app 字典中；每个平台的覆盖项保留在 platforms.ios / platforms.android 下。

在提交到 App Store Connect 或 Google Play 之前使用 skip meta index，以确认元数据可以正确组装，没有平台缺少必需字段，并且两个商店都存在本地化资源。

环境命令

skip doctor

检查 Skip 开发的系统配置和先决条件。验证 Xcode、Android Studio、JDK、Gradle 和 SDK 版本。

# 运行基本环境检查
skip doctor

# 包含原生 Swift-on-Android 支持的检查
skip doctor --native

这是 skip checkup 的子集（后者还会创建和构建示例项目）。

skip checkup

通过运行 skip doctor 的所有检查，然后创建和构建示例 Skip 项目来验证一切正常，执行完整的系统评估。

# 完整系统检查
skip checkup

# 包含原生应用支持检查
skip checkup --native

skip upgrade

检查并安装 Skip 工具链的最新版本。

skip upgrade

skip devices

列出所有已连接的 Android 模拟器/设备（通过 adb）和 iOS 模拟器/设备（通过 simctl 和 devicectl）。用于在运行或测试前验证哪些目标可用。

skip devices

输出包括设备 ID、平台、类型和型号信息，以 JSON 格式呈现。

测试命令

skip test

构建并运行 Swift（XCTest）和转译的 Kotlin（JUnit）测试，然后生成并排对比报告。默认情况下，Kotlin 测试通过 Robolectric 在本地运行。使用 --android-serial 在连接的设备或模拟器上运行仪器化测试。

# 在本地运行对比测试（Robolectric）
skip test

# 为指定项目运行测试
skip test --project path/to/project

# 在连接的设备上运行仪器化测试
skip test --android-serial auto

# 定位特定模拟器
skip test --android-serial emulator-5554

主要标志：

标志	描述
`--project <dir>`	项目文件夹（默认：`.`）
`--test/--no-test`	运行测试（默认：`--test`）
`--android-serial <serial>`	仪器化测试的目标设备（省略则使用 Robolectric）
`--xunit <path>`	XUnit 测试报告路径
`--junit <path>`	JUnit 测试报告文件夹路径
`-c, --configuration <c>`	构建配置（默认：`debug`）

Android 命令

skip android 命令组提供了使用 Swift Android SDK 交叉编译 Swift 包、在 Android 设备或模拟器上运行可执行文件和测试，以及管理 SDK、工具链和模拟器镜像的工具。

USAGE: skip android <subcommand>

SUBCOMMANDS:
  build                   Build the native project for Android
  run                     Run the executable target on an Android device or emulator
  test                    Test the native project on an Android device or emulator
  home                    Install and manage the Android SDK in ANDROID_HOME
  sdk                     Manage installation of Swift Android SDK
  emulator                Manage Android emulators
  toolchain               Manage installation of Swift Android Host Toolchain

skip android build

使用已安装的 Swift Android SDK 交叉编译 Swift 包。

# 为 Android 构建（debug）
skip android build

# 为 release 构建
skip android build --configuration release

# 构建并归档输出到文件夹
skip android build --dir output/

# 为特定架构构建
skip android build --arch aarch64

额外的 swift build 标志可以作为尾部参数传递。

skip android run

为 Android 构建 Swift 包，将可执行文件和共享库依赖推送到连接的设备或模拟器，然后运行。

# 运行默认可执行文件
skip android run

# 使用参数运行特定可执行文件
skip android run MyExecutable -- --flag value

# 定位特定模拟器
skip android run --android-serial emulator-5554

主要标志：

标志	描述
`--android-serial <serial>`	目标设备（默认：`auto`）
`--cleanup/--no-cleanup`	运行后清理临时文件（默认：`--cleanup`）
`--remote-folder <path>`	设备上的自定义暂存文件夹
`--env <key=value>`	远程执行的环境变量
`--copy <path>`	推送到设备的额外文件

skip android test

为 Android 构建 Swift 测试，推送到设备或模拟器并执行。默认情况下，测试作为原生可执行文件通过 adb shell 运行。使用 --apk 时，测试被打包为 Android APK 并通过仪器化运行。

# 在连接的设备上运行测试
skip android test

# 以 APK 运行测试（仪器化测试）
skip android test --apk

# 定位特定模拟器
skip android test --android-serial emulator-5554

# 仅运行 Swift Testing 测试
skip android test --testing-library testing

# 仅运行 XCTest 测试
skip android test --testing-library xctest

主要标志：

标志	描述
`--android-serial <serial>`	目标设备（默认：`auto`）
`--android-connect-timeout <seconds>`	安装前等待设备启动的时间（默认：`5`）
`--apk/--no-apk`	将测试打包为 APK 用于仪器化测试
`--testing-library <lib>`	测试库：`all`、`xctest` 或 `testing`（默认：`all`）
`--event-stream-output-path <path>`	将 JSON 测试事件流写入文件
`--cleanup/--no-cleanup`	测试后清理（默认：`--cleanup`）

工具链选项

build、run 和 test 子命令共享以下工具链选项来控制交叉编译：

标志	描述
`--swift-version <v>`	要使用的 Swift 版本
`--sdk <path>`	Swift Android SDK 路径
`--ndk <path>`	Android NDK 路径
`--toolchain <path>`	Swift 工具链路径
`--package-path <path>`	Swift 包路径
`-c, --configuration <c>`	构建配置：`debug` 或 `release`
`--arch <arch>`	目标架构：`automatic`、`current`、`all`、`aarch64`、`armv7`、`x86_64`
`--android-api-level <level>`	Android API 级别（默认：`28`）
`--bridge/--no-bridge`	启用 SKIP_BRIDGE 到 Kotlin 的桥接（默认：`--bridge`）
`-Xswiftc <flag>`	向 Swift 编译器传递标志
`-Xcc <flag>`	向 C 编译器传递标志
`-Xlinker <flag>`	向链接器传递标志

skip android sdk

管理 Android 的 Swift 交叉编译 SDK。SDK 是编译 Swift 代码以在 Android 上原生运行（Skip Fuse 模式）所必需的。

skip android sdk install

安装 Swift Android SDK。默认安装最新发布版本。

# 安装最新发布版
skip android sdk install

# 安装特定版本
skip android sdk install --version 6.3

# 安装最新每夜构建版
skip android sdk install --version nightly-main

skip android sdk list

列出已安装的 Swift Android SDK。

# 列出本地安装的 SDK
skip android sdk list

# 列出可用的远程 SDK
skip android sdk list --remote

skip android sdk uninstall

移除已安装的 Swift Android SDK。

# 卸载所有已安装的 SDK
skip android sdk uninstall

# 卸载特定版本
skip android sdk uninstall --version swift-6.3-RELEASE_android

skip android emulator

创建、列出和启动 Android 模拟器镜像（AVD）。模拟器用于在没有物理 Android 设备连接时的测试。

skip android emulator create

安装系统镜像并创建 Android 虚拟设备（AVD）。

# 创建默认模拟器（API 34）
skip android emulator create

# 创建自定义模拟器
skip android emulator create \
  --name pixel_7_api_36 \
  --device-profile pixel_7 \
  --android-api-level 36 \
  --system-image google_apis_playstore_ps16k

skip android emulator launch

启动 Android 模拟器。如果只安装了一个 AVD，则自动启动。否则使用默认模拟器名称，或者你可以使用 --name 指定。

# 启动默认模拟器
skip android emulator launch

# 启动特定模拟器
skip android emulator launch --name emulator-34-medium_phone

# 在后台启动（启动完成后返回）
skip android emulator launch --background

# 无头启动（无窗口，用于 CI）
skip android emulator launch --headless --background

主要标志：

标志	描述
`-n, --name <name>`	要启动的 AVD 名称
`--background/--no-background`	启动后将进程放入后台（默认：`--no-background`）
`--headless/--no-headless`	无窗口运行（默认：从 `CI` 环境变量自动检测）
`--logcat <filter>`	Logcat 过滤表达式（默认：`*:D`）
`--android-connect-timeout <seconds>`	等待启动的秒数（默认：`90`）

skip android emulator list

列出已安装的 Android 模拟器镜像（AVD）。

skip android emulator list

skip android home install

在你的 ANDROID_HOME 目录中设置基础 Android SDK。安装 cmdline-tools、platform-tools 和模拟器组件。

skip android home install

这通常只需要一次，或在全新系统设置后执行。大多数用户会让 Android Studio 处理 SDK 安装。

skip android toolchain version

显示已安装的 Swift Android Host Toolchain 版本。

skip android toolchain version

提示与故障排除

详细输出

在任何命令中添加 -v 或 --verbose 以查看详细输出，包括正在执行的确切 shell 命令。这对于诊断构建或配置问题非常有用。

skip android test --verbose

多个已连接设备

当多个 Android 设备或模拟器连接时，定位设备的命令会自动优先选择模拟器而非物理设备。要定位特定设备，请使用 --android-serial 标志：

# 列出已连接设备以查找序列号
skip devices

# 定位特定设备
skip android test --android-serial emulator-5554

你也可以设置 ANDROID_SERIAL 环境变量，所有命令都会遵守它。

CI/CD 使用

对于持续集成，典型的设置如下：

# 安装 Skip 和 Android SDK
brew install skip
skip android sdk install
skip android emulator create

# 在后台启动模拟器（无头，等待启动完成）
skip android emulator launch --background --headless

# 运行测试
skip android test

模拟器启动命令会等待设备完全启动后才返回，因此测试命令可以紧随其后立即运行。

获取帮助

每个命令都支持 --help 以获取可用标志的完整列表：

skip android test --help

如需更多帮助，请访问 Skip 论坛 ↗ 或加入我们的 Slack。