Windows IOS Cicd

Windows → iOS/watchOS 构建与模拟器验证标准（Build & Verify iOS/watchOS from Windows）

核心结论：Windows 上无法本地编译 iOS 代码，但可以完成 100% 的开发工作 ——代码在 Windows 编写，编译/测试/截图全部在 GitHub Actions 的 macOS runner 完成， 结果（构建状态、测试报告、模拟器截图）自动回传仓库。 Key idea: all iOS development can happen on Windows; compilation & simulator runs happen on CI macOS runners, with artifacts pushed back into the repo.

1. 总原则 / Core Principles

2. 工程标准 / Project Standard

2.1 目录结构（推荐 monorepo）

Project/
├── project.yml                 # XcodeGen 定义（唯一工程事实源）
├── AppKit/                     # SPM 本地包（纯逻辑，iOS+watchOS 双平台）
│   └── Package.swift
├── App/                        # iOS App（SwiftUI）
├── Watch/                      # watchOS App
├── WatchWidget/                # watchOS complication（独立 widget extension）
├── Widget/                     # iOS 小组件 extension
├── Shared/                     # 跨 target 共享源文件（消息结构、FlowLevel 等）
├── Tests/
│   ├── UnitTests/              # 单元测试（SPM 包的测试 + App 测试）
│   └── UITests/                # 截图/UI 测试（关键！见 §4）
├── docs/screenshots/           # CI 自动提交的模拟器截图
└── .github/workflows/
    ├── ios.yml                 # 常规 CI：build + test
    └── simulator-shots.yml     # 手动触发：截图并 commit 回仓库

2.2 project.yml 要点 / XcodeGen Essentials

name: MyApp
options:
  bundleIdPrefix: com.example
  deploymentTarget:
    iOS: "17.0"
    watchOS: "10.0"

packages:                        # ★ 本地 SPM 包（不要用 xcodegen 的 framework target！）
  MyKit:
    path: MyKit

targets:
  MyApp:
    type: application
    platform: iOS
    sources: [{path: App}, {path: Shared}]
    dependencies:
      - package: MyKit          # ★ 引用方式：package，不是 target
      - target: MyWatch
        embed: true
      - target: MyWidget
        embed: true
    info:
      path: App/Info.plist      # xcodegen 自动生成，含权限描述
      properties:
        UILaunchScreen: {}
        NSHealthShareUsageDescription: "…"
        NSHealthUpdateUsageDescription: "…"
        NSSpeechRecognitionUsageDescription: "…"
        NSMicrophoneUsageDescription: "…"
    entitlements:
      path: App/App.entitlements
      properties:
        com.apple.developer.healthkit: true
        com.apple.security.application-groups: [group.com.example.app]

  MyWatch:
    type: application            # ★ watchOS 用 application，不是 application.watchapp2！（坑 #4）
    platform: watchOS
    sources: [{path: Watch}, {path: Shared}]
    dependencies:
      - package: MyKit
      - target: MyWatchWidget
        embed: true

  MyWatchWidget:                 # watchOS complication 必须独立 extension（坑 #3）
    type: app-extension
    platform: watchOS
    info:
      path: WatchWidget/Info.plist
      properties:
        NSExtension:
          NSExtensionPointIdentifier: com.apple.widgetkit-extension

schemes:
  MyApp:
    build: {targets: {MyApp: all, MyWatch: all, MyWatchWidget: all, MyWidget: all}}
    test: {config: Debug, targets: [MyAppTests, MyKitTests]}
  MyAppUITests:                  # ★ 截图专用 scheme（与常规 CI 隔离）
    build: {targets: {MyApp: all, MyAppUITests: [test]}}
    test: {config: Debug, targets: [MyAppUITests]}

2.3 Swift 版本与并发

• SWIFT_VERSION: "5.10"（Xcode 16 默认；避免 Swift 6 严格并发误伤）
• @MainActor 服务类（SwiftData store 等）被 View 的普通方法同步调用会编译失败 → 给相关 View 结构体整体标 @MainActor
• SwiftData @Model 类默认 Identifiable（persistentModelID），可直接用于 sheet(item:)

3. CI 标准 / CI Standard

3.1 常规 CI（.github/workflows/ios.yml）

