Fork me on GitHub

XcodeGen 小白教程：从安装到生成 iOS 工程

一篇面向新手的 XcodeGen 实践指南：它是什么、怎么装、怎么写 project.yml、怎么和 CocoaPods 配合，以及常见坑。

目录

  1. 它是什么
  2. 安装
  3. 核心概念
  4. 最小可用工程：从零实践一遍
  5. project.yml 常用配置详解
  6. 与 CocoaPods 配合
  7. 日常使用场景对照表
  8. 常见坑
  9. 速查命令
  10. 官方教程链接

1. 它是什么

XcodeGen 是一个命令行工具，用来「用文本文件生成 Xcode 工程」。

  • 传统方式：在 Xcode 图形界面点 New Project → 配置 Target → 逐个添加文件。
  • XcodeGen 方式：手写一个 project.yml 文本文件描述工程长什么样 → 跑一条命令生成 .xcodeproj。
project.yml（文本配置，人手写）
        │
        │  xcodegen generate
        ▼
MyApp.xcodeproj（Xcode 能正常打开使用的工程）

为什么用它：.xcodeproj 内部的 project.pbxproj 格式非常复杂，人工手写几乎不可能；而 XcodeGen 让你用人类可读的 YAML 描述工程，特别适合：脚本化创建工程、AI/命令行工具搭建工程、团队间用文本共享和评审工程结构。

如果你用过 CocoaPods，可以这样类比：Podfile → pod install 生成 Pods 集成；project.yml → xcodegen generate 生成工程。

2. 安装

brew install xcodegen

验证安装成功：

xcodegen --version
# 输出版本号（如 Version: 2.44.1）即成功

装一次即可，之后永久可用。升级用 brew upgrade xcodegen。

3. 核心概念

概念 说明
project.yml 工程定义文件（YAML 格式），描述 Target、设置、Info.plist、Scheme 等
xcodegen generate 读取 project.yml，生成 .xcodeproj
YAML 格式 「冒号键值对 + 空格缩进表示层级」的文本格式

YAML 基础示例：

name: MyApp            # 键: 值（冒号后要有一个空格）
targets:               # 一级配置
  MyApp:               # 缩进 2 空格 = targets 的子项
    type: application  # 再缩进 2 空格 = MyApp 的子项

两个硬规则：缩进必须用空格（不能 Tab）；冒号后必须有一个空格。

4. 最小可用工程：从零实践一遍

4.1 创建目录和 project.yml

mkdir MyApp && cd MyApp
touch project.yml        # 创建空文件
vim project.yml          # 用 vim 编辑（VSCode 等任意编辑器都可以）

写入以下最小内容：

name: MyApp
options:
  deploymentTarget:
    iOS: "15.0"
targets:
  MyApp:
    type: application
    platform: iOS
    sources:
      - path: MyApp

sources 指向的 MyApp 目录必须存在——这是放 App 源码的地方。

4.2 放一个源码文件

mkdir MyApp

在 MyApp/AppDelegate.swift 里写一个最小的 App 入口：

import UIKit

@main
class AppDelegate: UIResponder, UIApplicationDelegate {
    var window: UIWindow?
    func application(_ application: UIApplication,
                     didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        window = UIWindow(frame: UIScreen.main.bounds)
        window?.backgroundColor = .white
        window?.makeKeyAndVisible()
        return true
    }
}

4.3 生成工程

xcodegen generate
# 输出: Created project at .../MyApp.xcodeproj

4.4 打开验证

open MyApp.xcodeproj

Xcode 里能看到 MyApp Target、AppDelegate.swift 已挂进工程，直接 Run 即可。

5. project.yml 常用配置详解

以下是一个覆盖了主要场景的完整示例：

name: MyApp                              # ① 工程名（生成 <name>.xcodeproj）
options:
  deploymentTarget:                      # ② 全局最低部署版本
    iOS: "15.0"
settings:
  base:                                  # ③ 工程级 Build Settings
    SWIFT_VERSION: "5.0"                 #    Swift 语言模式

