IOS Empty Project

iOS 空工程

从零搭建最小化 iOS 项目结构，支持 SwiftUI、UIKit（Swift/OC），纯代码无 Storyboard。空工程创建时必须直接生成 .xcodeproj，使工程可直接用 Xcode 打开，不依赖用户本机安装 XcodeGen。

Agent 执行要求（必读）

创建 iOS 空工程时必须同时完成：

1. 生成源码与资源：在 {ProjectName}/{ProjectName}/ 下创建对应模板的源码文件（main/AppDelegate/SceneDelegate/ViewController、Info.plist 等）。UIKit 工程（Swift/OC）必须包含 LaunchScreen.storyboard，否则在刘海屏设备上会出现非全屏（黑边）。

2. 直接生成 .xcodeproj：在工程根目录（与内层 {ProjectName}/ 同级）创建 {ProjectName}.xcodeproj/project.pbxproj，内容为合法 Xcode 工程格式，包含：

   • PBXBuildFile：每个需参与编译的 .m 或 .swift 一条；UIKit 工程必须包含 LaunchScreen.storyboard 的 Resources BuildFile。
   • PBXFileReference：每个文件（含 .h、.m/.swift、Info.plist、.app）一条；UIKit 工程含 LaunchScreen.storyboard；product 的 explicitFileType 为 wrapper.application，path 为 {ProjectName}.app。
   • PBXGroup：根 Group、Products、以及源码目录 Group（path = {ProjectName}），子 Group 按需（如 Models、Views 等）；源码 Group 中需包含 LaunchScreen.storyboard。
   • PBXSourcesBuildPhase：列出所有 .m 或 .swift 的 BuildFile。
   • PBXFrameworksBuildPhase：可为空 files。
   • PBXResourcesBuildPhase：UIKit 工程必须包含 LaunchScreen.storyboard 的 BuildFile；若含 Assets.xcassets 则再加入对应 BuildFile。
   • PBXNativeTarget：buildPhases 含 Sources、Frameworks、Resources；productReference 指向 .app 的 FileReference；productName = ProjectName。
   • PBXProject：rootObject；mainGroup；targets 含上述 NativeTarget。
   • XCBuildConfiguration（Project 与 Target 各 Debug/Release）：
     IPHONEOS_DEPLOYMENT_TARGET = 15.0；INFOPLIST_FILE = {ProjectName}/Info.plist；PRODUCT_BUNDLE_IDENTIFIER = com.example.{ProjectName}；TARGETED_DEVICE_FAMILY = "1,2"；GENERATE_INFOPLIST_FILE = NO（使用自定义 Info.plist 时）。
     Swift 时加 SWIFT_VERSION = "5.0"。不要引用不存在的 Asset Catalog（如无 Assets 则不写 ASSETCATALOG_COMPILER_*）。

3. 目录约定：工程根目录结构为 {ProjectName}/{ProjectName}.xcodeproj/ 与 {ProjectName}/{ProjectName}/（源码目录），pbxproj 中 Group 的 path 与相对路径与此一致。

完成后用户可直接 open {ProjectName}.xcodeproj 编译运行，无需执行 xcodegen generate。

（若用户明确要求使用 XcodeGen，可额外提供 project.yml 并说明需本地执行 xcodegen generate；否则以直接生成 .xcodeproj 为准。）

可选：使用 XcodeGen 生成项目

若用户已安装 XcodeGen 或明确要求用 YAML 维护工程，可提供 project.yml，由用户在工程根目录执行 xcodegen generate 生成 .xcodeproj。

1. 安装 XcodeGen：brew install xcodegen（或 Mint：mint install yonaskolb/XcodeGen）
2. 创建工程目录：如 MyApp/，其下建子目录 MyApp/ 作为 target 源码目录
3. 在工程根目录（与 MyApp/ 同级）创建 project.yml，按模板选择其一（见下）
4. 将对应模板的源码文件放入 MyApp/MyApp/（及 Assets.xcassets）
5. 执行：在含 project.yml 的目录运行 xcodegen generate，生成 MyApp.xcodeproj
6. 打开：open MyApp.xcodeproj

