症状：TeamCity 代理已安装，Mac 构建仍可能无法连接、无法调度，或调用了不对的 Xcode。
最快解法：按“代理连接与授权 → 环境兼容 → Xcode 构建 → 真实启动方式下验收”逐项核对；四项都通过，才算完成 TeamCity macOS 构建代理部署。
这篇指南适合需要接入 Mac 构建节点的企业 IT 负责人，也适合处理代理授权、构建要求和任务路由的 TeamCity 管理员。
如果你负责 Xcode 流水线，还能据此建立可复核的上线记录，而不只是确认代理显示在线。
先分清代理处于哪种状态
安装成功，只代表代理文件已放到 Mac 上，不等于它已经接入服务器。排障时应先观察 TeamCity 管理界面中的代理状态，再结合 Mac 上的代理日志判断原因，避免把网络故障、配置错误和等待授权混为一谈。
| 现象 | 优先核对 | 处理方向 |
|---|---|---|
| 管理界面里找不到代理 | 进程是否运行；serverUrl 是否正确；Mac 到服务器的网络是否可达 |
先确认代理日志和服务器地址，再检查网络路径 |
| 代理出现在未授权列表 | 是否为团队预期接入的主机；代理名称和来源是否可识别 | 管理员核实主机身份后再授权 |
| 显示已连接但不能接任务 | 是否已授权、启用；代理是否符合构建要求 | 检查授权、启用状态和兼容性信息 |
| 代理在线但构建排队 | 构建配置要求是否与代理上报参数一致 | 定位具体不匹配项，调整要求或补齐依赖 |
TeamCity 代理会主动连接服务器，连接建成后再轮询待执行任务；通常不需要让服务器反向连入代理主机。若代理没有出现，先根据代理安装配置说明检查 Server 地址、协议和代理配置，并从代理端日志确认连接过程。这里的“能访问 TeamCity 网页”只能说明某种访问路径可用，不应代替代理实际连接验证。
TeamCity 将新代理标记为未授权，是平台接入许可的独立状态。管理员在管理界面核实代理对应的 Mac 后，再执行授权和启用；授权不会自动证明该机器已安装符合要求的 Xcode，也不会让不兼容的构建配置自动获得可调度代理。可参考代理状态与授权机制分别处理“已连接”“已授权”和“已启用”。
⚠️ 不要只记录“代理在线”。还要记下代理状态变化的时间、管理界面显示的名称，以及代理日志中与连接相关的记录；这样网络或权限问题再次发生时，才有可对照的证据。
第一阶段：安装后先验连接，不要急着改构建
从 TeamCity 管理界面取得代理安装包，在目标 Mac 上解压并准备 conf/buildAgent.properties。设置对应的 TeamCity Server 地址和便于识别的代理名称，再以计划用于构建的 macOS 用户启动代理。具体安装过程可对照TeamCity 代理安装文档。
| 接入选择 | 适合的情况 | 关键检查点 |
|---|---|---|
| 手动启动代理 | 初次安装、诊断连接、验证配置 | 进程是否启动；代理日志是否显示连接结果 |
| 登录后由 LaunchAgent 启动 | 构建任务运行在指定用户会话下 | 用户登录、文件归属、启动项和日志是否一致 |
| 仅按“机器重启”预期自动运行 | 只有实际验证了重启和登录策略后才采用 | 不要假设 LaunchAgent 等于无用户登录的系统服务 |
接下来在 TeamCity 的代理列表中确认它出现在预期状态。如果状态是未授权，先完成主机身份核验与授权；如果没有连接，回到 serverUrl、代理进程和网络路径逐项排除。JetBrains 的代理启动说明介绍了 macOS 的 LaunchAgent 路径；该路径的运行条件与手动在终端启动并不完全相同。
排查自动启动时，先确认启动命令是否执行，再查看代理进程和日志，区分“进程没有起来”与“进程起来了但连不上服务器”。按 JetBrains 文档配置时，要核对 buildAgent 目录及其文件是否归构建用户所有，并检查启动项是否位于该用户的 ~/Library/LaunchAgents/。如果构建依赖用户级环境或图形会话，还要按照团队实际的登录策略做重启试验，不能把该启动方式当成适用于所有任务的通用方案。
第二阶段：代理已连接，先让构建配置找到它
连接和授权完成后，仍可能出现“没有可用代理”或构建持续排队。此时不要先重装代理，先在构建配置的代理兼容性信息中查找不匹配项，再对照代理详情页的参数报告。TeamCity 的代理要求配置文档说明，构建要求会根据代理上报的参数判断该代理是否兼容；预定义代理参数说明可用于查找平台、架构和环境参数。
核对时按这个顺序走：
- 在构建配置的代理要求页面，确认平台、架构、环境变量和自定义参数等条件。
- 打开 Mac 代理的参数信息，确认它实际上报的值，而不是依据管理员对主机配置的预期推断。
- 找到具体不匹配项后，判断应该调整构建要求，还是在代理上安装对应工具或设置参数。
- 若安装了工具或更改了代理环境，等待代理更新其参数，再重新查看兼容性结果。
- 重新触发代表性构建，确认任务确实被分配到目标 Mac，而非只观察队列状态。
要求条件应能区分“可以执行该构建”的代理。例如，构建步骤需要某个 SDK 时，要确认代理确实报告了对应工具或参数；仅因代理运行 macOS，不能推断所有 Xcode 项目都能在其上执行。每次调整后都重新检查兼容性，避免留下一个表面在线、实际无法接单的节点。
第三阶段：Xcode 步骤成功启动，也要核对实际工具链
TeamCity 中的 Xcode 构建步骤会依赖 Mac 上可用的 Xcode 和相关工具。先核对代理上安装的 Xcode，再检查构建步骤里的项目或工作区、Scheme、目标平台及 Xcode 路径。可查看TeamCity 的 Xcode 构建步骤说明，对照该配置实际支持的字段与代理要求，不要依据旧配置猜测当前行为。
在 Mac 终端检查当前开发者目录：
xcode-select --print-path
xcodebuild -version
xcode-select --print-path用于查看当前命令行工具使用的开发者目录；若有多个 Xcode 安装，可以在构建步骤明确指定路径，或按团队策略切换默认版本。Apple 的命令行工具配置说明解释了查看和切换开发者目录的方法，Xcode 命令行工具参考说明了 xcodebuild 等工具的用途。
提醒：通过
xcode-select更改默认目录后，要确认 TeamCity 代理已经重新发现工具链。不能仅凭终端窗口能运行xcodebuild，就推定代理执行构建时看到的是同一环境。
使用实际流水线中的代表性项目做验证：选定项目或工作区、Scheme 和目标平台，运行团队真正需要的构建或测试动作，并检查构建日志与产物。若测试依赖模拟器或真实设备，模拟器构建通过不能代替物理设备验证；Apple 的模拟器与实体设备运行说明也指出，两类目标并不等同。具体 Xcode 版本和工具行为，应以团队当前安装环境及官方资料核实，不应从代理在线状态推断兼容性。
上线验收以端到端证据为准
在面向团队开放任务路由前，完成一轮完整试跑：由 TeamCity 触发构建，确认目标 Mac 被判为兼容并实际接单，再确认 Xcode 步骤使用预期工具链，最后检查产物和构建结果。验收记录可按下表保存，便于复查配置变更、连接故障和任务分配问题。
| 验收项 | 需要保存的证据 | 未通过时的回退 |
|---|---|---|
| 代理连接、授权、启用 | 管理界面状态与代理日志 | 先暂停构建路由，查配置、网络和授权 |
| 代理兼容目标配置 | 兼容性结果与相关参数 | 修正要求或安装依赖，复查后再试 |
| 使用预期 Xcode 执行 | 构建步骤设置、工具链检查与构建日志 | 明确 Xcode 路径或修正默认开发者目录 |
| 代表性任务完整结束 | 构建结果、测试信息和产物检查记录 | 保持节点在试运行范围，定位失败步骤 |
| 按真实启动方式恢复 | 重启后的登录状态、进程和连接记录 | 修正 LaunchAgent、用户权限或团队登录策略 |
这里的关键不是把每个字段都存进复杂的运维系统，而是让另一位管理员能够据记录复现“代理如何启动、为何被选中、用了哪套 Xcode、构建产出了什么”。如果机器重启后代理消失，应重新验证启动与用户会话；如果代理在线但无法匹配构建，则回到代理要求；如果任务运行却用了错误工具链，则复查构建步骤和默认路径。分层处理比反复重装更容易找到故障边界。
常见问题
Mac 上的代理安装完成后，怎样确认已经接入 TeamCity？
检查 buildAgent.properties 中的 Server 地址和代理名称，再看代理日志与 TeamCity 管理界面中的实际状态。若代理处于未授权状态，需由管理员核实后授权；只有连接、授权和启用状态均符合预期，才进入兼容性与构建验收。
代理已连接，但构建配置没有把任务分配给它？
查看构建配置的代理兼容性信息，并对照代理上报参数定位未满足的要求。检查平台、架构、环境变量和工具依赖；调整要求或补齐依赖后重新确认兼容，再触发构建验证任务路由。
macOS 自动启动代理后，重启仍然失联怎么办？
先确认团队配置的启动方式是否要求构建用户登录，再检查该用户的 LaunchAgent、文件归属和代理日志。区分启动项未运行、代理进程未启动以及进程启动后连不上服务器；需要图形会话的工作负载，还要在实际登录条件下单独验证。
Xcode 构建步骤如何确认使用了正确的 Mac 代理？
先看代理兼容性和参数，再核对构建步骤指定的 Xcode 路径、项目或工作区、Scheme 与目标平台。运行代表性构建并核查日志和产物；修改默认 Xcode 后，重启代理并重新检查工具发现结果，不能只用终端测试代替流水线验收。
把 TeamCity 部署到现有 Mac 上，适合已有硬件、需要持续运行且团队能负责维护的情形；但自购节点要承担采购和折旧，已有开发机兼作构建机可能受用户工作负载影响，非 Mac 环境也不能替代需要 Xcode 的原生构建任务。若只是阶段性扩容、临时建立验收环境，或希望先验证托管 Mac 能否进入现有流水线，可结合团队的登录策略、权限要求和任务类型，查看 NowMini 的 Mac 接入方式与远程 Mac 使用说明，再评估是否租赁；若任务长期稳定高负载或依赖必须直连的物理接口，则应优先评估自有 Mac 节点。部署相关的其他排查主题也可从 Mac 使用指南继续查找。
常见问题
在 Mac 上安装 TeamCity 代理后，怎样确认它真的接入了服务器？
在 Mac 上配置正确的 TeamCity Server 地址和唯一代理名称后启动代理，再查看代理日志及 TeamCity 的代理列表。若代理显示未授权，需要管理员先核准；只有显示已连接、已授权且处于启用状态，才继续检查构建兼容性。安装程序结束或进程存在，都不能单独作为接入成功的证据。
Mac 代理已连接，但构建一直排队，应该先检查哪里？
先打开该构建配置的代理兼容性信息，对照代理上报的 macOS、架构、工具和自定义参数，找出未满足的要求。若代理不兼容，修正构建要求或安装缺少的依赖后重新核对；若已兼容但仍不执行，再检查代理是否启用、队列状态及构建路由。
TeamCity 在 macOS 上自动启动代理时，为什么要检查用户登录状态？
TeamCity 文档给出的 macOS 自动启动路径使用 LaunchAgent，并在构建用户登录后启动代理。因此，机器重启后若该用户没有按团队策略登录，代理可能没有启动；而依赖图形会话或用户级环境的任务，也不能只凭启动项存在来判定可运行。应按实际登录策略重启验证。
怎么确认 TeamCity 的 Xcode 构建步骤选中了正确的 Mac 和 Xcode？
先在代理参数中核对平台、架构和已发现的工具，再检查构建配置的代理要求与 Xcode 步骤里的项目或工作区、Scheme、平台以及 Xcode 路径。使用团队的代表性项目运行构建并检查日志与产物；如果通过 xcode-select 切换了默认 Xcode，重启代理后再验证工具发现结果。
为你的苹果平台构建任务配置专属 Mac 节点
NowMini 提供独享 Mac Mini M4 物理节点，可用于部署构建代理、运行自动化任务并稳定复用构建环境。