CodMate 构建与发布教程：Makefile + SwiftPM 打包 Developer ID 签名 DMG 的完整流程

CodMate 是一款 macOS SwiftUI 应用，用于管理 Codex、Claude Code 和 Gemini CLI 的会话。本文带你完整走一遍 CodMate 的构建与发布流程：从 SwiftPM 编译、Makefile目标，到 Developer ID 签名、公证（notarization）和 DMG 打包，帮助你快速上手 macOS 应用发布。

构建环境准备：macOS + Swift 6 工具链 🧰

CodMate 采用纯 SwiftPM 构建（无 Xcode 工程文件），因此环境要求很简单：

💡 本地开发调试不需要签名证书，构建脚本会自动退回到 ad-hoc 签名。

获取源码：一行命令克隆仓库

git clone https://gitcode.com/gh_mirrors/co/codmate cd codmate

项目根目录的 Makefile 是构建入口，输入make help可以查看所有可用目标：

make help

构建体系一览：Makefile 目标速查表 ⚙️

Makefile 中封装了完整的构建流程，核心目标如下：

两个关键环境变量：

• VER：营销版本号（写入CFBundleShortVersionString），如1.4.0；
• ARCH：目标架构，支持arm64、x86_64，也可以写"arm64 x86_64"构建通用二进制。

本地快速调试：make run 一步启动

开发阶段最常用的命令：

make run

它会以本机架构做一次 debug 构建（自动使用 ad-hoc 签名），然后打开build/CodMate.app。如果需要查看运行时日志，Makefile 还提供了几个调试目标：

• make debug：终端前台输出程序日志；
• make debug-app：后台启动应用并流式输出统一日志；
• make debug-logs：在应用运行时实时追踪log stream输出；
• make debug-file：日志同时写入logs/debug.log。

应用打包：make app 背后的构建流程 📦

执行make app VER=1.2.3时，实际调用的是 scripts/create-app-bundle.sh，它完成了完整的打包链路：

1. 多架构编译：对ARCH_MATRIX中的每个架构执行swift build -c release --arch <arch>；
2. 架构校验：用lipo -info检查产物架构是否纯净，多架构时用lipo -create合并为 universal 二进制；
3. 二进制瘦身：默认执行strip（可用STRIP=0关闭）；
4. 组装 .app 包：复制主程序与codmate-notify通知助手、写入Info.plist（Bundle ID 为ai.umate.codmate）；
5. 编译资源：用xcrun actool编译 assets/Assets.xcassets，生成Assets.car与应用图标；
6. 打入打包数据：复制 payload/providers.json、payload/terminals.json、提示词与内部技能等内置资源。

版本号策略由BUILD_NUMBER_STRATEGY控制：

脚本还会把 Git tag、commit 短哈希和 dirty 状态写入Info.plist，方便在"关于"面板中追踪产物来源。

发布流程核心：make dmg 生成签名 DMG 🚀

# 单架构（当前主机架构） make dmg VER=1.4.0 # 指定架构 make dmg VER=1.4.0 ARCH=arm64 # 双架构：同时产出 codmate-arm64.dmg 和 codmate-x86_64.dmg make dmg VER=1.4.0 ARCH="arm64 x86_64"

make dmg调用的是 scripts/macos-build-notarized-dmg.sh，每个架构会经历五个阶段：

1. 打包：复用上面的create-app-bundle.sh生成该架构的CodMate-<arch>.app；
2. 签名：检测到 Developer ID 证书时，先签内部二进制codmate-notify，再签主程序，最后签整个 bundle（带--options runtime硬运行时保护），并用codesign --verify --deep --strict自检。找不到证书时自动降级为 ad-hoc 签名并给出警告；
3. 制作 DMG：优先使用create-dmg生成带 "拖入 Applications" 图标的安装盘，失败或未安装时回退到hdiutil create；
4. 公证：将 DMG 提交给 Apple 公证服务（见下一节）；
5. 装订验证：xcrun stapler staple+stapler validate完成收尾。

产物输出到artifacts/release/目录，文件名为codmate-<arch>.dmg。

公证（Notarization）的两种认证方式

macOS 要求分发给普通用户的 Developer ID 应用必须经过 Apple 公证，否则 Gatekeeper 会拦截。脚本支持两种提交方式，且会自动识别（NOTARY_MODE=auto）：

方式一：Keychain Profile（推荐，CI 友好）

xcrun notarytool store-credentials "AC_PROFILE" \ --team-id YOUR_TEAM_ID \ --apple-id you@apple.com \ --password app-specific-password APPLE_NOTARY_PROFILE="AC_PROFILE" make dmg VER=1.4.0

方式二：Apple ID + 应用专用密码

APPLE_ID="you@apple.com" \ APPLE_PASSWORD="xxxx-xxxx-xxxx-xxxx" \ TEAM_ID="YOURTEAMID" \ make dmg VER=1.4.0

🔒 脚本支持从项目根目录的.env文件读取APPLE_SIGNING_IDENTITY、APPLE_ID、APPLE_PASSWORD、APPLE_TEAM_ID，命令行显式导出的变量优先，无需在 CI 日志中暴露密码。

如果设置了SKIP_NOTARIZATION=1或未提供任何凭据，脚本会跳过公证并明确提示——这样的 DMG 只适合内测，不能公开发布。

分发最后一公里：zip 打包与产物校验

DMG 公证完成后，通常还会再压一层 zip 方便下载渠道分发：

make zip VER=1.4.0

它会在artifacts/release/下为每个 DMG 生成同名.zip。发布前建议手动做一次终检：

codesign --verify --deep --strict build/CodMate.app xcrun stapler validate artifacts/release/codmate-arm64.dmg

此外，项目依赖变更后记得更新第三方许可声明：

make notices

该目标通过 scripts/gen-third-party-notices.py 扫描 Package.resolved 与本地依赖缓存，重新生成THIRD-PARTY-NOTICES.md，任何缺失许可文件的依赖都会让构建失败。

常见问题排查 🛠️

相关文档与源码位置 📚

• 构建总览文档：scripts/BUILD.md
• 构建入口 Makefile：Makefile
• 应用打包脚本：scripts/create-app-bundle.sh
• DMG 签名与公证脚本：scripts/macos-build-notarized-dmg.sh
• SwiftPM 包描述（依赖 GhosttyKit 与 MCP Swift SDK）：Package.swift
• 许可声明生成器：scripts/gen-third-party-notices.py
• 构建与发布说明：README.md

流程回顾：make run日常调试 →make app VER=x.y.z出应用包 →make dmg VER=x.y.z签名并公证出 DMG →make zip生成发布产物。掌握这条流水线，你就能独立完成 CodMate 从源码到可分发 DMG 的完整构建与发布。