project.yml 示例（SwiftUI）

工程根目录放 project.yml，target 源码目录为 MyApp：

name: MyApp
options:
  bundleIdPrefix: com.example
  deploymentTarget:
    iOS: "15.0"
targets:
  MyApp:
    type: application
    platform: iOS
    sources: [MyApp]
    settings:
      base:
        SWIFT_VERSION: "5.0"
        TARGETED_DEVICE_FAMILY: "1,2"

project.yml 示例（UIKit Swift，纯代码）

name: MyApp
options:
  bundleIdPrefix: com.example
  deploymentTarget:
    iOS: "15.0"
targets:
  MyApp:
    type: application
    platform: iOS
    sources: [MyApp]
    info:
      path: MyApp/Info.plist
      properties:
        CFBundleDisplayName: 我的应用
        UILaunchStoryboardName: LaunchScreen
        UIApplicationSceneManifest:
          UIApplicationSupportsMultipleScenes: false
          UISceneConfigurations:
            UIWindowSceneSessionRoleApplication:
              - UISceneConfigurationName: Default Configuration
                UISceneDelegateClassName: "$(PRODUCT_MODULE_NAME).SceneDelegate"
    settings:
      base:
        SWIFT_VERSION: "5.0"
        TARGETED_DEVICE_FAMILY: "1,2"

需在 MyApp/Info.plist 中补全或仅保留 Scene 相关键时，也可将 info.path 指向该 plist，由 XcodeGen 自动设置 INFOPLIST_FILE。UIKit 工程仍需在 MyApp/MyApp/ 下创建 LaunchScreen.storyboard 并纳入 sources/resources，否则刘海屏上非全屏。

project.yml 示例（UIKit Objective-C，纯代码）

name: MyApp
options:
  bundleIdPrefix: com.example
  deploymentTarget:
    iOS: "15.0"
targets:
  MyApp:
    type: application
    platform: iOS
    sources: [MyApp]
    info:
      path: MyApp/Info.plist
      properties:
        CFBundleDisplayName: 我的应用
        UILaunchStoryboardName: LaunchScreen
        UISceneDelegateClassName: SceneDelegate
        UIApplicationSceneManifest:
          UIApplicationSupportsMultipleScenes: false
          UISceneConfigurations:
            UIWindowSceneSessionRoleApplication:
              - UISceneConfigurationName: Default Configuration
                UISceneDelegateClassName: SceneDelegate
    settings:
      base:
        TARGETED_DEVICE_FAMILY: "1,2"

OC 工程 UISceneDelegateClassName 填 SceneDelegate（不要用 $(PRODUCT_MODULE_NAME).SceneDelegate），否则运行可能报错。同样需提供 LaunchScreen.storyboard。

选择模板

创建前请让开发者选择：Swift 还是 Objective-C？

SwiftUI 空工程（Swift）

以下源码与资源与上文 project.yml（SwiftUI） 配合使用：放入 MyApp/MyApp/ 及 MyApp/MyApp/Assets.xcassets/，再执行 xcodegen generate。也可仅用 Xcode 手动创建。

目录结构

MyApp/
├── MyApp/
│   ├── MyAppApp.swift      # @main 入口
│   ├── ContentView.swift   # 根视图
│   └── Assets.xcassets/
└── MyApp.xcodeproj/

1. App 入口 MyAppApp.swift

import SwiftUI

@main
struct MyAppApp: App {
    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}

2. 根视图 ContentView.swift

import SwiftUI

struct ContentView: View {
    var body: some View {
        Text("Hello, World!")
    }
}

3. Assets.xcassets

创建 Assets.xcassets 目录，内含 Contents.json：

{
  "info" : {
    "author" : "xcode",
    "version" : 1
  }
}

UIKit 空工程（Swift，纯代码）

以下源码与 project.yml（UIKit Swift） 配合使用：源码放入 MyApp/MyApp/，Info.plist 可由 XcodeGen 的 info 生成或自建。

目录结构