targets:                                 # ④ Target 列表
  MyApp:                                 #    App Target
    type: application                    #    Target 类型
    platform: iOS
    sources:                             #    源码目录（整个目录的文件都收进 Target）
      - path: MyApp
    info:                                # ⑤ Info.plist 内容（xcodegen 自动生成 plist 文件）
      path: MyApp/Info.plist             #    plist 输出路径
      properties:                        #    plist 键值
        CFBundleDisplayName: MyApp
        UILaunchScreen: {}
        NSAppTransportSecurity:
          NSAllowsArbitraryLoads: true
    settings:
      base:                              # ⑥ Target 级 Build Settings
        PRODUCT_BUNDLE_IDENTIFIER: com.example.myapp
        CODE_SIGN_STYLE: Automatic

  MyAppTests:                            # ⑦ 测试 Target
    type: bundle.unit-test
    platform: iOS
    sources:
      - path: MyAppTests

schemes:                                 # ⑧ 共享 Scheme
  MyApp:
    build:
      targets:
        MyApp: all
    run:
      config: Debug

各段作用与 Xcode 界面的对应关系：

段落 作用 对应 Xcode 里的位置
① name 工程名 文件 <name>.xcodeproj
② deploymentTarget 最低系统版本 Target → General → Minimum Deployments
③ settings 全局 Build Settings Project → Build Settings
④ targets 所有 Target 定义 左侧导航栏的 Target 列表
⑤ info Info.plist 内容 工程里的 Info.plist 文件
⑥ settings.base Target 级设置 Target → Build Settings
⑦ 测试 Target 单测 / UI 测试 左侧 Target
⑧ schemes Scheme 配置 Xcode 顶部 Scheme 选择器

更多字段查官方 ProjectSpec 文档（见第 10 节）。

6. 与 CocoaPods 配合

XcodeGen 生成工程后，每次跑 xcodegen generate 都会抹掉 CocoaPods 的集成（pod 的 xcconfig 引用、构建阶段都没了），所以标准流程是两条命令连用：

xcodegen generate   # 1. 重新生成工程结构
pod install         # 2. 重新挂上 CocoaPods 集成

两者各管各的：Podfile 管三方库，project.yml 管工程结构，互不干扰。

7. 日常使用场景对照表

你做了什么 需要执行的命令
修改已有文件里的代码 什么都不用做
壳工程源码目录下新增/删除文件 xcodegen generate + pod install
改 Info.plist 配置 改 project.yml 的 info.properties → 同上
改 Bundle ID / 部署版本 改 project.yml 对应段落 → 同上
改工程级 Build Settings 改 project.yml 的 settings → 同上
Pod 组件（podspec 管理的源码）加文件 不用 xcodegen，跑 pod install 即可
新增整个 Target project.yml 加 target 段 → 同上

8. 常见坑

  1. Info.plist 会被覆盖：info: 段落生成的 plist 文件，直接改 plist 后跑 generate 会被还原——正确姿势是改 project.yml。
  2. 忘了 pod install：generate 后必须 pod install，否则打开工程会报缺 Pods 配置。
  3. 缩进错误：YAML 用空格缩进（2 格一层），用 Tab 会报错；冒号后要空格。
  4. sources 目录不存在：generate 会报错，先建目录。
  5. 在 Xcode 里改的工程设置会被覆盖：工程级配置以 project.yml 为准；若团队不想用 xcodegen 维护，可以把 project.yml 当一次性生成模板，之后全部在 Xcode 里改。

9. 速查命令

xcodegen generate          # 生成工程
xcodegen dump              # 打印当前 project.yml 解析结果（排错用）
xcodegen --version         # 查看版本
brew upgrade xcodegen      # 升级

10. 官方教程链接

project.yml 编写官方文档（最权威的两篇）：

其他参考：

posted @ 2026-09-01 15:53  极度恐慌_JG  阅读(33)  评论(0)    收藏  举报