name: iOS CI
on: {push: {branches: [main]}, pull_request:}
jobs:
  build-and-test:
    runs-on: macos-15
    steps:
      - uses: actions/checkout@v4
      - run: brew install xcodegen
      - run: xcodegen generate
      # ★ build 用 generic 目的地（不依赖具体模拟器型号，永远可用）
      - name: Build
        run: |
          xcodebuild build -project MyApp.xcodeproj -scheme MyApp \
            -destination 'generic/platform=iOS Simulator' CODE_SIGNING_ALLOWED=NO
      # ★ test 必须具体设备：动态探测（runner 镜像的模拟器型号会变！）
      - name: Test
        run: |
          SIM_NAME=$(xcrun simctl list devices available -j | python3 -c "import json,sys;d=json.load(sys.stdin)['devices'];all_=[x for v in d.values() for x in v if x.get('isAvailable') and x['name'].startswith('iPhone')];print(sorted(all_,key=lambda x:x['name'])[-1]['name'] if all_ else '')")
          xcodebuild test -project MyApp.xcodeproj -scheme MyApp \
            -destination "platform=iOS Simulator,name=$SIM_NAME" CODE_SIGNING_ALLOWED=NO

要点：

• build 用 generic/platform=iOS Simulator；test 用探测到的具体设备名（硬编码 iPhone 16 会因 runner 镜像不同而 "Unable to find a device"）
• 免费/无证书环境 CODE_SIGNING_ALLOWED=NO 足够编译与单测
• 单测能启动 App（host app 机制），所以单测通过 ≈ App 可启动

3.2 GitHub 计费 / Billing

• Private 仓库免费额度 2000 分钟/月，macOS runner 按 10 倍计（即约 200 分钟实际）
• 额度耗尽/欠费 → job 被拒：The job was not started because recent account payments have failed...
• Public 仓库 Actions 免费无限 ← 常用解法：临时 gh repo edit --visibility public --accept-visibility-change-consequences，随时可切回 private

4. 模拟器截图标准（Windows 上看 App 效果的唯一通道）/ Simulator Screenshots via XCUITest

★ 结论：不要用 simctl launch + simctl io screenshot（参数与时序坑太多，见坑 #7~#9）。 用 XCUITest 驱动截图：xcodebuild test 是唯一稳定启动 App 的通道。

4.1 UI 测试模板（Tests/UITests/ScreenshotTests.swift）

import XCTest

final class ScreenshotTests: XCTestCase {
    func testCaptureAllTabs() throws {
        let app = XCUIApplication()
        let springboard = XCUIApplication(bundleIdentifier: "com.apple.springboard")

        for tab in ["home", "detail", "settings"] {
            // ★ 用 launchEnvironment 传截图参数（App 端读 ProcessInfo.environment）
            app.launchEnvironment["MY_SKIP_ONBOARDING"] = "1"
            app.launchEnvironment["MY_SEED_DEMO"] = "1"
            app.launchEnvironment["MY_OPEN_TAB"] = tab
            app.launch()

            // ★ 轮询处理系统弹窗（HealthKit 授权等），最长 12 秒
            for _ in 0..<6 {
                Thread.sleep(forTimeInterval: 2)
                let turnOnAll = springboard.buttons["Turn On All"]
                let allow = springboard.buttons["Allow"]
                if turnOnAll.exists { turnOnAll.tap(); break }
                if allow.exists { allow.tap(); break }
            }

            _ = app.buttons.firstMatch.waitForExistence(timeout: 15)
            Thread.sleep(forTimeInterval: 4)

            let screenshot = XCUIScreen.main.screenshot()
            // ★ 直接写 runner 沙盒 Documents（CI 用 simctl 拷贝，规范命名）
            if let docs = FileManager.default.urls(for: .documentDirectory, in: .userDomainMask).first {
                try? screenshot.pngRepresentation.write(to: docs.appendingPathComponent("\(tab).png"))
            }
            app.terminate()
        }
    }
}

App 端读取参数（仅 DEBUG 生效）：

enum LaunchArguments {
    static var seedDemo: Bool {
        #if DEBUG
        return ProcessInfo.processInfo.environment["MY_SEED_DEMO"] == "1"
        #else
        return false
        #endif
    }
}

4.2 截图工作流（.github/workflows/simulator-shots.yml）