MyApp/
├── MyApp/
│   ├── AppDelegate.swift
│   ├── SceneDelegate.swift
│   ├── ViewController.swift
│   ├── LaunchScreen.storyboard   # 必须，否则刘海屏上非全屏（黑边）
│   └── Assets.xcassets/
└── MyApp.xcodeproj/

1. AppDelegate.swift

import UIKit

@main
class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        return true
    }

    func application(_ application: UIApplication, configurationForConnecting connectingSceneSession: UISceneSession, options: UIScene.ConnectionOptions) -> UISceneConfiguration {
        return UISceneConfiguration(name: "Default Configuration", sessionRole: connectingSceneSession.role)
    }
}

2. SceneDelegate.swift

import UIKit

class SceneDelegate: UIResponder, UIWindowSceneDelegate {
    var window: UIWindow?

    func scene(_ scene: UIScene, willConnectTo session: UISceneSession, options connectionOptions: UIScene.ConnectionOptions) {
        guard let windowScene = (scene as? UIWindowScene) else { return }
        window = UIWindow(windowScene: windowScene)
        window?.rootViewController = ViewController()
        window?.makeKeyAndVisible()
    }
}

3. ViewController.swift

import UIKit

class ViewController: UIViewController {
    override func viewDidLoad() {
        super.viewDidLoad()
        view.backgroundColor = .systemBackground
    }
}

4. LaunchScreen.storyboard（必须）

UIKit 工程必须包含启动图，否则在 iPhone X 及以后机型上会以兼容模式显示，出现上下/左右黑边（非全屏）。在 MyApp/MyApp/ 下创建 LaunchScreen.storyboard，内容可为：

<?xml version="1.0" encoding="UTF-8"?>
<document type="com.apple.InterfaceBuilder3.CocoaTouch.Storyboard.XIB" version="3.0" toolsVersion="21701" targetRuntime="iOS.CocoaTouch" propertyAccessControl="none" useAutolayout="YES" launchScreen="YES" useTraitCollections="YES" useSafeAreas="YES" colorMatched="YES" initialViewController="01J-lp-oVM">
    <device id="retina6_12" orientation="portrait" appearance="light"/>
    <dependencies>
        <plugIn identifier="com.apple.InterfaceBuilder.IBCocoaTouchPlugin" version="21678"/>
        <capability name="Safe area layout guides" minToolsVersion="9.0"/>
        <capability name="documents saved in the Xcode 8 format" minToolsVersion="8.0"/>
    </dependencies>
    <scenes>
        <scene sceneID="EHf-IW-A2E">
            <objects>
                <viewController id="01J-lp-oVM" customClass="UIViewController" sceneMemberID="viewController">
                    <view key="view" contentMode="scaleToFill" id="Ze5-6b-2t3">
                        <rect key="frame" x="0.0" y="0.0" width="393" height="852"/>
                        <autoresizingMask key="autoresizingMask" widthSizable="YES" heightSizable="YES"/>
                        <viewLayoutGuide key="safeArea" id="6Tk-OE-BBY"/>
                        <color key="backgroundColor" systemColor="systemBackgroundColor"/>
                    </view>
                </viewController>
                <placeholder placeholderIdentifier="IBFirstResponder" id="iYj-Kq-Ea1" userLabel="First Responder" sceneMemberID="firstResponder"/>
            </objects>
            <point key="canvasLocation" x="53" y="375"/>
        </scene>
    </scenes>
</document>

并在 Info.plist 中增加：

<key>UILaunchStoryboardName</key>
<string>LaunchScreen</string>

pbxproj 中需：PBXFileReference（LaunchScreen.storyboard）、PBXGroup 中加入该文件、PBXBuildFile 加入 Resources、PBXResourcesBuildPhase 的 files 中加入该 BuildFile。

5. Info.plist（Scene 配置）

在 Info.plist 中需包含（UILaunchStoryboardName 见上一节）。使用自定义 Info.plist 且 GENERATE_INFOPLIST_FILE = NO 时，必须包含 CFBundleExecutable，否则真机安装会报「missing or invalid CFBundleExecutable」：

