. 先建立一套正确的心智模型

痛点：很多新人把 iOS 工程误认为只有一个文件夹加几个 Swift 文件，导致后期维护和 困难。

iOS 工程是一张由容器、建立规则、依赖和执行配置组成的图。怎么说呢，

可以先记住下面六句话：

1. Workspace 是多个工程的工作容器。
2. Project 保存 Target、文件引用和建立配置。
3. Target 描述如何把一组输入建立成一个 Product。
4. Scheme 描述 Build、Run、Test、Profile、Analyze、Archive 怎么执行。
5. Build Configuration 是一套有名字的 Build Settings。
6. Package Dependency 向 Target 提供可编译或可链接的 Product。

它们的基本组合关系：

Workspace
├── Project A
│ ├── Target: App
│ ├── Target: UnitTests
│ ├── Target: UITests
│ └── Package References
├── Project B
│ └── Target: Framework
└── Schemes
├── App-Debug
├── App-Staging
└── App-Release

建立关系可以简化为：

Scheme -> 选择 Build Action -> 选择一个或多个 Target
-> 为每个 Action 选择 Build Configuration
-> Target 读取 Build Settings
-> 执行 Build Phases
-> 建立 Target Dependencies 和 Package Products
-> 生成 Product

当前 WebRTC Demo 的实际模型

WebRTC-Demo.xcworkspace
├── WebRTC-Demo.xcodeproj
│ └── Target: WebRTC-Demo
│ ├── Product: WebRTC-Demo.app
│ ├── Sources
│ ├── Resources
│ ├── Package Product: Starscream
│ └── Package Product: WebRTC
└── SignalingServer.xcodeproj
└── Target: SignalingServer
├── Product: SignalingServer
└── Platform: macOS

运行时还有另一层关系：

WebRTC-Demo.app -- WebSocket --> SignalingServer

这个 WebSocket 关系不属于 Target 编译依赖，而是两个进程之间的运行时服务依赖。

. Xcode 左侧目录不完全等于磁盘目录

磁盘文件程序

WebRTC-iOS-main/
├── WebRTC-Demo-App/
│ ├── Sources/
│ ├── Resources/
│ ├── SupportingFiles/
│ ├── WebRTC-Demo.xcodeproj/
│ └── WebRTC-Demo.xcworkspace/
└── signaling/
└── Swift/
└── SignalingServer.xcodeproj/

Xcode Navigator 展示的内容

• Workspace 引用的 Project。
• Project 保存的 Group。
• 文件引用。
• Package Dependencies。
• Products。

痛点：Xcode 中节点可能是实际目录。也可能是纯粹的逻辑 Group，导致开发者误判磁盘方法，产生找不到文件或重复引用的问题。老实说，

Group 与 Folder Reference 的区别

• 黄色 Group: 仅用于逻辑组织。名称可以与磁盘目录不同，移动 Group 不一定移动磁盘文件，且加入 Group 并不保证被编译。
• Folder Reference: 更接近磁盘目录。但仍需检查 Target Membership 与 Build Phase 设置，否则资源不会被打包。

文件出现不等于被编译

A .swift 文件即使显示在 Xcode 左侧。如果没有加入某个 Target 的 Compile Sources，它就不会进入该 Target。相反，同一个文件可以属于多个 Target，并针对每个 Target 分别编译。这正是 Total Membership 的本质。按理说，

The Role of .xcodeproj

• 文件与 Group 引用。
• Targe​t 列表。怎么说呢，
• P​roduct 列表。
• B​uild Phases 定义每一步骤。
• B​uild Settings 与 Configurations 保存所有参数化信息。
• T​arget Dependencies 定义内部建立顺序。
• P​ackage References 用于 SwiftPM 集成。话说回来，
• S​hared Scheme和 User Scheme元数据。

Pain Point: 很多人误以为 .xcodeproj 就是最终 App，实际它只是一个描述性的容器，真正产物是由其中的 Targets 决定的.

.xcodeproj 实际是目录包（Bundle)

WebRTC-Demo.xcodeproj/
├─ project.pbxproj ← 主要配置文件
├─ project.xcworkspace/ ← 隐式 Workspace。仅在单独打开 .xcodeproj 时使用
├─ xcshareddata/
│  └─ xcschemes/ ← 团队共享 Scheme
└─ xcuserdata/ ← 本地 UI 状态 & 使用者 Scheme

`project.pbxproj` 保存了哪些对象？