name: Simulator Screenshots
on: workflow_dispatch
permissions: {contents: write}   # ★ 允许 CI 把截图 commit 回仓库
jobs:
  shots:
    runs-on: macos-15
    steps:
      - uses: actions/checkout@v4
      - run: brew install xcodegen
      - run: xcodegen generate
      - name: Boot simulator
        run: |
          SIM_UDID=$(xcrun simctl list devices available -j | python3 -c "…取最后一个 iPhone 的 udid…")
          echo "SIM_UDID=$SIM_UDID" >> "$GITHUB_ENV"
          xcrun simctl boot "$SIM_UDID" || true
          xcrun simctl bootstatus "$SIM_UDID" -b
      - name: Run UI tests & collect screenshots
        run: |
          SIM_NAME=$(…探测设备名…)
          xcodebuild test -project MyApp.xcodeproj -scheme MyAppUITests \
            -destination "platform=iOS Simulator,name=$SIM_NAME" \
            -resultBundlePath ui-tests.xcresult -only-testing:MyAppUITests
          mkdir -p docs/screenshots
          # ★ 从 UI test runner 沙盒直拷规范命名截图
          RUNNER=$(xcrun simctl get_app_container "$SIM_UDID" com.example.app.uitests.xctrunner data)
          cp "$RUNNER"/Documents/*.png docs/screenshots/ || true
      - name: Commit screenshots
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
          git add docs/screenshots/
          git commit -m "docs: 模拟器截图（自动生成）" || echo "no changes"
          git push

要点：

• 截图写 UI test runner 的沙盒 Documents（simctl get_app_container <udid> com.example.app.uitests.xctrunner data），比 xcresulttool export attachments（UUID 命名、需二次映射）省事
• CI 直接 commit + push 回仓库 → Windows 端 git pull 即见截图
• 演示数据（seed）通过 launchEnvironment 注入，截图内容可控

5. 网络与二进制传输标准（中国大陆网络）/ Network & Binary Transfer

典型环境：github.com:443 被阻断，github.com:22（SSH）通，api.github.com 通，raw.githubusercontent.com 时通时断。

SSH 配置（~/.ssh/config）：

Host github.com
  HostName github.com
  User git
  IdentityFile ~/.ssh/ylovel_github_ed25519
  IdentitiesOnly yes

6. 踩坑清单 / Pitfalls & Fixes（按踩坑顺序）

工程与编译 / Project & Compile

运行时崩溃 / Runtime Crashes（CI 模拟器才暴露，本地单测可能全绿）

模拟器启动与截图 / Simulator & Screenshots

资产与分发 / Assets & Distribution

7. 完整检查清单 / Final Checklist（新项目启动时逐项过）

• project.yml：SPM 本地包（非 framework target）、watchOS 用 application、complication 独立 extension、scheme 含 UI test scheme
• .gitignore：*.xcodeproj/、xcuserdata/、DerivedData/、*.ipa；.gitattributes 统一 LF
• Info.plist 权限描述齐全（Health/Speech/Microphone 按需）；AppIcon 1024 无 alpha
• iOS CI：build=generic、test=动态探测设备名；每次 push 全绿
• 截图工作流：permissions: contents: write；UI test 写 runner 沙盒；CI commit 回仓库
• 截图参数走 SIMCTL_CHILD_/launchEnvironment，且 seed 在 onAppear 而非 App.init
• 日期区间/集合构造有防御（guard lower <= upper）
• 授权请求只有一处统一入口
• git remote 用 SSH；下载二进制用 curl.exe + gh token
• 仓库 visibility 与 Actions 额度匹配（public=免费无限；private=2000 分钟/月）
• 真机分发路径明确（免费账号：Mac 直连/AltStore；付费：TestFlight）

8. 关键链接 / References

• XcodeGen：https://github.com/yonaskolb/XcodeGen（watchOS 坑：issue #1257）
• Swift Package Manager 本地包：Package.swift 放在子目录即可被 xcodegen packages.path 引用
• XCUITest 截图与 XCUIScreen.main.screenshot()
• xcrun simctl（list devices -j / get_app_container / SIMCTL_CHILD_ 环境变量注入）
• GitHub CLI：gh workflow run / gh run view --log / gh api（raw 下载二进制）