<key>CFBundleExecutable</key>
<string>$(EXECUTABLE_NAME)</string>
<key>CFBundleDisplayName</key>
<string>我的应用</string>
<key>UIApplicationSceneManifest</key>
<dict>
    <key>UIApplicationSupportsMultipleScenes</key>
    <false/>
    <key>UISceneConfigurations</key>
    <dict>
        <key>UIWindowSceneSessionRoleApplication</key>
        <array>
            <dict>
                <key>UISceneConfigurationName</key>
                <string>Default Configuration</string>
                <key>UISceneDelegateClassName</key>
                <string>$(PRODUCT_MODULE_NAME).SceneDelegate</string>
            </dict>
        </array>
    </dict>
</dict>

若集成百度地图且使用定位，需添加 NSLocationWhenInUseUsageDescription。

UIKit 空工程（Objective-C，纯代码）

以下源码与 project.yml（UIKit OC） 配合使用：源码放入 MyApp/MyApp/，Info.plist 可由 XcodeGen 的 info 生成或自建。

目录结构

MyApp/
├── MyApp/
│   ├── main.m
│   ├── AppDelegate.h
│   ├── AppDelegate.m
│   ├── SceneDelegate.h
│   ├── SceneDelegate.m
│   ├── ViewController.h
│   ├── ViewController.m
│   ├── LaunchScreen.storyboard   # 必须，否则刘海屏上非全屏（黑边）
│   └── Assets.xcassets/
└── MyApp.xcodeproj/

1. main.m

#import <UIKit/UIKit.h>
#import "AppDelegate.h"

int main(int argc, char * argv[]) {
    NSString * appDelegateClassName;
    @autoreleasepool {
        appDelegateClassName = NSStringFromClass([AppDelegate class]);
    }
    return UIApplicationMain(argc, argv, nil, appDelegateClassName);
}

2. AppDelegate.h / AppDelegate.m

// AppDelegate.h
#import <UIKit/UIKit.h>

@interface AppDelegate : UIResponder <UIApplicationDelegate>
@end

// AppDelegate.m
#import "AppDelegate.h"
#import "SceneDelegate.h"

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    // 若集成百度地图：[BMKMapManager setAgreePrivacy:YES];  // 类方法，勿用 sharedInstance
    // [[BMKMapManager sharedInstance] start:@"YOUR_AK" generalDelegate:nil];
    return YES;
}

- (UISceneConfiguration *)application:(UIApplication *)application configurationForConnectingSceneSession:(UISceneSession *)connectingSceneSession options:(UISceneConnectionOptions *)options {
    return [[UISceneConfiguration alloc] initWithName:@"Default Configuration" sessionRole:connectingSceneSession.role];
}

@end

3. SceneDelegate.h / SceneDelegate.m

// SceneDelegate.h
#import <UIKit/UIKit.h>

@interface SceneDelegate : UIResponder <UIWindowSceneDelegate>
@property (strong, nonatomic) UIWindow * window;
@end

// SceneDelegate.m
#import "SceneDelegate.h"
#import "ViewController.h"

@implementation SceneDelegate

- (void)scene:(UIScene *)scene willConnectToSession:(UISceneSession *)session options:(UISceneConnectionOptions *)connectionOptions {
    UIWindowScene *windowScene = (UIWindowScene *)scene;
    self.window = [[UIWindow alloc] initWithWindowScene:windowScene];
    self.window.rootViewController = [[ViewController alloc] init];
    [self.window makeKeyAndVisible];
}

@end

4. ViewController.h / ViewController.m

// ViewController.h
#import <UIKit/UIKit.h>

@interface ViewController : UIViewController
@end

// ViewController.m
#import "ViewController.h"

@implementation ViewController

- (void)viewDidLoad {
    [super viewDidLoad];
    self.view.backgroundColor = [UIColor systemBackgroundColor];
}

@end

5. LaunchScreen.storyboard（必须）

与「UIKit 空工程（Swift）」一节相同：必须在 MyApp/MyApp/ 下创建 LaunchScreen.storyboard（内容见 Swift 模板同节），并在 Info.plist 中增加：