• `PBXProject` – 项目根对象
• `PBXNativeTarget` – 原生建立目标
• `PBXFileReference` – 文件或产物引用
• `PBXGroup` – Xcode 中的逻辑分组
• `PBXBuildFile` – 某个文件进入某个 Build Phase 的记录
• `PBXSourcesBuildPhase`,`PBXResourcesBuildPhase`,`PBXFrameworksBuildPhase`。`PBXCopyFilesBuildPhase` – 各种标准阶段
• `PBXTargetDependency` – 建立顺序依赖
• `XCBuildConfiguration`,`XCConfigurationList` – 配置集合
• `XCRemoteSwiftPackageReference`,`XCSwiftPackageProductDependency` – Swift 包声明与产品依赖

ID 如何串联对象？

project.pbxproj 中每个对象都有类似 79262EE220B0D6F600D576C1 的唯一标识符。Scheme 中会通过 BlueprintIdentifier = "79262EE220B0D6F600D576C1" 指向对应的 App Target。 Xcode 正是靠这些 UUID 把 Scheme / Targets / Build Phases / Files 串成完整图谱的。Pain Point: 手动编辑 pbxproj 极易破坏 UUID 链接，引发不可预料的合并冲突或工程无法打开。除非对对象模型非常熟悉，否则务必通过 UI 完成修改。

. Project 级配置 vs. Target 级配置

.Project‑level Settings

