1. 为什么说 Project 管理本身就是一种架构聊到 iOS 架构很多人第一反应是 MVC、MVVM、VIPER 这些代码层的设计模式或者组件化、模块化这样的技术方案。但我在一线待了这么多年有个越来越强烈的体会真正决定一个项目能不能长期健康迭代的往往不是某个 ViewModel 怎么写而是工程结构顶层那一层——Project 管理。这层要是乱了后面再怎么重构代码都是治标不治本。Project 管理这个词听起来很基础好像就是把文件拖进 Xcode、建几个文件夹、加几个 Target 而已。但实际上它承载的东西非常多代码的物理组织方式、构建配置的继承关系、多环境的切换方案、资源文件的归属、依赖的引入方式、编译的顺序与依赖、甚至团队协作时的冲突边界。这些如果从一开始就没设计好等业务膨胀到几十万行代码的时候再想调整就不是改几天代码的事情了而是要把整个工程推倒重来的级别。我见过太多这样的场景某个业务模块的开发同学为了提一个小小的需求要在一个几万行的 Xcode 工程里翻半天才能找到对应的文件或者明明只是换个测试环境的接口地址却要手动改多处配置一不小心就漏改一处导致线上环境串了测试环境的数据。这些问题看起来像是“管理不规范”本质上是 Project 层面缺少架构设计。所以这篇文章我想认真聊聊iOS 项目里的 Project 管理到底该怎么做。我不会只讲概念而是把我在实际项目中踩过的坑、验证过的做法、以及背后的思考逻辑都摊开来讲。内容会覆盖分层设计、Target 与 Scheme 的规划、Build Settings 的下沉、xcconfig 的应用、依赖管理的选型以及构建性能的优化。无论你是在维护一个几万行的老项目还是准备从零搭建一个新工程的基建这篇文章都应该能给你一些可以直接落地的参考。2. 整体设计思路工程结构先于代码结构2.1 先分清“物理目录”和“逻辑 Target”我在重构某个老项目的时候第一步不是动代码而是把整个工程的文件结构画出来然后问团队一个问题我们现在有几层这里说的“层”不是 MVVM 那种代码分层而是物理目录和 Target 层面的分层。我通常会把一个 iOS 工程的目录结构拆成四个区域App 入口层只放 AppDelegate、SceneDelegate、主 Window 的配置、全局的启动逻辑。这一层要尽量薄不承载任何业务。Feature 业务层按业务域拆分的模块比如登录、首页、订单、消息。每个模块内部再按照自己的需求去组织互不依赖。Core 基础层网络、存储、日志、埋点、路由、工具类。这一层不依赖任何业务模块。Shared 共享层资源文件、第三方库的封装、通用的 UI 组件。为什么要这么分因为 Project 管理最大的价值之一就是通过物理边界来强制约束依赖关系。如果目录只有一个平铺的 Main 文件夹那代码的归属就是靠自觉久而久之必然出现各种跨层调用——比如某个业务页面直接操作数据库或者某个工具类里硬编码了业务逻辑。而如果你在 Project 规划阶段就把目录结构按层级铺好并且通过 Target、文件归属这些硬性手段来约束团队每个人在新建文件的时候就会下意识地想这个文件应该放在哪一层、属于哪个模块。这种潜移默化的影响比代码评审时的一句“你这个不该放这里”要有效得多。实际项目中我会立刻把这些目录建出来哪怕里面是空的。空目录在磁盘上存在就行Xcode 中可以不引用但团队约定俗成后新文件就有了默认的落位。2.2 从单 Target 到多 Target 的演进路线很多 iOS 项目都是从单 Target 起步的这在初期完全没问题。但当项目进入第二个阶段也就是需要区分不同环境开发、测试、生产或者需要做独立的功能模块比如主机 App 和扩展 App的时候单 Target 就会开始拖后腿。我见过最典型的做法是在单个 Target 里通过编译宏或者运行时判断来区分环境。比如在代码里写#if DEBUG、或者定义一个kIsTestEnvironment来切换接口地址。这能跑但是问题不少首先所有环境的代码都在同一个二进制里面不上线也能通过某些手段切到测试环境其次配置逻辑散落在代码中新同学根本搞不清楚哪些是当前环境生效的再者如果你要做严格的发布流程希望测试包和生产包在构建层面就隔离这种运行时切换的做法很难满足。所以我更推荐在工程结构上直接按 Target 拆分。从单 Target 到多 Target 的演进路径我建议分三步走第一步把通用代码和配置抽取出来保证它们不依赖任何环境变量。第二步建立基础的AppDev、AppStaging、AppProd三个 Target它们共用同一份源代码文件但各自的 Build Settings 和 Info.plist 完全独立。第三步把不同环境的差异逐步从代码中剥离全部收拢到 Build Settings 和配置文件里。这个方案的优点在于环境差异在编译期就固定下来了。开发包用的是开发环境的配置生产包用的是生产环境的配置构建产物互不干扰。它带来的额外好处是CI/CD 的流程也可以针对不同 Target 走不同的签名配置和发布流程。2.3 Build Settings 是项目里的“隐藏架构”我在 Code Review 的时候最怕看到的信息之一就是在某个 Xcode 的 Build Settings 面板里硬塞了一堆自定义配置。比如有人直接把接口地址写在Other Linker Flags里面或者用Preprocessor Macros塞一堆业务开关。这样的配置一旦多了工程的可维护性就会急剧下降因为 Build Settings 的配置项是全局性的、容易被覆盖的而且不同 Target 之间的配置关系非常容易混乱。正确的做法是让 Build Settings 成为一个“可编程”的配置文件体系。也就是说不要依赖 Xcode 面板里的图形化界面来管理配置而是把配置项下沉到 xcconfig 文件里通过文件的继承关系来体系化地管理。这就像把原来散落在各个角落的常量定义统一抽到一个配置类里。Build Settings 的层级关系天然适合做这件事工程级别的配置在最底层Target 级别的配置覆盖上层Scheme 用来决定使用哪一套配置。我实际操作中的做法是这样的建一个Configurations目录专门存放所有的 xcconfig 文件。针对每个环境建立独立的Dev.xcconfig、Staging.xcconfig、Release.xcconfig。这些文件通过#include引入公共配置让三个环境的配置共享大部分内容差异项只在各自的文件里覆盖。这样设计的核心价值在于所有环境差异全部集中到几个配置文件里排查环境和构建相关的问题时只要打开这几个文件一切一目了然。不需要在 Xcode 的 Build Settings 面板里翻几页才能找到某个配置项也不需要担心某个人手滑改了全局配置。3. 核心细节解析xcconfig、Target 与 Scheme 的三位一体3.1 xcconfig 的正确用法与常见误区xcconfig 文件本质上是一个基于键值对的配置文件语法很简单但它背后支持的继承机制才是真正让它强大的地方。#include指令可以引入其他配置文件从而实现配置的继承与覆盖。我在项目中通常会建立这样一组文件Configurations/ ├── Common.xcconfig ├── Dev.xcconfig ├── Staging.xcconfig └── Release.xcconfigCommon.xcconfig存放所有环境共享的配置比如代码签名用的证书名、最低系统版本、某些通用的编译选项。三个环境各自的文件则通过#include Common.xcconfig引用基础配置再定义自己独有的项比如 API Base URL、日志级别、统计开关等。有一个关键点需要特别注意xcconfig 中的#include路径是相对于当前文件所在目录的而且路径中不能使用变量来构造比如#include $(SRCROOT)/...这种写法是行不通的。我刚开始用的时候就踩过这个坑后来干脆把所有 xcconfig 文件都放在同一个目录下用相对路径引用省掉了很多麻烦。另外一个常见的误区是试图用 xcconfig 覆盖所有 Build Settings。但有些设置是无法通过 xcconfig 配置的比如Info.plist文件的路径、某些 Target 的常规设置等这些只能在 Xcode 面板里配置。所以我的原则是凡是能在 xcconfig 里配置的全部下沉不能在 xcconfig 里配置的在面板里设置完成后一定要加上注释说明为什么这样设置并同步到工程的文档中。3.2 Target 的划分策略一个主 Target 加若干个子 Target讲到 Target 划分我见过两种极端的做法一种是全局只有一个 Target什么功能都往里面塞另一种是把每个功能模块都单独建一个 Target结果 Target 数量多达几十个编译的时候依赖关系极其复杂每次 Build 都要经历漫长的链接过程。这两种做法我都不推荐。合理的策略是主 Target 只保留一个它是最终 App 的二进制目标。其余的子 Target 按需要建立主要包括三类扩展 Target比如通知扩展、Widget 扩展、Share 扩展。这些扩展虽然最终会打进主 App 的二进制里但它们在逻辑上是独立的进程必须独立成 Target。框架 Target如果你做的是模块化开发可以把各个独立模块拆成 framework Target。这里需要注意动态框架会增加启动时链接的开销而静态库则没有这个问题。我建议小团队的项目优先使用静态库等模块数量多到一定程度再考虑动态库。测试 Target包括单元测试和 UI 测试的 Target。测试 Target 应该跟主 Target 保持完全一致的配置环境否则很容易出现测试环境能跑、线上环境崩掉的问题。我把这个策略总结下来就是Target 的个数是有上限的能共享代码的文件一定要共享不要因为某个文件只属于某个功能模块就把它单独拉出去建 Target。Target 多了工程文件冲突的频率会急剧上升。所谓某个功能模块独立成 Target在 Web 前端可以做微前端但在 iOS 的世界里二进制层面的模块独立性是以一定的复杂度为代价的。除非团队规模和业务复杂度真的到了不拆不行的地步否则我建议先用目录分层、再用静态库、最后才上动态库一步步来。3.3 Scheme 是环境切换的“总开关”Scheme 在 Xcode 里是最容易被忽视、但也是环境切换最重要的一环。很多人直接使用 Xcode 默认生成的 Scheme然后通过修改 Target 的 Build Configuration 来切换环境这样也可以但每次切换环境都需要手动操作还容易出错。我的建议是为每个环境维护一个独立的 Scheme并且把 Scheme 之间的差异通过 Shared Scheme 提交到版本库中。这样团队每个人检出的代码都已经带着所有环境的 Scheme不需要各自手动创建。Scheme 里除了管理 Build Configuration还有三个地方值得注意Run 和 Test 的配置需要保证 Debug 环境下测试和运行使用的是同一套 Build Configuration否则会出现测试结果和生产环境不一致的情况。Archive 的配置只允许使用 Release 配置。这个最好在命名的时候就稍微规范一点比如AppDev、AppStaging、AppRelease这样在选择的时候不容易混淆。启动参数和环境变量。Scheme 可以配置启动时的环境变量这比在代码里硬编码强太多。我在本地调试的时候通常会通过 Scheme 传入一个开关用来决定是否开启日志记录、是否模拟弱网等这些完全不需要改动代码。用 Scheme 管理环境还有一个隐藏的好处它可以对接不同的数据源。比如开发环境的 Scheme 指向本地 Mock 服务测试环境的 Scheme 指向测试服务器发布环境的 Scheme 指向线上服务器。这些差异全部在 Scheme 和 xcconfig 里体现代码层面看不到任何环境相关的代码这对团队协作质量和代码可读性都是极大的提升。4. 实操过程从零到一落地一个规范化的 Project 管理方案4.1 基础设施搭建目录结构与 Workspace 的选型我在搭建一个新的 iOS 工程时会先做几件基础工作这几件事看起来不起眼但能决定后面的所有步骤是否顺利。首先是把项目从.xcodeproj升级为.xcworkspace。这个选择的意义在于后续要接入 CocoaPods 或者 Swift Package Manager 的时候Workspace 能统一管理主项目和各种依赖项目避免构建层面的循环依赖。即使你当前没有使用任何第三方的包管理器我也建议直接建成 Workspace 的形式因为这是为团队协作和后续集成预留的弹性。其次是目录结构的物理落地。我在磁盘上会按照第二小节提到的四层结构加上Configurations目录和Scripts目录组成一个整套的工程骨架ProjectName/ ├── App/ ├── Features/ ├── Core/ ├── Shared/ ├── Configurations/ ├── Scripts/ └── ProjectName.xcworkspace这个结构本身就是一个约定团队里的任何人看到目录名就知道代码该放哪里。这一步虽然是体力活但它是整个 Project 管理方案的地基。4.2 通过 Ruby 脚本自动生成多环境配置文件纯靠手工创建三个环境、三套 Target、三个 Scheme不仅效率低而且容易遗漏配置。我通常会写一个小脚本来自动化生成这些配置。这里我以 Ruby 为例但其实用 Shell 或者 Python 也可以关键是把过程自动化。我需要先定义一组环境变量然后生成三份 xcconfig 文件。下面是一个简化的脚本逻辑environments { Dev { API_BASE_URL https://dev.example.com, LOG_LEVEL verbose }, Staging { API_BASE_URL https://staging.example.com, LOG_LEVEL info }, Release { API_BASE_URL https://api.example.com, LOG_LEVEL error } } common_config ~COMMON PRODUCT_NAME MyApp IPHONEOS_DEPLOYMENT_TARGET 13.0 SWIFT_VERSION 5.0 COMMON File.write(Configurations/Common.xcconfig, common_config) environments.each do |env_name, settings| content ~CONFIG #include Common.xcconfig API_BASE_URL #{settings[API_BASE_URL]} LOG_LEVEL #{settings[LOG_LEVEL]} CONFIG File.write(Configurations/#{env_name}.xcconfig, content) end脚本跑完之后Configurations目录下会自动生成四个文件。注意Common 和三个环境各自的内容分得很清楚。这样即使以后要加一个新的环境比如针对某个大客户的定制环境也只需要在脚本里多定义一组键值对重新跑一遍即可。脚本化最大的好处是可重复。用 Xcode 面板手动配置很容易出现“这个环境少了某个配置那个环境多了一个参数”的问题。而脚本化的配置生成保证每次生成的配置是一致的差异只来源于预期的环境差异。4.3 App Target 的配置与多环境 Scheme 的创建有了 xcconfig 文件之后就需要将它们与 Target 和 Scheme 关联起来。我通常是在 Xcode 中创建好 Target然后在 Build Settings 里把Configuration指到对应的 xcconfig 文件再将 Target 的 Build Configuration 数目调整为三个环境。有一个细节值得特别提醒很多入门教程或者懒人做法会直接让AppDelegate通过判断Bundle.main里的某些键值来区分环境这种做法虽然能用但绝对不推荐。正确的思路是在代码中不要写任何环境判断逻辑而是通过 Info.plist 或者编译常量来读取当前环境的基础配置。我之前提到的 xcconfig 中的API_BASE_URL就是放下这一个层面——编译时已经决定了当前工程所属的环境代码只是被动读取。Scheme 的创建也是类似的思路。我通常会为三种环境各创建一个 SchemeMyApp-DevBuild Configuration 指向 DevRun 和 Test 都使用 Debug。MyApp-StagingBuild Configuration 指向 StagingRun 也使用 Debug因为 Staging 一般用于测试同学的远程调试。MyApp-ReleaseBuild Configuration 指向 ReleaseArchive 只允许使用 Release。这里有一个坑Scheme 创建时默认生成的顺序可能不是我们想要的需要手动在 Xcode 中调整或者通过脚本统一生成 Shared Scheme。如果团队人多我更建议把 Scheme 生成脚本也纳入自动化流程保证每个成员检出的工程里的 Scheme 都是同一套。4.4 依赖管理的选型与落位CocoaPods与Swift Package Manager依赖管理的选型是 Project 管理里绕不开的话题。我在这两种工具之间有过反复的切换最后沉淀下来的经验是不用刻意追求“全用 SPM”或者“全用 CocoaPods”而是看在你的实际场景里哪个更可靠。我个人目前的策略是优先使用 SPM因为它是系统原生支持不需要额外的安装和构建步骤但是当某个第三方库的版本、二进制兼容性、或者某些需要修改源码的场景确实得用 CocoaPods 时我也不会排斥。如果是偏向使用 CocoaPods 的场景我会在 Podfile 里明确指定使用use_frameworks!并区分静态和动态。具体选择取决于依赖之间的兼容性。这里我不展开讲但要提醒的是无论你使用哪种依赖管理方式都要保证 Podfile 的变更尽量通过代码评审因为 Podfile 的变化背后往往隐含了版本升级或者架构调整蕴含的风险比代码变更还要大。另外在 Workspace 里引入依赖时我会专门建立一个Vendor目录用来存放需要手动集成、不能通过包管理器引入的第三方库。比如一些闭源厂商的 SDK需要通过 framework 拖拽进来的我会在这里保留一个副本并写明版本号和来源避免团队里谁都不知道某个 framework 是从哪个版本、哪个渠道引入的。4.5 构建性能优化从 Shared Build 到脚本化说到 Project 管理构建速度是绕不开的话题。iOS 工程的编译时间会随着业务规模的膨胀而指数级增长到了后期一个全量编译可能要等五分钟以上这对团队开发效率的拖累非常明显。我在实际项目中采取的优化手段包括开启新构建系统并严格使用静态库方式组织内部模块减少动态库的链接开销。打开Build Active Architecture Only在 Debug 模式下设置为 YES这样模拟器调试时只编译当前的架构显著加快编译速度。利用脚本预生成某些代码比如配置文件的生成、本地化字符串的扫描等避免 Xcode 在每次构建时重复计算。把较大的资源文件按需加载不要一股脑放进 App Bundle尤其是地图资源、视频资源等既拖慢构建速度又增大包体。这些手段的落地很多都要依赖 Project 层面的配置。所以我在讲 Project 管理时总是会提一句构建性能优化也是 Project 管理的一部分不要等到工程卡得不行了才回过头来做。5. 常见问题与排查技巧实录5.1 Build Settings 被 Xcode 面板覆盖的问题这是最容易被坑到的一个问题。我们在 xcconfig 里设置了环境变量然后某个同事在 Xcode 的 Build Settings 面板里点了某个选项点了之后这个设置就变成了“显式设置”优先级高于 xcconfig 文件。结果就是xcconfig 里配置了半天面板里的值反而成了真正生效的值而且这种覆盖是非常隐蔽的Xcode 里也没有明显的提示。我的排查技巧很简单看到 Build Settings 里某个配置项的字号是黑色的说明它是被显式覆盖过的如果是灰色说明它继承自工程或 xcconfig。当你需要确认某个配置的实际生效值可以选中 Target 的某个 Build Configuration然后看右侧的“Level”面板那里会列出每一个配置项的来源层级。遇到这种情况我的一般判断顺序是先检查 xcconfig 文件的内容再在面板里搜索相同的配置项看是否有显式值。5.2 Scheme 文件冲突导致的环境错乱当团队使用 Shared Scheme 时Scheme 文件会被保存在.xcscheme目录下并纳入版本管理。人多手杂容易出现两种典型的冲突一种是有人不小心修改了 Scheme 中 Run 的 Build Configuration把 Dev 的 Scheme 切到了 Release另一种是合并分支时 Scheme 文件产生了冲突但某个人直接把冲突的一方保留导致环境配置被另一个人的本地修改覆盖。这个问题没有一个完美的一键解决方案我能给的建议是把 Scheme 文件的变更当成代码变更来看待每次合并冲突时要仔细看清楚确认BuildConfiguration这个元素没有被误改。同时我建议在 CI 的脚本里加一道校验检查各个 Scheme 的BuildConfiguration是否与预期一致不一致就直接报警。这样就能把人工操作的风险降到最低。5.3 多 Target 下资源文件重复导致的包体增大把代码拆成多个 Target 之后一个常见的坑是资源文件的重复打包。比如你把某个图片资源同时添加到了主 Target 和某个尺寸较大的扩展 Target那么这份资源就会在最终产物里出现两份直接增大 App 的体积。处理这个问题的核心思路是定位。我在排查这类问题时会先在构建日志中搜索重复资源的相关警告或者在产物包中查看资源文件的实际大小判断哪些资源被多次打包。如果资源确实需要在多个 Target 中使用我建议把它们提取到一个独立的资源 Bundle 中由订阅者 Target 统一引用这样既避免了重复又保持了资源的集中管理。如果使用场景只是扩展组件和主 App 共享某几个图标我更推荐使用Asset Catalog的按需分配功能而不是把整份资源全部复制到多个 Target。5.4 自定义脚本导致的构建顺序问题Project 管理里经常会用到 Build Phase 的自定义脚本比如版本号自动递增、Info.plist 预处理、构建产物上传等。脚本虽然方便但如果对构建顺序没有足够的理解很容易写出有隐患的步骤。我记得踩过的一个坑是在某个模块的脚本里调用了 CocoaPods 生成的脚本并联到主工程之后导致脚本在依赖库的编码完成之前被调用自然就找不到依赖库的头文件。我的建议是这样自定义脚本尽量放在 Build Phase 序列的最后一段避免干预编译和连接的正常流程。凡是需要读取其他 Target 构建产物的步骤必须考虑 Target 依赖关系确保脚本在依赖产出之后再执行。如果脚本中有任何环境变量的获取最好在脚本开头通过set -u和set -e加上严格模式一旦变量不存在就立刻报错而不是等脚本跑到一半才失败。5.5 多环境切换后出现的“Data Race”和缓存问题切换环境时因为代码中读到的配置不同了一些模块会出现本地缓存或者状态未重置的问题。最常见的是用户登录态的缓存你在 Dev 环境登入了切到 Staging 环境后因为本地缓存还在新环境依旧拿着旧的 token 去请求结果各种 401 和缓存错乱。我的处理方式比较明确每个环境的沙盒命名空间必须完全隔离不要共用同一个本地数据库或者偏好设置存储区。这可以通过在代码中根据Bundle Identifier或者某个人为定义的编译常量来生成存储路径实现。如果在切换环境后遇到这类诡异问题第一排查思路就是看本地存储的路径是否随环境发生了变化。这个操作在具体实现上很简单但很多人就是容易忽略。多环境不是简单地把接口地址换掉它是从网络、存储、日志到调试工具链的全链路隔离任何一环没有隔离到位排查起来都会非常痛苦。6. 工具链与团队协作把 Project 管理变成可审查的资产6.1 用脚本和模板固化工程规范Project 管理最大的敌人是“手动”。我见过不少团队定了一堆规范但每次新建模块、新建 Target 的时候都是手动在 Xcode 里点来点去结果规范就慢慢变形了。我在项目管理里常做的一件事就是把这些规范写成脚本或者 Xcode 模板让团队成员在“使用”的过程中天然遵守规范。比如在创建新的业务模块时我会提供一个脚本生成统一的模块目录结构、一个基础的类文件、以及对应的测试 Target 需要的文件。团队只需执行一行命令就能得到一个结构完整的模块骨架而不需要手动建目录、建文件、拖文件进 Xcode。这样看起来多花了一点准备时间但实际上为团队省下了大量的重复劳动也让工程结构保持了高度的一致。Xcode 的模板系统也值得做。你可以自定义File Template让团队在新建文件时默认就选到正确的模板里面的基础框架代码已经写好。模板和脚本共同起作用Project 管理才能从“约定俗成”变成“默认如此”。6.2 把 Project 文件的变更纳入代码评审project.pbxproj文件是 Xcode 工程配置的核心但它是一个旧式格式的文件文本可读性比较差遇到 merge conflict 时也很让人头疼。我的经验是这个文件应该被当作代码一样评审而不只是“顺手提交”。在评审的时候重点看这几项文件引用的路径是否正确Target 归属是否正确新增的脚本阶段是否合理Build Phases 的顺序有没有被打乱。特别是当某次提交同时涉及 xcconfig 修改、Target 修改、代码修改时这个评审重要性会成倍上升。还有一点多人同时改project.pbxproj的冲突处理我不建议依赖自动 merge。最好能约定配置文件变更尽量由指定的人统一处理其他人不要横插一手不然最终的合并产物可能非常诡异排查起来让人抓狂。6.3 CI/CD 中的 Project 管理要点在 CI/CD 流程中Project 管理同样扮演重要角色。构建机上面如果不做任何预配置直接xcodebuild会默认使用工程里的设置的 Scheme 和 Configuration。如果你在本地能构建成功但在 CI 上构建失败很大概率是 CI 环境与本地环境存在差异证书的配置、描述文件的可见性、依赖安装的顺序、甚至 Ruby 版本不同都会导致构建结果不一致。我的建议是让 CI 完全消费工程里已有的配置而不是在 CI 配置里再写死一套环境。具体来说就是确保工程里有足够完整的 Shared Scheme保证 CI 可以直接用xcodebuild -workspace xxx -scheme AppRelease的方式构建不需要任何人手动维护Xcode的图形界面配置。另外上传测试包或发布包之前可以在 CI 阶段写一个脚本对最终生成的 ipa 里的 Info.plist 做校验确认环境标识、版本号、证书信息等关键参数符合预期。这一步非常有效能直接阻断绝大部分由于人为配置失误导致的构建事故。7. 踩坑复盘与经验沉淀最后再分享几个我踩过比较有代表性的坑以及对应的复盘结论。第一个坑是关于 xcconfig 的路径相对性。我最初把Common.xcconfig放在一个子目录然后引用了另一个目录下的文件结果 Xcode 一直报错找不到配置排了半天才发现#include的路径不支持变量拼接我只好把所有配置文件统一放在同一个目录下才解决问题。这个经历让我养成了一个习惯所有的配置文件路径尽量只使用相对当前文件的位置这样工程迁到任何路径都能正常工作。第二个坑是 Scheme 的 Archive 配置。早期我让 Staging 的 Scheme 也允许 Archive结果有一次发布流程误操作把 Staging 的包当成了生产包上传。虽然最终没有造成事故但着实惊出一身冷汗。从那以后我明确规定 Archive 只允许 Release 配置并在 CI 里做了硬校验杜绝了这类事件再次发生。第三个坑是关于依赖管理的混用。某个第三方库同时支持 SPM 和 CocoaPods我为了省事在 SPM 和 CocoaPods 里都引入了它结果出现了一段重复代码、两份二进制编译时不报错但运行时出现奇怪的符号冲突。排查了很久才定位到最后把其中一个来源移除才解决。这个案例让我认识到依赖管理一定要有明确的边界不能爱怎么加就怎么加。其实做 Project 管理和做代码架构是一脉相承的。代码架构是逻辑层面约束依赖和模块而 Project 管理是构建层面、文件层面约束依赖和模块两者互为表里。一个健康的工程应该是打开目录结构就能大概猜到代码归属看到 Scheme 列表就知道有哪几套环境打开 xcconfig 就知道环境差异在哪里。当你的工程达到这种状态无论是来新同学、走了老同学还是业务大规模扩展、要接新的 CI/CD 工具整个团队都会轻松很多。这套 Project 管理的方法我在不同体量的项目里验证过多次从只有两个人的小项目到十几个人的中型团队都拿到了正向反馈。小团队它能让起步更规范不欠技术债大团队它能让工程结构的维护变得可控、可评审、可扩展。如果你正面临工程结构混乱、环境切换困难、构建越来越慢的问题不妨按照这篇文章的思路从目录分层、xcconfig、Scheme 规划开始一步步把 Project 管理理顺。这些都是眼前有投入、长期有回报的事情。 
长河君 · 2026/10/15 20:02:07 · 阅读 1.2k Project 管理也是 iOS 架构：工程结构、Target 与 Scheme 实践
1. 为什么说 Project 管理本身就是一种架构聊到 iOS 架构很多人第一反应是 MVC、MVVM、VIPER 这些代码层的设计模式或者组件化、模块化这样的技术方案。但我在一线待了这么多年有个越来越强烈的体会真正决定一个项目能不能长期健康迭代的往往不是某个 ViewModel 怎么写而是工程结构顶层那一层——Project 管理。这层要是乱了后面再怎么重构代码都是治标不治本。Project 管理这个词听起来很基础好像就是把文件拖进 Xcode、建几个文件夹、加几个 Target 而已。但实际上它承载的东西非常多代码的物理组织方式、构建配置的继承关系、多环境的切换方案、资源文件的归属、依赖的引入方式、编译的顺序与依赖、甚至团队协作时的冲突边界。这些如果从一开始就没设计好等业务膨胀到几十万行代码的时候再想调整就不是改几天代码的事情了而是要把整个工程推倒重来的级别。我见过太多这样的场景某个业务模块的开发同学为了提一个小小的需求要在一个几万行的 Xcode 工程里翻半天才能找到对应的文件或者明明只是换个测试环境的接口地址却要手动改多处配置一不小心就漏改一处导致线上环境串了测试环境的数据。这些问题看起来像是“管理不规范”本质上是 Project 层面缺少架构设计。所以这篇文章我想认真聊聊iOS 项目里的 Project 管理到底该怎么做。我不会只讲概念而是把我在实际项目中踩过的坑、验证过的做法、以及背后的思考逻辑都摊开来讲。内容会覆盖分层设计、Target 与 Scheme 的规划、Build Settings 的下沉、xcconfig 的应用、依赖管理的选型以及构建性能的优化。无论你是在维护一个几万行的老项目还是准备从零搭建一个新工程的基建这篇文章都应该能给你一些可以直接落地的参考。2. 整体设计思路工程结构先于代码结构2.1 先分清“物理目录”和“逻辑 Target”我在重构某个老项目的时候第一步不是动代码而是把整个工程的文件结构画出来然后问团队一个问题我们现在有几层这里说的“层”不是 MVVM 那种代码分层而是物理目录和 Target 层面的分层。我通常会把一个 iOS 工程的目录结构拆成四个区域App 入口层只放 AppDelegate、SceneDelegate、主 Window 的配置、全局的启动逻辑。这一层要尽量薄不承载任何业务。Feature 业务层按业务域拆分的模块比如登录、首页、订单、消息。每个模块内部再按照自己的需求去组织互不依赖。Core 基础层网络、存储、日志、埋点、路由、工具类。这一层不依赖任何业务模块。Shared 共享层资源文件、第三方库的封装、通用的 UI 组件。为什么要这么分因为 Project 管理最大的价值之一就是通过物理边界来强制约束依赖关系。如果目录只有一个平铺的 Main 文件夹那代码的归属就是靠自觉久而久之必然出现各种跨层调用——比如某个业务页面直接操作数据库或者某个工具类里硬编码了业务逻辑。而如果你在 Project 规划阶段就把目录结构按层级铺好并且通过 Target、文件归属这些硬性手段来约束团队每个人在新建文件的时候就会下意识地想这个文件应该放在哪一层、属于哪个模块。这种潜移默化的影响比代码评审时的一句“你这个不该放这里”要有效得多。实际项目中我会立刻把这些目录建出来哪怕里面是空的。空目录在磁盘上存在就行Xcode 中可以不引用但团队约定俗成后新文件就有了默认的落位。2.2 从单 Target 到多 Target 的演进路线很多 iOS 项目都是从单 Target 起步的这在初期完全没问题。但当项目进入第二个阶段也就是需要区分不同环境开发、测试、生产或者需要做独立的功能模块比如主机 App 和扩展 App的时候单 Target 就会开始拖后腿。我见过最典型的做法是在单个 Target 里通过编译宏或者运行时判断来区分环境。比如在代码里写#if DEBUG、或者定义一个kIsTestEnvironment来切换接口地址。这能跑但是问题不少首先所有环境的代码都在同一个二进制里面不上线也能通过某些手段切到测试环境其次配置逻辑散落在代码中新同学根本搞不清楚哪些是当前环境生效的再者如果你要做严格的发布流程希望测试包和生产包在构建层面就隔离这种运行时切换的做法很难满足。所以我更推荐在工程结构上直接按 Target 拆分。从单 Target 到多 Target 的演进路径我建议分三步走第一步把通用代码和配置抽取出来保证它们不依赖任何环境变量。第二步建立基础的AppDev、AppStaging、AppProd三个 Target它们共用同一份源代码文件但各自的 Build Settings 和 Info.plist 完全独立。第三步把不同环境的差异逐步从代码中剥离全部收拢到 Build Settings 和配置文件里。这个方案的优点在于环境差异在编译期就固定下来了。开发包用的是开发环境的配置生产包用的是生产环境的配置构建产物互不干扰。它带来的额外好处是CI/CD 的流程也可以针对不同 Target 走不同的签名配置和发布流程。2.3 Build Settings 是项目里的“隐藏架构”我在 Code Review 的时候最怕看到的信息之一就是在某个 Xcode 的 Build Settings 面板里硬塞了一堆自定义配置。比如有人直接把接口地址写在Other Linker Flags里面或者用Preprocessor Macros塞一堆业务开关。这样的配置一旦多了工程的可维护性就会急剧下降因为 Build Settings 的配置项是全局性的、容易被覆盖的而且不同 Target 之间的配置关系非常容易混乱。正确的做法是让 Build Settings 成为一个“可编程”的配置文件体系。也就是说不要依赖 Xcode 面板里的图形化界面来管理配置而是把配置项下沉到 xcconfig 文件里通过文件的继承关系来体系化地管理。这就像把原来散落在各个角落的常量定义统一抽到一个配置类里。Build Settings 的层级关系天然适合做这件事工程级别的配置在最底层Target 级别的配置覆盖上层Scheme 用来决定使用哪一套配置。我实际操作中的做法是这样的建一个Configurations目录专门存放所有的 xcconfig 文件。针对每个环境建立独立的Dev.xcconfig、Staging.xcconfig、Release.xcconfig。这些文件通过#include引入公共配置让三个环境的配置共享大部分内容差异项只在各自的文件里覆盖。这样设计的核心价值在于所有环境差异全部集中到几个配置文件里排查环境和构建相关的问题时只要打开这几个文件一切一目了然。不需要在 Xcode 的 Build Settings 面板里翻几页才能找到某个配置项也不需要担心某个人手滑改了全局配置。3. 核心细节解析xcconfig、Target 与 Scheme 的三位一体3.1 xcconfig 的正确用法与常见误区xcconfig 文件本质上是一个基于键值对的配置文件语法很简单但它背后支持的继承机制才是真正让它强大的地方。#include指令可以引入其他配置文件从而实现配置的继承与覆盖。我在项目中通常会建立这样一组文件Configurations/ ├── Common.xcconfig ├── Dev.xcconfig ├── Staging.xcconfig └── Release.xcconfigCommon.xcconfig存放所有环境共享的配置比如代码签名用的证书名、最低系统版本、某些通用的编译选项。三个环境各自的文件则通过#include Common.xcconfig引用基础配置再定义自己独有的项比如 API Base URL、日志级别、统计开关等。有一个关键点需要特别注意xcconfig 中的#include路径是相对于当前文件所在目录的而且路径中不能使用变量来构造比如#include $(SRCROOT)/...这种写法是行不通的。我刚开始用的时候就踩过这个坑后来干脆把所有 xcconfig 文件都放在同一个目录下用相对路径引用省掉了很多麻烦。另外一个常见的误区是试图用 xcconfig 覆盖所有 Build Settings。但有些设置是无法通过 xcconfig 配置的比如Info.plist文件的路径、某些 Target 的常规设置等这些只能在 Xcode 面板里配置。所以我的原则是凡是能在 xcconfig 里配置的全部下沉不能在 xcconfig 里配置的在面板里设置完成后一定要加上注释说明为什么这样设置并同步到工程的文档中。3.2 Target 的划分策略一个主 Target 加若干个子 Target讲到 Target 划分我见过两种极端的做法一种是全局只有一个 Target什么功能都往里面塞另一种是把每个功能模块都单独建一个 Target结果 Target 数量多达几十个编译的时候依赖关系极其复杂每次 Build 都要经历漫长的链接过程。这两种做法我都不推荐。合理的策略是主 Target 只保留一个它是最终 App 的二进制目标。其余的子 Target 按需要建立主要包括三类扩展 Target比如通知扩展、Widget 扩展、Share 扩展。这些扩展虽然最终会打进主 App 的二进制里但它们在逻辑上是独立的进程必须独立成 Target。框架 Target如果你做的是模块化开发可以把各个独立模块拆成 framework Target。这里需要注意动态框架会增加启动时链接的开销而静态库则没有这个问题。我建议小团队的项目优先使用静态库等模块数量多到一定程度再考虑动态库。测试 Target包括单元测试和 UI 测试的 Target。测试 Target 应该跟主 Target 保持完全一致的配置环境否则很容易出现测试环境能跑、线上环境崩掉的问题。我把这个策略总结下来就是Target 的个数是有上限的能共享代码的文件一定要共享不要因为某个文件只属于某个功能模块就把它单独拉出去建 Target。Target 多了工程文件冲突的频率会急剧上升。所谓某个功能模块独立成 Target在 Web 前端可以做微前端但在 iOS 的世界里二进制层面的模块独立性是以一定的复杂度为代价的。除非团队规模和业务复杂度真的到了不拆不行的地步否则我建议先用目录分层、再用静态库、最后才上动态库一步步来。3.3 Scheme 是环境切换的“总开关”Scheme 在 Xcode 里是最容易被忽视、但也是环境切换最重要的一环。很多人直接使用 Xcode 默认生成的 Scheme然后通过修改 Target 的 Build Configuration 来切换环境这样也可以但每次切换环境都需要手动操作还容易出错。我的建议是为每个环境维护一个独立的 Scheme并且把 Scheme 之间的差异通过 Shared Scheme 提交到版本库中。这样团队每个人检出的代码都已经带着所有环境的 Scheme不需要各自手动创建。Scheme 里除了管理 Build Configuration还有三个地方值得注意Run 和 Test 的配置需要保证 Debug 环境下测试和运行使用的是同一套 Build Configuration否则会出现测试结果和生产环境不一致的情况。Archive 的配置只允许使用 Release 配置。这个最好在命名的时候就稍微规范一点比如AppDev、AppStaging、AppRelease这样在选择的时候不容易混淆。启动参数和环境变量。Scheme 可以配置启动时的环境变量这比在代码里硬编码强太多。我在本地调试的时候通常会通过 Scheme 传入一个开关用来决定是否开启日志记录、是否模拟弱网等这些完全不需要改动代码。用 Scheme 管理环境还有一个隐藏的好处它可以对接不同的数据源。比如开发环境的 Scheme 指向本地 Mock 服务测试环境的 Scheme 指向测试服务器发布环境的 Scheme 指向线上服务器。这些差异全部在 Scheme 和 xcconfig 里体现代码层面看不到任何环境相关的代码这对团队协作质量和代码可读性都是极大的提升。4. 实操过程从零到一落地一个规范化的 Project 管理方案4.1 基础设施搭建目录结构与 Workspace 的选型我在搭建一个新的 iOS 工程时会先做几件基础工作这几件事看起来不起眼但能决定后面的所有步骤是否顺利。首先是把项目从.xcodeproj升级为.xcworkspace。这个选择的意义在于后续要接入 CocoaPods 或者 Swift Package Manager 的时候Workspace 能统一管理主项目和各种依赖项目避免构建层面的循环依赖。即使你当前没有使用任何第三方的包管理器我也建议直接建成 Workspace 的形式因为这是为团队协作和后续集成预留的弹性。其次是目录结构的物理落地。我在磁盘上会按照第二小节提到的四层结构加上Configurations目录和Scripts目录组成一个整套的工程骨架ProjectName/ ├── App/ ├── Features/ ├── Core/ ├── Shared/ ├── Configurations/ ├── Scripts/ └── ProjectName.xcworkspace这个结构本身就是一个约定团队里的任何人看到目录名就知道代码该放哪里。这一步虽然是体力活但它是整个 Project 管理方案的地基。4.2 通过 Ruby 脚本自动生成多环境配置文件纯靠手工创建三个环境、三套 Target、三个 Scheme不仅效率低而且容易遗漏配置。我通常会写一个小脚本来自动化生成这些配置。这里我以 Ruby 为例但其实用 Shell 或者 Python 也可以关键是把过程自动化。我需要先定义一组环境变量然后生成三份 xcconfig 文件。下面是一个简化的脚本逻辑environments { Dev { API_BASE_URL https://dev.example.com, LOG_LEVEL verbose }, Staging { API_BASE_URL https://staging.example.com, LOG_LEVEL info }, Release { API_BASE_URL https://api.example.com, LOG_LEVEL error } } common_config ~COMMON PRODUCT_NAME MyApp IPHONEOS_DEPLOYMENT_TARGET 13.0 SWIFT_VERSION 5.0 COMMON File.write(Configurations/Common.xcconfig, common_config) environments.each do |env_name, settings| content ~CONFIG #include Common.xcconfig API_BASE_URL #{settings[API_BASE_URL]} LOG_LEVEL #{settings[LOG_LEVEL]} CONFIG File.write(Configurations/#{env_name}.xcconfig, content) end脚本跑完之后Configurations目录下会自动生成四个文件。注意Common 和三个环境各自的内容分得很清楚。这样即使以后要加一个新的环境比如针对某个大客户的定制环境也只需要在脚本里多定义一组键值对重新跑一遍即可。脚本化最大的好处是可重复。用 Xcode 面板手动配置很容易出现“这个环境少了某个配置那个环境多了一个参数”的问题。而脚本化的配置生成保证每次生成的配置是一致的差异只来源于预期的环境差异。4.3 App Target 的配置与多环境 Scheme 的创建有了 xcconfig 文件之后就需要将它们与 Target 和 Scheme 关联起来。我通常是在 Xcode 中创建好 Target然后在 Build Settings 里把Configuration指到对应的 xcconfig 文件再将 Target 的 Build Configuration 数目调整为三个环境。有一个细节值得特别提醒很多入门教程或者懒人做法会直接让AppDelegate通过判断Bundle.main里的某些键值来区分环境这种做法虽然能用但绝对不推荐。正确的思路是在代码中不要写任何环境判断逻辑而是通过 Info.plist 或者编译常量来读取当前环境的基础配置。我之前提到的 xcconfig 中的API_BASE_URL就是放下这一个层面——编译时已经决定了当前工程所属的环境代码只是被动读取。Scheme 的创建也是类似的思路。我通常会为三种环境各创建一个 SchemeMyApp-DevBuild Configuration 指向 DevRun 和 Test 都使用 Debug。MyApp-StagingBuild Configuration 指向 StagingRun 也使用 Debug因为 Staging 一般用于测试同学的远程调试。MyApp-ReleaseBuild Configuration 指向 ReleaseArchive 只允许使用 Release。这里有一个坑Scheme 创建时默认生成的顺序可能不是我们想要的需要手动在 Xcode 中调整或者通过脚本统一生成 Shared Scheme。如果团队人多我更建议把 Scheme 生成脚本也纳入自动化流程保证每个成员检出的工程里的 Scheme 都是同一套。4.4 依赖管理的选型与落位CocoaPods与Swift Package Manager依赖管理的选型是 Project 管理里绕不开的话题。我在这两种工具之间有过反复的切换最后沉淀下来的经验是不用刻意追求“全用 SPM”或者“全用 CocoaPods”而是看在你的实际场景里哪个更可靠。我个人目前的策略是优先使用 SPM因为它是系统原生支持不需要额外的安装和构建步骤但是当某个第三方库的版本、二进制兼容性、或者某些需要修改源码的场景确实得用 CocoaPods 时我也不会排斥。如果是偏向使用 CocoaPods 的场景我会在 Podfile 里明确指定使用use_frameworks!并区分静态和动态。具体选择取决于依赖之间的兼容性。这里我不展开讲但要提醒的是无论你使用哪种依赖管理方式都要保证 Podfile 的变更尽量通过代码评审因为 Podfile 的变化背后往往隐含了版本升级或者架构调整蕴含的风险比代码变更还要大。另外在 Workspace 里引入依赖时我会专门建立一个Vendor目录用来存放需要手动集成、不能通过包管理器引入的第三方库。比如一些闭源厂商的 SDK需要通过 framework 拖拽进来的我会在这里保留一个副本并写明版本号和来源避免团队里谁都不知道某个 framework 是从哪个版本、哪个渠道引入的。4.5 构建性能优化从 Shared Build 到脚本化说到 Project 管理构建速度是绕不开的话题。iOS 工程的编译时间会随着业务规模的膨胀而指数级增长到了后期一个全量编译可能要等五分钟以上这对团队开发效率的拖累非常明显。我在实际项目中采取的优化手段包括开启新构建系统并严格使用静态库方式组织内部模块减少动态库的链接开销。打开Build Active Architecture Only在 Debug 模式下设置为 YES这样模拟器调试时只编译当前的架构显著加快编译速度。利用脚本预生成某些代码比如配置文件的生成、本地化字符串的扫描等避免 Xcode 在每次构建时重复计算。把较大的资源文件按需加载不要一股脑放进 App Bundle尤其是地图资源、视频资源等既拖慢构建速度又增大包体。这些手段的落地很多都要依赖 Project 层面的配置。所以我在讲 Project 管理时总是会提一句构建性能优化也是 Project 管理的一部分不要等到工程卡得不行了才回过头来做。5. 常见问题与排查技巧实录5.1 Build Settings 被 Xcode 面板覆盖的问题这是最容易被坑到的一个问题。我们在 xcconfig 里设置了环境变量然后某个同事在 Xcode 的 Build Settings 面板里点了某个选项点了之后这个设置就变成了“显式设置”优先级高于 xcconfig 文件。结果就是xcconfig 里配置了半天面板里的值反而成了真正生效的值而且这种覆盖是非常隐蔽的Xcode 里也没有明显的提示。我的排查技巧很简单看到 Build Settings 里某个配置项的字号是黑色的说明它是被显式覆盖过的如果是灰色说明它继承自工程或 xcconfig。当你需要确认某个配置的实际生效值可以选中 Target 的某个 Build Configuration然后看右侧的“Level”面板那里会列出每一个配置项的来源层级。遇到这种情况我的一般判断顺序是先检查 xcconfig 文件的内容再在面板里搜索相同的配置项看是否有显式值。5.2 Scheme 文件冲突导致的环境错乱当团队使用 Shared Scheme 时Scheme 文件会被保存在.xcscheme目录下并纳入版本管理。人多手杂容易出现两种典型的冲突一种是有人不小心修改了 Scheme 中 Run 的 Build Configuration把 Dev 的 Scheme 切到了 Release另一种是合并分支时 Scheme 文件产生了冲突但某个人直接把冲突的一方保留导致环境配置被另一个人的本地修改覆盖。这个问题没有一个完美的一键解决方案我能给的建议是把 Scheme 文件的变更当成代码变更来看待每次合并冲突时要仔细看清楚确认BuildConfiguration这个元素没有被误改。同时我建议在 CI 的脚本里加一道校验检查各个 Scheme 的BuildConfiguration是否与预期一致不一致就直接报警。这样就能把人工操作的风险降到最低。5.3 多 Target 下资源文件重复导致的包体增大把代码拆成多个 Target 之后一个常见的坑是资源文件的重复打包。比如你把某个图片资源同时添加到了主 Target 和某个尺寸较大的扩展 Target那么这份资源就会在最终产物里出现两份直接增大 App 的体积。处理这个问题的核心思路是定位。我在排查这类问题时会先在构建日志中搜索重复资源的相关警告或者在产物包中查看资源文件的实际大小判断哪些资源被多次打包。如果资源确实需要在多个 Target 中使用我建议把它们提取到一个独立的资源 Bundle 中由订阅者 Target 统一引用这样既避免了重复又保持了资源的集中管理。如果使用场景只是扩展组件和主 App 共享某几个图标我更推荐使用Asset Catalog的按需分配功能而不是把整份资源全部复制到多个 Target。5.4 自定义脚本导致的构建顺序问题Project 管理里经常会用到 Build Phase 的自定义脚本比如版本号自动递增、Info.plist 预处理、构建产物上传等。脚本虽然方便但如果对构建顺序没有足够的理解很容易写出有隐患的步骤。我记得踩过的一个坑是在某个模块的脚本里调用了 CocoaPods 生成的脚本并联到主工程之后导致脚本在依赖库的编码完成之前被调用自然就找不到依赖库的头文件。我的建议是这样自定义脚本尽量放在 Build Phase 序列的最后一段避免干预编译和连接的正常流程。凡是需要读取其他 Target 构建产物的步骤必须考虑 Target 依赖关系确保脚本在依赖产出之后再执行。如果脚本中有任何环境变量的获取最好在脚本开头通过set -u和set -e加上严格模式一旦变量不存在就立刻报错而不是等脚本跑到一半才失败。5.5 多环境切换后出现的“Data Race”和缓存问题切换环境时因为代码中读到的配置不同了一些模块会出现本地缓存或者状态未重置的问题。最常见的是用户登录态的缓存你在 Dev 环境登入了切到 Staging 环境后因为本地缓存还在新环境依旧拿着旧的 token 去请求结果各种 401 和缓存错乱。我的处理方式比较明确每个环境的沙盒命名空间必须完全隔离不要共用同一个本地数据库或者偏好设置存储区。这可以通过在代码中根据Bundle Identifier或者某个人为定义的编译常量来生成存储路径实现。如果在切换环境后遇到这类诡异问题第一排查思路就是看本地存储的路径是否随环境发生了变化。这个操作在具体实现上很简单但很多人就是容易忽略。多环境不是简单地把接口地址换掉它是从网络、存储、日志到调试工具链的全链路隔离任何一环没有隔离到位排查起来都会非常痛苦。6. 工具链与团队协作把 Project 管理变成可审查的资产6.1 用脚本和模板固化工程规范Project 管理最大的敌人是“手动”。我见过不少团队定了一堆规范但每次新建模块、新建 Target 的时候都是手动在 Xcode 里点来点去结果规范就慢慢变形了。我在项目管理里常做的一件事就是把这些规范写成脚本或者 Xcode 模板让团队成员在“使用”的过程中天然遵守规范。比如在创建新的业务模块时我会提供一个脚本生成统一的模块目录结构、一个基础的类文件、以及对应的测试 Target 需要的文件。团队只需执行一行命令就能得到一个结构完整的模块骨架而不需要手动建目录、建文件、拖文件进 Xcode。这样看起来多花了一点准备时间但实际上为团队省下了大量的重复劳动也让工程结构保持了高度的一致。Xcode 的模板系统也值得做。你可以自定义File Template让团队在新建文件时默认就选到正确的模板里面的基础框架代码已经写好。模板和脚本共同起作用Project 管理才能从“约定俗成”变成“默认如此”。6.2 把 Project 文件的变更纳入代码评审project.pbxproj文件是 Xcode 工程配置的核心但它是一个旧式格式的文件文本可读性比较差遇到 merge conflict 时也很让人头疼。我的经验是这个文件应该被当作代码一样评审而不只是“顺手提交”。在评审的时候重点看这几项文件引用的路径是否正确Target 归属是否正确新增的脚本阶段是否合理Build Phases 的顺序有没有被打乱。特别是当某次提交同时涉及 xcconfig 修改、Target 修改、代码修改时这个评审重要性会成倍上升。还有一点多人同时改project.pbxproj的冲突处理我不建议依赖自动 merge。最好能约定配置文件变更尽量由指定的人统一处理其他人不要横插一手不然最终的合并产物可能非常诡异排查起来让人抓狂。6.3 CI/CD 中的 Project 管理要点在 CI/CD 流程中Project 管理同样扮演重要角色。构建机上面如果不做任何预配置直接xcodebuild会默认使用工程里的设置的 Scheme 和 Configuration。如果你在本地能构建成功但在 CI 上构建失败很大概率是 CI 环境与本地环境存在差异证书的配置、描述文件的可见性、依赖安装的顺序、甚至 Ruby 版本不同都会导致构建结果不一致。我的建议是让 CI 完全消费工程里已有的配置而不是在 CI 配置里再写死一套环境。具体来说就是确保工程里有足够完整的 Shared Scheme保证 CI 可以直接用xcodebuild -workspace xxx -scheme AppRelease的方式构建不需要任何人手动维护Xcode的图形界面配置。另外上传测试包或发布包之前可以在 CI 阶段写一个脚本对最终生成的 ipa 里的 Info.plist 做校验确认环境标识、版本号、证书信息等关键参数符合预期。这一步非常有效能直接阻断绝大部分由于人为配置失误导致的构建事故。7. 踩坑复盘与经验沉淀最后再分享几个我踩过比较有代表性的坑以及对应的复盘结论。第一个坑是关于 xcconfig 的路径相对性。我最初把Common.xcconfig放在一个子目录然后引用了另一个目录下的文件结果 Xcode 一直报错找不到配置排了半天才发现#include的路径不支持变量拼接我只好把所有配置文件统一放在同一个目录下才解决问题。这个经历让我养成了一个习惯所有的配置文件路径尽量只使用相对当前文件的位置这样工程迁到任何路径都能正常工作。第二个坑是 Scheme 的 Archive 配置。早期我让 Staging 的 Scheme 也允许 Archive结果有一次发布流程误操作把 Staging 的包当成了生产包上传。虽然最终没有造成事故但着实惊出一身冷汗。从那以后我明确规定 Archive 只允许 Release 配置并在 CI 里做了硬校验杜绝了这类事件再次发生。第三个坑是关于依赖管理的混用。某个第三方库同时支持 SPM 和 CocoaPods我为了省事在 SPM 和 CocoaPods 里都引入了它结果出现了一段重复代码、两份二进制编译时不报错但运行时出现奇怪的符号冲突。排查了很久才定位到最后把其中一个来源移除才解决。这个案例让我认识到依赖管理一定要有明确的边界不能爱怎么加就怎么加。其实做 Project 管理和做代码架构是一脉相承的。代码架构是逻辑层面约束依赖和模块而 Project 管理是构建层面、文件层面约束依赖和模块两者互为表里。一个健康的工程应该是打开目录结构就能大概猜到代码归属看到 Scheme 列表就知道有哪几套环境打开 xcconfig 就知道环境差异在哪里。当你的工程达到这种状态无论是来新同学、走了老同学还是业务大规模扩展、要接新的 CI/CD 工具整个团队都会轻松很多。这套 Project 管理的方法我在不同体量的项目里验证过多次从只有两个人的小项目到十几个人的中型团队都拿到了正向反馈。小团队它能让起步更规范不欠技术债大团队它能让工程结构的维护变得可控、可评审、可扩展。如果你正面临工程结构混乱、环境切换困难、构建越来越慢的问题不妨按照这篇文章的思路从目录分层、xcconfig、Scheme 规划开始一步步把 Project 管理理顺。这些都是眼前有投入、长期有回报的事情。