<key>UILaunchStoryboardName</key>
<string>LaunchScreen</string>

pbxproj 中需把 LaunchScreen.storyboard 加入 PBXFileReference、PBXGroup、PBXBuildFile（Resources）、PBXResourcesBuildPhase。

6. Info.plist（Scene 配置）

需包含 UIApplicationSceneManifest、UISceneDelegateClassName 以及 UILaunchStoryboardName（见上一节）。使用自定义 Info.plist 时必须包含 CFBundleExecutable，否则真机安装会报「missing or invalid CFBundleExecutable」。Objective-C 工程须用 SceneDelegate（不用 $(PRODUCT_MODULE_NAME).SceneDelegate），否则运行时报错「could not load class with name "xxx.SceneDelegate"」。

<key>CFBundleExecutable</key>
<string>$(EXECUTABLE_NAME)</string>
<key>UISceneDelegateClassName</key>
<string>SceneDelegate</string>

若后续集成百度地图：必须配置 CFBundleDisplayName，否则 SDK 启动报错。使用定位时需 NSLocationWhenInUseUsageDescription。详见 baidu-map-ios-sdk 技能。

<key>CFBundleDisplayName</key>
<string>我的应用</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>需要获取您的位置以展示地图</string>

百度地图集成衔接

若创建空工程用于集成百度地图 SDK：

Xcode 项目文件要点

• 默认要求：创建空工程时 必须直接生成 {ProjectName}.xcodeproj/project.pbxproj（见上文「Agent 执行要求」），使工程可直接用 Xcode 打开，无需用户安装或执行 XcodeGen。
• pbxproj 要点：正确配置 PBXNativeTarget、PBXBuildFile、PBXFileReference、PBXGroup、PBXSourcesBuildPhase、PBXResourcesBuildPhase（UIKit 工程必须含 LaunchScreen.storyboard）、XCBuildConfiguration；Build Settings 需含 INFOPLIST_FILE、PRODUCT_BUNDLE_IDENTIFIER、TARGETED_DEVICE_FAMILY、IPHONEOS_DEPLOYMENT_TARGET（建议 15.0）；Swift 工程加 SWIFT_VERSION。不引用不存在的资源（如无 Assets 则不写 ASSETCATALOG_COMPILER_*）。
• 可选：若用户明确要求用 YAML 维护，可额外提供 project.yml，并说明需本地执行 xcodegen generate。
• 备选：用 Xcode 新建 App 工程，再删除 Storyboard 等不需要的文件。

快速命令（Swift Package 风格）

若仅需 Swift 源码骨架，可用 SPM 初始化：

mkdir MyApp && cd MyApp
swift package init --type executable

注意：SPM 生成的是命令行可执行文件，不是 iOS App。iOS App 仍需 Xcode 工程。

更多参考

• XcodeGen 安装、常用命令、Build Settings 等见 reference.md

注意事项

• 创建前：若用户未指定语言，主动询问选择 Swift 还是 Objective-C
• Launch Screen（必须）：UIKit 空工程（Swift/OC）必须包含 LaunchScreen.storyboard 并在 Info.plist 中配置 UILaunchStoryboardName，否则在刘海屏设备上会出现非全屏（黑边）。SwiftUI 工程由系统处理，可不单独提供。
• CFBundleExecutable（自定义 Info.plist 时必须）：使用自定义 Info.plist 且 GENERATE_INFOPLIST_FILE = NO 时，必须在 Info.plist 中配置 CFBundleExecutable 为 $(EXECUTABLE_NAME)，否则真机安装会报「missing or invalid CFBundleExecutable」、无法安装（CoreDeviceError 3002）。
• SwiftUI 工程无需 Info.plist 中的 Scene 配置，Xcode 会自动处理
• UIKit 纯代码工程需在 Info.plist 中移除 UIMainStoryboardFile 等 Storyboard 相关键，但保留 UILaunchStoryboardName = LaunchScreen
• 最低支持版本建议 iOS 15+，以覆盖 Swift Concurrency 等特性