• S​​wift version。警告规则,Deployment‑target 默认值等通用设置放在这里以免在每个 target 重复声明。

  SDKROOT = iphoneos
  IPHONEOS_DEPLOYMENT_TARGET = 13.0
  SWIFT_VERSION = 5.8
  SWIFT_ACTIVE_COMPILATION_CONDITIONS = DEBUG
  SWIFT_OPTIMIZATION_LEVEL = -Onone // Debug 下
  ENABLE_TESTABILITY = YES // Debug 下
  SWIFT_OPTIMIZATION_LEVEL = -O // Release 下
  DEBUG_INFORMATION_FORMAT = dwarf-with-dsym // Release 下
  VALIDATE_PRODUCT = YES // Release 下
  ...

  PRODUCT_BUNDLE_IDENTIFIER = com.stasel.WebRTC
  PRODUCT_NAME = $
  INFOPLIST_FILE = $/SupportingFiles/Info.plist
  ASSETCATALOG_COMPILER_APPICON_NAME = AppIcon
  TARGETED_DEVICE_FAMILY = "1。2"
  CODE_SIGN_STYLE = Automatic
  ...

  Pain Point: 开发者经常只看 “Project Settings”，忽略了同名 target 设置覆盖，从而导致调试环境下出现意外签名错误或资源方法错误。建议使用 XCode “Levels” 查看最终有效值。

  The Inherited Mechanism `)

  • `OTHER_LDFLAGS = $ -ObjC` 如果覆盖时忘记 `$`，会丢失项目级别还有 SwiftPM 自动注入的链接标志。Pain Point: 遗漏 `$` 常导致第三方库链接失败，只报 “Undefined symbols”。

    . What is a Target?

    The Core Definition of a Target

    Target
    ├─ Inputs
    ├─ Build Settings
    ├─ Build Phases
    └─ Output Product
    Pain Point: 很多人把 “App” 当作唯一 target。却忽略了测试 bundle、extension 等其他 target，使得功能拆分和代码复用受阻。
    
    A target is NOT an app itself — only an Application‑type target produces a `.app` bundle.
    .xctest 
    …怎么说呢，etc.
    Pain Point: 在大型项目里混淆 target 类型会导致错误地把资源放进错误 build phase。例如把 UI Tests 放进 Compile Sources 导致编译报错。
    
    Current Demo’s Two Targets
    
    
    WebRTC‑Demo → App 
    
    SignalingServer → macOS tool 
    
    两者位于不同 project 中，互相独立。
    
    Multi‑target in one project
    
    
    CompanyApp.xcproject/
    ├─ CompanyApp ← Application
    ├─ CompanyAppTests ← Unit tests
    ├─ CompanyAppUITests ← UI tests
    ├─ NotificationService← Extension
    └─ ShareExtension ← Extension
    
    *每个 target 都拥有自己的 bundle identifier、info.plist 与签名设置，即使共享同一源码也会分别打包进去。
    
    Target Membership in practice
    
    
    打开 File Inspector → 勾选对应 target 即可把源码加入该 target 的 Compile Sources 阶段。
    
    同一个源码若勾选多个 targets。则会分别编译进各自 product，而不是运行时共享同一份二进制。按理说，
    
    Target Dependency
    
    
    App → FeatureFramework → CoreFramework
     
    
    XCode 会先建立 Core。再建立 Feature，最终再建立 App。如果缺少此依赖，则可能出现 “Undefined symbols for architecture …” 错误，
    
    . Dependency Types Overview
    
    
    Common target types & ir products 
    
    I​OS Application 
    .app 
    
    I​OS Framework 
    .framework 
    
    I​OS Static Library 
    .a 
    
    I​Unit Test Bundle 
    .xctest 
    
    I​UI Test Bundle 
    
     I ​Extension  
     .appex 
    
    
     Command Line Tool
     executable
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    
    Relationship
    When does it happen?
    Where is it configured?
    Demo example
    
    
    
    
    Target Dependency
    建立前
    Target → Dependencies
    当前为空
    
    
    Link Dependency
    链接阶段
    Link Binary With Libraries + Package Product
    Starscream & WebRTC
    
    
    Resource Dependency
    Copy Bundle Resources
    Copy Bundle Resources 阶段
    Assets.xcassets,Storyboard
    
    
    Runtime Service Dependency
    程序运行时网络交互
    源码中手写业务逻辑
    App ↔︎ SignalingServer via WS
    
    
    
    
    
    . Build Phases Explained
    
    What y do?
    
    A target tells XCode what to build. Build Phases tell it how to process inputs. Common phases include:
    
    1️⃣ Target Dependencies
    2️⃣ Compile Sources
    3️⃣ Link Binary With Libraries
    4️⃣ Copy Bundle Resources
    5️⃣ Embed Frameworks
    6️⃣ Copy Files
    7️⃣ Run Script 
    
    Additional hidden steps：Info.plist processing、Swift module generation、dSYM creation、Code signing 等等。
    
    
    Compile Sources
    
    Current app compile list includes:
    
    
    AppDelegate.swift
    Config.swift
    MainViewController.swift
    VideoViewController.swift
    WebRTCClient.swift
    SignalingClient.swift
    Message.swift
    WebSocketProvider.swift
    StarscreamProvider.swift
    NativeWebSocket.swift
    SessionDescription.swift
    IceCandidate.swift
    RTCStates.swift
     
    
    If a file is not listed here → It will not be compiled for that target,even if you can see it in navigator. 
    
    
    Link Binary With Libraries
    
    For this demo:
    
    
    WebRTC // binary xcframework from SwiftPM
    Starscream // source package compiled into a framework
     
    
    These are linked after compilation of source files and before code signing. 
    
    
    Copy Bundle Resources
    
    Resources copied into final .app: 
    
    
    Assets.xcassets
    MainViewController.xib
    VideoViewController.xib
    LaunchScreen.storyboard
     
    
    Note that asset catalogs are compiled by actool;xibs/storyboards are processed by Interface Builder compiler rar than being raw copies. 
    
    
    Why Info.plist is NOT a regular resource
    
    The Info.plist file is referenced via build setting:
    
    
    INFOPLIST_FILE = $/SupportingFiles/Info.plist
     
    
    During build XCode expands variables such as $ and writes final plist into bundle automatically—so you should never manually add it to Copy Bundle Resources. 
    
    
    Run Script
    
    Typical scripts:
    
    
    SwiftLint / SwiftFormat checks 
    
    Code generation 
    
    dSYM upload to crash reporting service 
    
    License aggregation 
    
    
    Best practices:
    
    
    Declare explicit Input Files / Output Files so incremental builds work. 
    
    Return non‑zero exit status on failure. 
    
    Never hard‑code secrets inside scripts. 
    
    Consider enabling ENABLE_USER_SCRIPT_SANDBOXING. 
    
    
    The current demo has no custom Run Script phases. 
    
    
    . The Final Product
    
    A .app bundle is actually a directory containing executable code plus resources:
    
    
    WebRTC-Demo.app/
    ├─ WebRTC-Demo ← executable binary
    ├─ Info.plist ← merged from build settings
    ├─ Assets.car ← compiled asset catalog
    ├─ Frameworks/ ← embedded frameworks
    ├─ Base.lproj/ ← localized storyboards & nibs
    └─ _CodeSignature/,embedded.mobileprovision … 
    
    Different destinations and signing styles affect which files appear inside this bundle. 
    
    All derived products live under XCode’s DerivedData folder:
    
    
    ~/Library/Developer/Xcode/DerivedData//Build/Products/-iphoneos/
     
    
    DerivedData should never be committed to Git because它是可再生成的数据。其实，
    
    
    . Workspace – The Multi‑Project Container
    
    A .xcworkspace can hold multiple .xcodeprojs and thus lets you edit and build m toger.
    
    How this demo’s workspace references two projects:
    
    In contents.xcworkspacedata:
    
    xml
    
    
    
    
    Resulting view in XCode shows both projects side by side.
    
    Important note on dependencies inside a workspace:
    
    Putting two projects toger does NOT automatically create compile or runtime dependencies 娱乐ween ir targets—you still need explicit Target Dependencies。Link Binary With Libraries,or runtime networking code to wire m up.
    
    When do you really need a workspace?
    
    
    Multiple internal frameworks living in separate projects.
    
    CocoaPods generated Pods project.
    
    Cross‑platform server tools alongside iOS app.
    
    Shared schemes across several projects.
    
    
    If your app consists of just one project you can safely rely on XCode’s implicit workspace . 
    
    The recommended entry point for this repo is:
    
    
    WebRTC‑Demo-App/WebRTC‑Demo.xcworkspace
     
    
    Team members and CI pipelines should open this file consistently to avoid mismatched scheme visibility or duplicate lock files.
    
    
    . Scheme – Execution Recipe
    
    A scheme decides what。how,and when things happen for a set of targets.
    
    Key questions answered by a scheme:
    
    
    Which targets are built?
    
    Which configuration is used for each action?其实，
    
    Which product runs when you press ▶️?
    
    Which tests run when you press ⌘U?
    
    Which environment variables / launch arguments are passed at runtime?
    
    
    Schemes contain six primary actions:
    
    
    
    <\/ad>
    
    
    Action 
    Typical Use 
    Default Configuration 
    
    
     Build                                                                                                                            ‎ ‎ ‎ ‎ ‎ ‎ ‎ ‎‎‎‎‎‎‎‎‏‏‏‏‏‏‏‏‏ ‏ ‏ ‏ ‌ ‌ ‌ ‌ ‌ ‌ ‌ ‌‌‌‌‌‍‍‍‍‍‌‌‌‌‌‌‌‌​​​ ​​​​ ​​​​​​​​​​​​​​​​​​​​​​​​​ ​​​​​​​​​ ​​​​️ 🚀 🚀 🚀 🚀 🚀 🚀🚂🚂🚂🚂🚂🚂⛽⛽⛽ ⟹ 🏎️ 🏎️ 🏎️🕹️🕹️🕹️🤖 🤖 🤖🤖🤖⚙⚙⚙⚙⚙ ⚡ ⚡ ⚡ 🔧🔧🔧 🔨🔨🔨 🔩 🔩 🔩 🔗🔗🔦💡💡💡📦 📦 📦 📦📞📞📞🛠️🛠️🛠️💬💬💬🎯🎯🎯 🎱 🎱 🎱 🌈🌈🌈 ✨✨✨ ✅✅✅ ✔✔✔✍✍✍✍✍✍🏁🏁🏁🏁⮚ ⮚ ⮚⟰ ⟰ ⟰⟰⟰⬆⬆⬆⬇⬇⬇➡➡➡↘↘↘◀◀◀▶▶▶☝☝☝⌚⌚⌚➤➤➤ ➣ ➣ ➣ ❓❓❓❓❓❓ ❗❗❗⁉⁉⁉⁉⁉ ⁉ ⁉ ⁉ ⁉ ❌ ❌ ❌ 🙅 🙅 🙅 🙅 🙅 🙅 👎👎👎 💥 💥 💥 🌀🌀🌀 📣 📣 📣 ☑ ☑ ☑ ✅ ✅ ✅ 🎉 🎉 🎉 🏆 🏆 🏆 🌟 🌟 🌟 💎 💎 💎 🍾 🍾 🍾 ✨ ✨ ✨ 😎 😎 😎 🤝 🤝 🤝 👍 👍 👍 👏 👏 👏 🚦 🚦 🚦 �... ... ... .... ...................... .... .................. ...... ....... .......... ..... ...... ........... .....' ] ) );，>
    
    
    
    
    Sorry!This answer was truncated due overflow